oracle.jbo
Interface RowIterator

All Known Subinterfaces:

RowSet, RowSetIterator, ViewObject

public interface RowIterator

Defines simple access to a set of rows.

Since:

JDeveloper 3.0

Field Summary

static int	SLOT_BEFORE_FIRST
static int	SLOT_BEYOND_LAST
static int	SLOT_DELETED
static int	SLOT_VALID

Method Summary

Key	createKey(AttributeList nvp) Given a list of name-value pairs, creates a Key object that matches the key structure for the ViewObject for this RowItertor.
Row	createRow() Creates a new Row object, but does not insert it into the row set.
java.util.Enumeration	enumerateRowsInRange() Gets an Enumeration interface for the row set.
Row[]	findByEntity(int eRowHandle, int maxNumOfRows) Finds and returns view rows that use the entity row, identified by the entity row handle, eRowHandle.
Row[]	findByKey(Key key, int maxNumOfRows) Finds and returns view rows that match the specified key.
Row	first() Designates the first row of the row set as the current row.
Row[]	getAllRowsInRange() Extracts the rows in the range.
Row	getCurrentRow() Accesses the current row.
int	getCurrentRowIndex() Gets the absolute index (not range index) of the current row.
int	getCurrentRowSlot() Gets the slot status of the current row.
int	getFetchedRowCount() Counts the number of rows currently fetched in the row set.
int	getRangeIndexOf(Row row) Get the index of the given row relative to the beginning of the range.
int	getRangeSize() Gets the size of the row set range.
int	getRangeStart() Gets the absolute index of the first row in the row set range.
Row	getRow(Key key) Accesses a row through a unique key.
Row	getRowAtRangeIndex(int index) Accesses a row through its index in the row set.
int	getRowCount() Counts the total number of rows in the row set.
int	getRowCountInRange() Gets the size of the row set range.
boolean	hasNext() Tests for the existence of a row after the current row.
boolean	hasPrevious() Tests for the existence of a row before the current row.
void	insertRow(Row row) Adds a row to the row set, before the current row.
void	insertRowAtRangeIndex(int index, Row row) Adds a row to the row set at the given index.
boolean	isRangeAtBottom() Tests if the row set range is at the end of the result set.
boolean	isRangeAtTop() Tests if the row set range is at the beginning of the result set.
Row	last() Designates the last row of the row set as the current row.
Row	next() Steps forward, designating the next row as the current row.
Row	previous() Steps backward, designating the previous row as the current row.
void	removeCurrentRow() Removes the current Row object from the row set.
void	reset() Clears the "current row" designation and places the iterator in the slot before the first row.
int	scrollRange(int amount) Moves the row set range up or down a given number of rows.
int	scrollRangeTo(Row row, int index) Scrolls the range to place a given row at a given row set index.
boolean	setCurrentRow(Row row) Designates a given row as the current row.
boolean	setCurrentRowAtRangeIndex(int index) Designates a given index as the current row.
int	setRangeSize(int size) Modifies the size of the row set range.
int	setRangeStart(int start) Moves the row set range.
void	setRowValidation(boolean flag) Sets the validation flag on this iterator.

Field Detail

SLOT_VALID

public static final int SLOT_VALID

SLOT_DELETED

public static final int SLOT_DELETED

SLOT_BEFORE_FIRST

public static final int SLOT_BEFORE_FIRST

SLOT_BEYOND_LAST

public static final int SLOT_BEYOND_LAST

Method Detail

next

public Row next()

Steps forward, designating the next row as the current row.

Returns:

a Row object, or null if there is no next row.

previous

public Row previous()

Steps backward, designating the previous row as the current row.

Returns:

a Row object, or null if there is no previous row.

first

public Row first()

Designates the first row of the row set as the current row.

Returns:

a Row object, or null if the row set is empty.

last

public Row last()

Designates the last row of the row set as the current row.

Returns:

a Row object, or null if the row set is empty.

reset

public void reset()

Clears the "current row" designation and places the iterator in the slot before the first row.

A subsequent invocation of next() will cause the first row to become the current row.

hasNext

public boolean hasNext()

Tests for the existence of a row after the current row.

Returns:

true if there is next row.

hasPrevious

public boolean hasPrevious()

Tests for the existence of a row before the current row.

Returns:

true if there is previous row.

getFetchedRowCount

public int getFetchedRowCount()

Counts the number of rows currently fetched in the row set.

Returns:

the number of fetched rows.

getRowCount

public int getRowCount()

Counts the total number of rows in the row set.

Returns:

the number of rows.

getRow

public Row getRow(Key key)

Accesses a row through a unique key.

Parameters:

key - a key.

Returns:

the Row object matching the key.

getRowAtRangeIndex

public Row getRowAtRangeIndex(int index)

Accesses a row through its index in the row set.

Parameters:

index - an integer in the range 0 to getRangeSize() - 1.

Returns:

a Row object, or null if the index is out of range.

getCurrentRow

public Row getCurrentRow()

Accesses the current row.

Returns:

the Row object designated as the current row.

getCurrentRowIndex

public int getCurrentRowIndex()

Gets the absolute index (not range index) of the current row.

Returns:

a row index.

getCurrentRowSlot

public int getCurrentRowSlot()

Gets the slot status of the current row.

Returns:

one of the class constants prefixed by SLOT_.

setCurrentRow

public boolean setCurrentRow(Row row)

Designates a given row as the current row.

Parameters:

row - the new current row.

Returns:

true if the operation succeeded.

createRow

public Row createRow()

Creates a new Row object, but does not insert it into the row set.

Returns:

a new Row object.

insertRow

public void insertRow(Row row)

Adds a row to the row set, before the current row. This method sets the current row to the row just inserted. With respect to eventing, this method call will generate two events (of oracle.jbo.RowSetListener): rowInserted, followed by navigated.

Parameters:

row - the Row object to be added.

removeCurrentRow

public void removeCurrentRow()

Removes the current Row object from the row set.

setRangeSize

public int setRangeSize(int size)

Modifies the size of the row set range.

This method takes effect when the next set of data is fetched. For an example usage of setRangeSize, see setRangeStart.

Parameters:

size - the new number of rows in the row set range.

Returns:

the new size of the range.

See Also:

setRangeStart(int start)

getRangeSize

public int getRangeSize()

Gets the size of the row set range.

Returns:

the number of rows in the range.

getRangeStart

public int getRangeStart()

Gets the absolute index of the first row in the row set range.

The absolute index is 0-based, and is the row's index relative to the entire result set.

Returns:

an index.

setRangeStart

public int setRangeStart(int start)

Moves the row set range.

Note that the index is 0-based. When you call setRangeStart(1), the range start will be positioned at the second table row.

Another behavior of setRangeStart (and also setRangeSize) is that it tries to position the range, so as to fill up the range as much as possible. For example, assume you have View Object vo focused on a table with four rows (A, B, C, D), and you execute the following code:

     vo.setRangeStart(4);
     vo.setRangeSize(3);
     Row[] rows = vo.getAllRowsInRange();
 

In this case, rows contains the last 3 rows (B, C, D). When you call setRangeStart(4), it will try to position you at row 4. Since the index is 0-based, it finds that there is no row. Since the default range size is 1, it will position you to the last row (row index 3).

Then, when you call getRangeSize(3), it tries to fill up the range from the bottom. This is why you get (B, C, D).

Parameters:

start - the absolute index of the new first row in the row set range.

scrollRange

public int scrollRange(int amount)

Moves the row set range up or down a given number of rows.

Parameters:

amount - the number of rows to scroll. A negative value scrolls upward.

Returns:

the number of rows actually scrolled.

scrollRangeTo

public int scrollRangeTo(Row row,
                         int index)

Scrolls the range to place a given row at a given row set index.

Parameters:

row - the row.

index - the row's new index.

Returns:

the actual number of rows scrolled. A negative number indicates that the scroll was scrolled upward.

setCurrentRowAtRangeIndex

public boolean setCurrentRowAtRangeIndex(int index)

Designates a given index as the current row.

Parameters:

index - the index of the new current row.

Returns:

true if the operation succeeded.

insertRowAtRangeIndex

public void insertRowAtRangeIndex(int index,
                                  Row row)

Adds a row to the row set at the given index. The index is relative to the range. I.e., index of 0 would mean to insert before the first row of the range. This method call does not alter the current position of the iterator.

Parameters:

index - the point where row is to be added.

row - the Row object to be added.

getRangeIndexOf

public int getRangeIndexOf(Row row)

Get the index of the given row relative to the beginning of the range.

Parameters:

row - a Row object. or -1 if the row is not in range.

Returns:

the index of row,

getRowCountInRange

public int getRowCountInRange()

Gets the size of the row set range.

Returns:

the number of rows in the range.

isRangeAtBottom

public boolean isRangeAtBottom()

Tests if the row set range is at the end of the result set.

Returns:

true if the last row of the range is the last row of the result set.

isRangeAtTop

public boolean isRangeAtTop()

Tests if the row set range is at the beginning of the result set.

Returns:

true if the first row of the range is the first row of the result set.

enumerateRowsInRange

public java.util.Enumeration enumerateRowsInRange()

Gets an Enumeration interface for the row set.

Returns:

an Enumeration interface.

getAllRowsInRange

public Row[] getAllRowsInRange()

Extracts the rows in the range.

Returns:

an array of Row objects. The size if the array is setViewSize().

findByKey

public Row[] findByKey(Key key,
                       int maxNumOfRows)

Finds and returns view rows that match the specified key.

See ViewObjectImpl#findByKey(key, int) for details.

You do not have to specify all of the keys, but you do have to correctly specify the positions of the keys that you do want. For example, assume that you have 3 Entity Objects in the View Object, and each Entity Object key is 2 parts. If you want to specify only the key attributes for Entity Object 1 and Entity Object 3, you need:

    Object [] keyValues = new Object[6]; // IMPORTANT that length is *6*
    keyValues[0] = eo1_keypart1; // first Entity Object, key part 1
    keyValues[1] = eo1_keypart2; // first Entity Object, key part 2
    keyValues[4] = eo3_keypart1; // third Entity Object, key part 1
    keyValues[5] = eo3_keypart2; // third Entity Object, key part 2
    Key key = new Key(keyValues);
 

Parameters:

key - the key to match.

maxNumOfRows - the maximum size of the array to return, or -1 to return all rows.

Returns:

an array of rows matching the key.

See Also:

ViewObjectImpl.findByKey(Key, int)

createKey

public Key createKey(AttributeList nvp)

Given a list of name-value pairs, creates a Key object that matches the key structure for the ViewObject for this RowItertor. This Key object could be used as a valid argument to findByKey. This Key will have null values for attributes expected in the key structure for this ViewObject, but not found in the given set of name-value pairs.

findByEntity

public Row[] findByEntity(int eRowHandle,
                          int maxNumOfRows)

Finds and returns view rows that use the entity row, identified by the entity row handle, eRowHandle.

Parameters:

eRowHandle - the entity row handle.

maxNumOfRows - the maximum size of the row array to return, or -1 to return all rows.

Returns:

an array of view rows that use the entity row.

setRowValidation

public void setRowValidation(boolean flag)

Sets the validation flag on this iterator. By default a RowIterator validates the current row when navigating to another row. This method can be used to turn this row-validation off by passing 'false' as parameter.

Parameters:

flag - Whether to turn row validation off or not.

Throws:

InvalidOperException - is thrown if this iterator is the default iterator of a ViewObject or a RowSet.