oracle.jbo
Interface RowIterator

All Known Subinterfaces:

NavigatableRowIterator, RowSet, RowSetIterator, ViewObject

public interface RowIterator

The interface for Row Iterator. A Row Iterator is an iterator over the View Object's Row Set. It enables the user to retrieve rows out of the Row Set and work with them. RowIterator is the base interface for RowSetIterator.

Within a running BC4J application, one can think of the following containership of application objects:

• Root Application Module contains nested Application Modules.
• An Application Module contains View Objects.
• A View Object contains Row Sets.
• A Row Set contain Row Set Iterators.

As mentioned earlier RowSetIterator extends RowIterator. The ViewObject and RowSet interfaces extend RowIterator as well. Put differently, a View Object, Row Set or Row Set Iterator is a Row Iterator.

A RowSet's implementation of RowIterator delegates to the internal "default" Row Set Iterator. Thus, a RowSet "impersonates" a RowIterator by using the default Row Set Iterator. This simplifies programming much simpler. For example, to get the next row from a Row Set, the user writes:

    RowSet myRowSet;
    ...
    Row row = myRowSet.next();
 

If RowSet did not implement RowIterator through the default RowIterator, he would have had to write something like:

    RowSet myRowSet;
    ...
    Row row = myRowSet.findRowSetIterator().next();
 

Similarly, a ViewObject's implementation of RowSet delegates to the internal "default" Row Set, through which the View Object implements RowIterator. To retrieve the next row, one writes:

    ViewObject myVO;
    ...
    Row row = myVO.next();
 

instead of:

    ViewObject myVO;
    ...
    Row row = myVO.findRowSet().
                   findRowSetIterator().next();
 

BC4J allows the user to create other Row Iterators than the default one. See RowSet.createRowSetIterator(String) for details. These additional Row Iterators are referred to as "secondary iterators."

Ranges

For performance and scalability considerations, if a Row Set contains many rows, it is better to work with a smaller number of rows at one time. Take a grid (table) UI control for an example. Even if the Row Set contains 1,000 rows, the grid may show only 10 rows at a time. RowIterator supports this "sliding window" of visible rows through its "range" facility. Row Iterator range allows the user to set this smaller number of rows (called the "range size") to work with at a time. When necessary, Row Iterator scrolls to bring other rows into its range. The default range size is 1.

Row Index

A row can be identified by its index (0-based) in the Row Set. This index is relative to the entire Row Set and is not affected when the range is scrolled. However, it can be affected when a row is deleted before the row. For example, suppose we have a row of index 20. This means the row is the 21-st row in the Row Set. If the user deletes a row at index 10, the row (of index 20) is no longer the 21-st row. Rather it is now the 20-th row. For this reason, this index is not stable and can change. Thus, the user should use care when managing rows through the index.

When a row is within the Row Iterator's range, it can be identified by its index within the range. To differentiate the index (in the Row Set) discussed in the previous paragraph from this index, we refer to the former as the "absolute index" (or the "row index") and the latter as the "range index." The range index is relevant only for those rows that are currently in the range. Note also that as the range scrolls, the range index can change.

In the above example (where the row's absolute index is 20), suppose the range size is 4 and the range is currently positioned at row index 17. Then, the range contains rows of index 17, 18, 19, 20. This makes the row in the example the 4-th row in the range. The row's range index is 3 (range index is 0-based as well). Suppose the user scrolls down this range by 1 row. The range now contains rows of index 18, 19, 20, 21. The row's range index is now 2 as row of index 20 is the 3-rd row in the range.

Currency and Slots

In addition to the range, a Row Iterator supports the concept of the current row (or the concept of "currency"). It is important to realize that the current row may be null in certain situations. More on this below... Also, the current row may or may not fall in the Row Iterator's range. Some methods, e.g., first(), next(), previous(), last() will scroll the range, so that the current row falls within the range. Others, e.g., scroll(), scrollRangeTo() will not affect the currency at all.

When a Row Iterator is first opened or created, the currency is placed on an imaginary "slot" before the first row. This enables the user to invoke next() on a fresh new Row Iterator and retrieve the first row. For example, the following block of code will print attribute "Ename" for all employees (it does not miss the first row):

    ApplicationModule myAM;
    ...
    ViewObject myVO = myAM.findViewObject("MyEmpVO");
    Row row;

    while ((row = myVO.next()) != null)
    {
       System.out.println("Ename: " + row.getAttribute("Ename"));
    }
 

This imaginary slot also helps in multi-level master-detail View Objects. When the master is first opened or created, the currency is placed on the slot before the first row. This prevents the detail set to be formulated. If the currency were automatically placed on the first row, the detail would have been executed. If this detail was master to another Row Set, that detail would have been executed, etc.

Similar to the slot before the first row, an imaginary slot exists after the last row of the Row Set. This means the user is allowed to call next() even when the currency is on the last row of the Row Set. The currency moves to this slot beyond the last row. Here, the user can call insertRow(Row) to append the row at the end of the Row Set.

If the user deletes the current row of a Row Iterator, the currency "moves" to an imaginary slot where the deleted row used to be. This slot is referred to as the deleted slot. Thus, if the user calls next() after deleting the current row, he gets the row next to the deleted row. Similarly, previous() returns the row before the deleted row.

For example, the following code block deletes all rows in the Row Set:

    ApplicationModule myAM;
    ...
    ViewObject myVO = myAM.findViewObject("MyEmpVO");
    Row row;

    while ((row = myVO.next()) != null)
    {
       myVO.removeCurrentRow();

       // "row.remove()" would have shown the same result
    }
 

When the Row Iterator's currency is on one of these imaginary slots, the current row returned by getCurrentRow() is null. A method getCurrentRowSlot() returns a code indicating whether the currency is on one of these imaginary slots and if so which kind.

Iteration Modes

RowIterator supports an "iteration mode" which controls how the range behaves when it reaches the end of the Row Set.

• Full last page mode: This mode tries to keep the range as full as possible when the range reaches the end.
• Partial last page mode: This mode does not try to keep the range full. Instead, it tries to keep range scrolling to minimum and the range positions more stable. More on these below...

If the user calls last(), the full last page mode will scroll just enough to keep the last page as full as possible. For example, suppose the Row Set has 25 rows and the range size is set at 4. Under the full last page mode, last() will scroll the range to row of index 20, which means the range will have row 21, 22, 23, 24. The range is fully populated with 4 rows.

Under the partial last page mode, no attempt is made to populate the last page. Instead, the range scrolls as if the user kept scrolling by the range size until the end is reached. The range will show (number_of_total_rows % range_size) rows if that number is not zero. If that number is zero, it shows range_size rows. In the above example, last() will show 1 row of row index 24, since 25 % 4 = 1. As the user pages up and down the Row Set, the first row in the range will always be a row whose index is divisible by the range_size. Thus, this mode works well for Web clients which tend to work with a stable set of pages of rows.

With the full last page mode, one cannot expect the pages to remain stable. When the user reaches the end of Row Set, the page may adjust itself to scroll less than range_size.

Another difference in behavior between these two modes is when a row is deleted in the last page. Under the full last page mode, if the user deletes a row in the range when the range had reached the end, the range pulls a row from the top (if one exists) to keep the range full.

For the partial last page mode, no rows are pulled from the top. If the last row of the page is deleted, the range scrolls up range_size (paging up).

Since:

JDevloper 3.0

See Also:

RowSetIterator, RowSet, ViewObject, NavigatableRowIterator, ApplicationModule

Field Summary

Type	Field
static int	ITER_MODE_LAST_PAGE_FULL ITER_MODE_... constants describe the iteration mode for this RowIterator.
static int	ITER_MODE_LAST_PAGE_PARTIAL ITER_MODE_... constants describe the iteration mode for this RowIterator.
static int	SLOT_BEFORE_FIRST SLOT_... constants describe the current slot status for this RowIterator.
static int	SLOT_BEYOND_LAST SLOT_... constants describe the current slot status for this RowIterator.
static int	SLOT_DELETED SLOT_... constants describe the current slot status for this RowIterator.
static int	SLOT_VALID SLOT_... constants describe the current slot status for this RowIterator.

Method Summary

Type	Method
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() Gets the first row in the iterator.
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	getIterMode() Gets the current iteration mode.
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() Gets the last row in the iterator.
Row	next() Gets the next row in the iterator.
Row	previous() Gets the previous row in the iterator.
void	removeCurrentRow() Removes the current Row object from the row set.
void	reset() Moves the currency to 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.
void	setIterMode(int mode) Sets the iteration mode for this Row Iterator.
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_... constants describe the current slot status for this RowIterator. For a detailed discussion, see the above subsection Currency and Slots.

getCurrentRowSlot() returns one of these constants.

SLOT_VALID means that the RowIterator is currently on a valid row. In this case, getCurrentRow() should return a Row.

SLOT_DELETED

public static final int SLOT_DELETED

SLOT_... constants describe the current slot status for this RowIterator. For a detailed discussion, see the above subsection Currency and Slots.

getCurrentRowSlot() returns one of these constants.

SLOT_DELETED indicates that the user has just delete the current row. The RowIterator does not have a current row and getCurrentRow() should return null.

Calling next() returns the row next to the row that was deleted (if there was the next row). Calling previous() returns the row before the row that was deleted (if there was the previous row).

SLOT_BEFORE_FIRST

public static final int SLOT_BEFORE_FIRST

SLOT_... constants describe the current slot status for this RowIterator. For a detailed discussion, see the above subsection Currency and Slots.

getCurrentRowSlot() returns one of these constants.

SLOT_BEFORE_FIRST indicates that the user has just opened or reset (see reset()) this iterator. The RowIterator does not have a current row and getCurrentRow() should return null.

Calling next() returns the first row in the iterator if a row exists in the iterator. If the iterator has no row in it, next() will return null and the current slot status will change to SLOT_BEYOND_LAST.

SLOT_BEYOND_LAST

public static final int SLOT_BEYOND_LAST

SLOT_... constants describe the current slot status for this RowIterator. For a detailed discussion, see the above subsection Currency and Slots.

getCurrentRowSlot() returns one of these constants.

SLOT_BEYOND_LAST indicates that the user has just gone beyond the last row of the iterator. If the user calls last(), followed immediately by next(), the currency will be positioned to the imaginary slot after the last row and the current slot status set to SLOT_BEYOND_LAST. If the iterator has no row in it (empty Row Set), and the current slot status is SLOT_BEYOND_LAST, calling previous() will put the currency to the imaginary slot before the first row, and the current slot status set to SLOT_BEFORE_FIRST.

ITER_MODE_LAST_PAGE_PARTIAL

public static final int ITER_MODE_LAST_PAGE_PARTIAL

ITER_MODE_... constants describe the iteration mode for this RowIterator. For a detailed discussion, see the above subsection Iteration Modes.

getIterMode() returns one of these constants. setIterMode(int) should pass in one of these constants.

ITER_MODE_LAST_PAGE_PARTIAL indicates that the iterator is in the partial last page mode, i.e., the iterator will not try to keep the range full when it reaches the end of the iterator.

ITER_MODE_LAST_PAGE_FULL

public static final int ITER_MODE_LAST_PAGE_FULL

ITER_MODE_... constants describe the iteration mode for this RowIterator. For a detailed discussion, see the above subsection Iteration Modes.

getIterMode() returns one of these constants. setIterMode(int) should pass in one of these constants.

ITER_MODE_LAST_PAGE_FULL indicates that the iterator is in the full last page mode, i.e., the iterator will try to keep the range as full as possible when it reaches the end of the iterator.

Method Detail

next

public Row next()

Gets the next row in the iterator. If next() is called on an iterator whose Row Set has not yet been #oracle.jbo.RowSet.executeQuery()'ed, the Row Set's query is executed. Thus, the user does not need to call executeQuery() himself before calling next(). We refer to this as implicit query execution or implicit Row Set execution.

Before moving to the next row, next() validates the current row (if the iterator has a current row) through a call to #oracle.jbo.Row.validate().

If the currency is on the last row of the range and next() is called, the range is scolled down by one row to bring the next row into the visible range. In particular, if the range size is 1, next() scrolls the range down by 1 row.

When this method is called, the current row of the iterator may be outside the range. (Note that the current row does not have to be within the range.) If so, next() will scroll the range, so that the row that will be the current row at the conclusion of this method will be positioned in the middle of the range.

If the iterator is just opened or reset (see reset()), next() will return the first row if one exists. In this situation, next() is functionally equivalent to first().

If the iterator is at the last row of the Row Set, next() push the currency into the imaginary slot after the last row. This will set the current slot status to SLOT_BEYOND_LAST.

When the next row is required, a check is made to see if the row has already been brought into cache. If not, the row is fetched from database. Note that the View Object's fetch mode affects how rows are fetched from database into cache. See #oracle.jbo.server.ViewObjectImpl.getFetchMode() for details.

If successful, this method designates the next row as the current row (the currency finally moves).

This method generates events to notify the changes to the iterator. If scrolling occurs because of conditions described above, a #oracle.jbo.ScrollEvent will be sent to #oracle.jbo.RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent). To pick up such an event, the listener object must implement the #oracle.jbo.RowSetListener interface. Further, this listener must be registered through a call to #oracle.jbo.NavigatableRowIterator.addListener(Object) (the listener object passed in as the parameter to addListener).

If the currency is changed, it generates a #oracle.jbo.NavigationEvent and sends it to #oracle.jbo.RowSetListener.navigated(oracle.jbo.NavigationEvent).

Returns:

the next #oracle.jbo.Row object, or null if there is no next row.

previous

public Row previous()

Gets the previous row in the iterator. If previous() is called on an iterator whose Row Set has not yet been #oracle.jbo.RowSet.executeQuery()'ed, the Row Set's query is executed. Thus, the user does not need to call executeQuery() himself before calling previous(). We refer to this as implicit query execution or implicit Row Set execution.

Before moving to the previous row, previous() validates the current row (if the iterator has a current row) through a call to #oracle.jbo.Row.validate().

If the currency is on the first row of the range and previous() is called, the range is scolled up by one row to bring the previous row into the visible range. In particular, if the range size is 1, previous() scrolls the range up by 1 row.

When this method is called, the current row of the iterator may be outside the range. (Note that the current row does not have to be within the range.) If so, previous() will scroll the range, so that the row that will be the current row at the conclusion of this method will be positioned in the middle of the range.

If the iterator is just opened or reset (see reset()), previous() will null as the currency is already on the imaginary slot before the first row.

If the iterator is at the first row of the Row Set, previous() push the currency into the imaginary slot before the first row. This will set the current slot status to SLOT_BEFORE_FIRST.

If successful, this method designates the previous row as the current row (the currency finally moves).

This method generates events to notify the changes to the iterator. If scrolling occurs because of conditions described above, a #oracle.jbo.ScrollEvent will be sent to #oracle.jbo.RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent). To pick up such an event, the listener object must implement the #oracle.jbo.RowSetListener interface. Further, this listener must be registered through a call to #oracle.jbo.NavigatableRowIterator.addListener(Object) (the listener object passed in as the parameter to addListener).

If the currency is changed, it generates a #oracle.jbo.NavigationEvent and sends it to #oracle.jbo.RowSetListener.navigated(oracle.jbo.NavigationEvent).

Returns:

the previous #oracle.jbo.Row object, or null if there is no previous row.

first

public Row first()

Gets the first row in the iterator. If first() is called on an iterator whose Row Set has not yet been #oracle.jbo.RowSet.executeQuery()'ed, the Row Set's query is executed. Thus, the user does not need to call executeQuery() himself before calling first(). We refer to this as implicit query execution or implicit Row Set execution.

This method checks to see if the currency is not on the first row. If not, it resets the currency to the imaginary slot before the first row and then calls next(). Note that the act of resetting the currency may cause the range to scroll upward.

If the currency is on the slot before the first row, it simply calls next(). In this case, first() is equivalent to next().

If the currency is already on the first row, nothing happens.

If first() is called on an empty Row Set (a Row Set that has no row), the currency is set to the slot after the last row, and null is returned.

This method generates events to notify the changes to the iterator, e.g., #oracle.jbo.ScrollEvent and/or #oracle.jbo.NavigationEvent. See next() for details.

Returns:

the first #oracle.jbo.Row object, or null if there is no first row. In that case (null return), the current slot status will be SLOT_BEYOND_LAST.

last

public Row last()

Gets the last row in the iterator. If last() is called on an iterator whose Row Set has not yet been #oracle.jbo.RowSet.executeQuery()'ed, the Row Set's query is executed. Thus, the user does not need to call executeQuery() himself before calling last(). We refer to this as implicit query execution or implicit Row Set execution.

Before moving to the last row, last() validates the current row (if the iterator has a current row) through a call to #oracle.jbo.Row.validate().

This method retrieves all rows from the Row Set and scrolls (if necessary) to the last row. If some of these rows have not yet been fetched from database, it fetches them. The View Object's fetch mode affects how rows are fetched from database into cache. See #oracle.jbo.server.ViewObjectImpl.getFetchMode() for details.

If successful, this method designates the last row as the current row.

If last() is called on an empty Row Set, the currency moves to the slot beyond the last row. The current slot status is set to SLOT_BEYOND_LAST.

The caller of this method should be aware that it may take a long time to complete as all rows from the Row Set are fetched.

The number of rows in the range at the completion of this method is affected by the "iteration mode". See Iteration Modes above for details.

This method generates events to notify the changes to the iterator. If scrolling occurs because of conditions described above, a #oracle.jbo.ScrollEvent will be sent to #oracle.jbo.RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent). To pick up such an event, the listener object must implement the #oracle.jbo.RowSetListener interface. Further, this listener must be registered through a call to #oracle.jbo.NavigatableRowIterator.addListener(Object) (the listener object passed in as the parameter to addListener).

If the currency is changed, it generates a #oracle.jbo.NavigationEvent and sends it to #oracle.jbo.RowSetListener.navigated(oracle.jbo.NavigationEvent).

Returns:

the last #oracle.jbo.Row object, or null if there is no last row.

reset

public void reset()

Moves the currency to the slot before the first row.

After this method, the current slot status will be SLOT_BEFORE_FIRST. A subsequent invocation of next() will cause the first row to become the current row.

It sends a #oracle.jbo.ScrollEvent to #oracle.jbo.RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent) if the currency was not on the first row or on the slot before the first row. To pick up such an event, the listener object must implement the #oracle.jbo.RowSetListener interface. Further, this listener must be registered through a call to #oracle.jbo.NavigatableRowIterator.addListener(Object) (the listener object passed in as the parameter to addListener).

hasNext

public boolean hasNext()

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

Returns:

true if there is a next row. Specifically, if the Row Set is empty or if the currency is on the last row or the slot after the last row (current slot status == SLOT_BEYOND_LAST), it returns false. Otherwise, true.

hasPrevious

public boolean hasPrevious()

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

If the Row Set is forward-only, it returns false.

Returns:

true if there is a previous row. Specifically, if the Row Set is empty or forward-only or if the currency is on the first row or the slot before the first row (current slot status == SLOT_BEFORE_FIRST), it returns false. Otherwise, true.

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. Size of 0 is treated same as 1. Size < -1 is treated same as -1.

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. Allowed values for index is 0 to range size. If index equals range size, the row is inserted right after the last row in the range. This method call does not alter the current position of the iterator, nor does it affect the range position.

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.

getIterMode

public int getIterMode()

Gets the current iteration mode. See Iteration Modes above for details on iteration mode which controls how the range behaves when it reaches the end of the Row Set.

Returns:

ITER_MODE_LAST_PAGE_PARTIAL if the iteration mode is "partial-last-page", ITER_MODE_LAST_PAGE_FULL if it is "full-last-page".

setIterMode

public void setIterMode(int mode)

Sets the iteration mode for this Row Iterator. See Iteration Modes above for details on iteration mode which controls how the range behaves when it reaches the end of the Row Set.

Parameters:

mode - should be ITER_MODE_LAST_PAGE_PARTIAL if the iteration mode is to be "partial-last-page", ITER_MODE_LAST_PAGE_FULL if it is to be "full-last-page".