oracle.jbo.common.ws
Class WSRowSetIteratorBase

java.lang.Object
  |
  +--oracle.jbo.common.ws.WSObject
        |
        +--oracle.jbo.common.ws.WSRowSetIteratorBase

All Implemented Interfaces:

NavigatableRowIterator, RowIterator, RowSetIterator, java.io.Serializable

Direct Known Subclasses:

WSRowSetImpl, WSRowSetIteratorImpl, WSViewObjectImpl

public abstract class WSRowSetIteratorBase

extends WSObject

implements RowSetIterator, java.io.Serializable

See Also:

Serialized Form

Field Summary

Fields inherited from interface oracle.jbo.RowIterator

ITER_MODE_LAST_PAGE_FULL, ITER_MODE_LAST_PAGE_PARTIAL, SLOT_BEFORE_FIRST, SLOT_BEYOND_LAST, SLOT_DELETED, SLOT_VALID

Method Summary

void	addListener(java.lang.Object listener) Adds a subscriber (listener) to be notified of RowSetListener events generated by this row set iterator.
void	addManagementListener(RowSetManagementListener listener) Adds a subscriber (listener) to be notified of RowSetManagementListener events generated by this Row Set Iterator.
abstract void	closeRowSetIterator() Closes this row set iterator.
Row	createAndInitRow(AttributeList nvp)
abstract RowSet	createDetailRowSet(java.lang.String rsName, java.lang.String linkDefName) Creates a detail Row Set.
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.
abstract RowSet[]	getDetailRowSets() Gets an array of detail Row Sets for which this Iterator is the master.
int	getEstimatedRangePageCount() Returns getEstimatedRowCount()/rangePageSize, if rangeSize > 0.
int	getFetchedRowCount() Counts the number of rows fetched from database into the Row Set collection up to this point.
abstract int	getIterMode() Gets the current iteration mode.
java.lang.String	getName() Gets the name of the Iterator.
Row[]	getNextRangeSet() Gets the next set of rows in the range.
Row[]	getPreviousRangeSet() Gets the previous set of rows in the range.
int	getRangeIndexOf(Row row) Get the index of the given row relative to the beginning of the range.
abstract int	getRangeSize() Gets the size of the row set range.
abstract 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.
abstract RowSet	getRowSet() Gets the Row Set that this Iterator belongs to.
abstract java.lang.Object	getSyncLock() Gets the locking object for this Row Set Iterator.
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	isConnected()
boolean	isNameGenerated() Tests if the Iterator's name was generated by the system.
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	removeCurrentRowFromCollection() Removes the current Row object from the collection.
void	removeListener(java.lang.Object listener) Removes a subscriber (listener) for RowSetListener events generated by this row set iterator.
void	removeManagementListener(RowSetManagementListener listener) Removes a subscriber (listener) for RowSetManagementListener events generated by this row set iterator.
void	reset() Moves the currency to the slot before the first row.
abstract int	scrollRange(int amount) Moves the row set range up or down a given number of rows.
abstract int	scrollRangeTo(Row row, int index) Scrolls the range to place a given row at a given row set index.
int	scrollToRangePage(int pageIndex) Moves the row set range start to the given page index where every page consists of RangeSize number of rows.
boolean	setCurrentRow(Row row) Designates a given row as the current row.
boolean	setCurrentRowAtRangeIndex(int index) Designates a given index as the current row.
abstract void	setIterMode(int mode) Sets the iteration mode for this Row Iterator.
abstract int	setRangeSize(int size) Modifies the size of the row set range.
abstract int	setRangeStart(int start) Moves the row set range.
abstract void	setRowValidation(boolean flag) Sets the validation flag on this iterator.

Methods inherited from class oracle.jbo.common.ws.WSObject

getFullName, getId, getImplObject, getParent, setImplObject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isConnected

public final boolean isConnected()

getName

public final java.lang.String getName()

Description copied from interface: RowSetIterator

Gets the name of the Iterator. If this Row Set Iterator is the default iterator of the Row Set, then the Iterator's name by default is the same as the Row Set name. For a secondary (non-default) Iterator of the Row Set, the name is assigned when the Row Set Iterator is created. See RowSet.createRowSetIterator(String) for more info.

Specified by:

getName in interface RowSetIterator

Specified by:

getName in class WSObject

Returns:

the Row Set Iterator name.

isNameGenerated

public final boolean isNameGenerated()

Description copied from interface: RowSetIterator

Tests if the Iterator's name was generated by the system.

Specified by:

isNameGenerated in interface RowSetIterator

Returns:

true if the name was generated by the system. false if the name was given by the user and not generated by the system.

getNextRangeSet

public final Row[] getNextRangeSet()

Description copied from interface: RowSetIterator

Gets the next set of rows in the range. This method is good for processing rows in a range-ful fashion. Suppose the Row Set has 20 rows and the Iterator range size is 10. Suppose further that the Iterator is showing rows 0 through 9 (0-based indexing). Calling getNextRangeSet() will return rows 10 through 19.

If the next range set does not have enough rows to fill up the range, getNextRangeSet() returns a partially filled range. That is, this method operates as if the iteration mode is RowIterator.ITER_MODE_LAST_PAGE_PARTIAL.

If there is no more rows, this method returns an empty array (an array of length 0).

While obtaining the next range set, the range will be scrolled. This causes a #oracle.jbo.ScrollEvent to 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).

After the next range set is obtained, the method sets the first Row of the range as the current row. This may fire a #oracle.jbo.NavigationEvent and sends it to #oracle.jbo.RowSetListener.navigated(oracle.jbo.NavigationEvent).

Specified by:

getNextRangeSet in interface RowSetIterator

Returns:

an array of Rows in the next range set. An array of length 0 if there are no more rows.

getPreviousRangeSet

public final Row[] getPreviousRangeSet()

Description copied from interface: RowSetIterator

Gets the previous set of rows in the range. This method is good for processing rows in a range-ful fashion. Suppose the Row Set has 20 rows and the Iterator range size is 10. Suppose further that the Iterator is showing rows 10 through 19 (0-based indexing). Calling getPreviousRangeSet() will return rows 0 through 9.

If there is no more rows, this method returns an empty array (an array of length 0).

While obtaining the previous range set, the range will be scrolled. This causes a #oracle.jbo.ScrollEvent to 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).

After the previous range set is obtained, the method sets the first Row of the range as the current row. This may fire a #oracle.jbo.NavigationEvent and sends it to #oracle.jbo.RowSetListener.navigated(oracle.jbo.NavigationEvent).

Specified by:

getPreviousRangeSet in interface RowSetIterator

Returns:

an array of Rows in the previous range set. An array of length 0 if there are no more rows.

getEstimatedRangePageCount

public int getEstimatedRangePageCount()

Description copied from interface: RowSetIterator

Returns getEstimatedRowCount()/rangePageSize, if rangeSize > 0. For rangeSize <= 0, returns 1.

This number may fluxuate when the View Object is syncronized with its Entity Object.

Specified by:

getEstimatedRangePageCount in interface RowSetIterator

Returns:

the number of range-pages that this RowSet collection has.

scrollToRangePage

public int scrollToRangePage(int pageIndex)

Description copied from interface: RowSetIterator

Moves the row set range start to the given page index where every page consists of RangeSize number of rows. PageIndex should start at page number 1. This method calculates the rowIndex that should start at that page and then scrolls the iterator to start at that row by using the following calculation:

(rangeSize * (pageSize-1)) - getRangeStart();

Specified by:

scrollToRangePage in interface RowSetIterator

Parameters:

pageIndex - the page number to go to in the result set.

Returns:

the number of rows actually scrolled.

getRowSet

public abstract RowSet getRowSet()

Description copied from interface: RowSetIterator

Gets the Row Set that this Iterator belongs to.

Specified by:

getRowSet in interface RowSetIterator

Returns:

the owning Row Set.

getDetailRowSets

public abstract RowSet[] getDetailRowSets()

Description copied from interface: RowSetIterator

Gets an array of detail Row Sets for which this Iterator is the master.

In a master-detail relationship in an Application Module, the master in reality is a Row Set Iterator. (Though we often speak of master View Object, in reality, it is the Iterator behind the View Object which is playing the role of the master). Whenever the currency of this master Iterator moves, the detail Row Sets are re-executed to show related Rows.

Calling this method returns an array of Row Sets that are related to this Iterator as detail Row Sets.

Specified by:

getDetailRowSets in interface RowSetIterator

Returns:

an array of detail RowSet.

createDetailRowSet

public abstract RowSet createDetailRowSet(java.lang.String rsName,
                                          java.lang.String linkDefName)

Description copied from interface: RowSetIterator

Creates a detail Row Set. See RowSetIterator.getDetailRowSets() for explanation of detail Row Sets.

This method creates a new detail Row Set for this Iterator.

Specified by:

createDetailRowSet in interface RowSetIterator

Parameters:

rsName - the name of the new detail Row Set.

linkDefName - the name of a View Link definition. This View Link chooses the relationship in which this Iterator is the master and the new Row Set is the detail. It must be a fully qualified name (including the package name).

Returns:

the new detail Row Set.

addManagementListener

public final void addManagementListener(RowSetManagementListener listener)

Description copied from interface: RowSetIterator

Adds a subscriber (listener) to be notified of RowSetManagementListener events generated by this Row Set Iterator.

Specified by:

addManagementListener in interface RowSetIterator

Parameters:

listener - the subscriber to be added. It should implement RowSetManagementListener.

removeManagementListener

public final void removeManagementListener(RowSetManagementListener listener)

Description copied from interface: RowSetIterator

Removes a subscriber (listener) for RowSetManagementListener events generated by this row set iterator.

Specified by:

removeManagementListener in interface RowSetIterator

Parameters:

listener - the subscriber to be removed.

closeRowSetIterator

public abstract void closeRowSetIterator()

Description copied from interface: RowSetIterator

Closes this row set iterator. If this row set iterator is a master in a master-detail relationship, closeRowSetIterator closes all detail row sets.

After that, it fires a RowSetManagementListener.iteratorClosed() event to its RowSetManagementListener's.

Then, it deregisters this row set iterator from the owning row set, and deregisters all its listeners.

Specified by:

closeRowSetIterator in interface RowSetIterator

getSyncLock

public abstract java.lang.Object getSyncLock()

Description copied from interface: RowSetIterator

Gets the locking object for this Row Set Iterator. Actually, this method locks the Application Module to which this Row Set Iterator belongs. See ApplicationModule.getSyncLock() for details.

Specified by:

getSyncLock in interface RowSetIterator

Returns:

the locking object.

addListener

public final void addListener(java.lang.Object listener)

Description copied from interface: NavigatableRowIterator

Adds a subscriber (listener) to be notified of RowSetListener events generated by this row set iterator.

Specified by:

addListener in interface NavigatableRowIterator

Parameters:

listener - the subscriber to be added. It should implement RowSetListener.

removeListener

public final void removeListener(java.lang.Object listener)

Description copied from interface: NavigatableRowIterator

Removes a subscriber (listener) for RowSetListener events generated by this row set iterator.

Specified by:

removeListener in interface NavigatableRowIterator

Parameters:

listener - the subscriber to be removed.

next

public final Row next()

Description copied from interface: RowIterator

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 RowIterator.reset()), next() will return the first row if one exists. In this situation, next() is functionally equivalent to RowIterator.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 the collection. If not, the row is fetched from database. Note that the View Object's fetch mode affects how rows are fetched from database into the collection. 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).

Specified by:

next in interface RowIterator

Returns:

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

previous

public final Row previous()

Description copied from interface: RowIterator

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 RowIterator.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).

Specified by:

previous in interface RowIterator

Returns:

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

first

public final Row first()

Description copied from interface: RowIterator

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 RowIterator.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 RowIterator.next() for details.

Specified by:

first in interface RowIterator

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 RowIterator.SLOT_BEYOND_LAST.

last

public final Row last()

Description copied from interface: RowIterator

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 the collection. 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 RowIterator.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).

Specified by:

last in interface RowIterator

Returns:

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

reset

public final void reset()

Description copied from interface: RowIterator

Moves the currency to the slot before the first row.

After this method, the current slot status will be RowIterator.SLOT_BEFORE_FIRST. A subsequent invocation of RowIterator.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).

Specified by:

reset in interface RowIterator

hasNext

public final boolean hasNext()

Description copied from interface: RowIterator

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

Specified by:

hasNext in interface RowIterator

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 == RowIterator.SLOT_BEYOND_LAST), it returns false. Otherwise, true.

hasPrevious

public final boolean hasPrevious()

Description copied from interface: RowIterator

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

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

Specified by:

hasPrevious in interface RowIterator

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 == RowIterator.SLOT_BEFORE_FIRST), it returns false. Otherwise, true.

getFetchedRowCount

public final int getFetchedRowCount()

Description copied from interface: RowIterator

Counts the number of rows fetched from database into the Row Set collection up to this point.

Specified by:

getFetchedRowCount in interface RowIterator

Returns:

the number of rows fetched.

getRowCount

public final int getRowCount()

Description copied from interface: RowIterator

Counts the total number of rows in the Row Set.

Note that this method retrieves all rows from the database then returns the number of rows in the Row Set collection.

Specified by:

getRowCount in interface RowIterator

Returns:

the number of rows.

getRow

public final Row getRow(Key key)

Description copied from interface: RowIterator

Accesses a row through a unique key.

Specified by:

getRow in interface RowIterator

Parameters:

key - a key.

Returns:

the Row object matching the key.

getRowAtRangeIndex

public final Row getRowAtRangeIndex(int index)

Description copied from interface: RowIterator

Accesses a row through its index in the row set.

Specified by:

getRowAtRangeIndex in interface RowIterator

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 final Row getCurrentRow()

Description copied from interface: RowIterator

Accesses the current row.

Specified by:

getCurrentRow in interface RowIterator

Returns:

the Row object designated as the current row.

getCurrentRowIndex

public final int getCurrentRowIndex()

Description copied from interface: RowIterator

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

Specified by:

getCurrentRowIndex in interface RowIterator

Returns:

a row index.

getCurrentRowSlot

public final int getCurrentRowSlot()

Description copied from interface: RowIterator

Gets the slot status of the current row.

Specified by:

getCurrentRowSlot in interface RowIterator

Returns:

one of the class constants prefixed by SLOT_.

setCurrentRow

public final boolean setCurrentRow(Row row)

Description copied from interface: RowIterator

Designates a given row as the current row.

Specified by:

setCurrentRow in interface RowIterator

Parameters:

row - the new current row.

Returns:

true if the operation succeeded.

createAndInitRow

public final Row createAndInitRow(AttributeList nvp)

Specified by:

createAndInitRow in interface RowIterator

createRow

public final Row createRow()

Description copied from interface: RowIterator

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

Specified by:

createRow in interface RowIterator

Returns:

a new Row object.

insertRow

public final void insertRow(Row row)

Description copied from interface: RowIterator

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.

Specified by:

insertRow in interface RowIterator

Parameters:

row - the Row object to be added.

removeCurrentRow

public final void removeCurrentRow()

Description copied from interface: RowIterator

Removes the current Row object from the row set.

Specified by:

removeCurrentRow in interface RowIterator

removeCurrentRowFromCollection

public final void removeCurrentRowFromCollection()

Description copied from interface: RowIterator

Removes the current Row object from the collection.

It does not cause the row to be deleted from the database table. It simply removes the row from the row collection.

Specified by:

removeCurrentRowFromCollection in interface RowIterator

setRangeSize

public abstract int setRangeSize(int size)

Description copied from interface: RowIterator

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.

Specified by:

setRangeSize in interface RowIterator

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:

RowIterator.setRangeStart(int)

getRangeSize

public abstract int getRangeSize()

Description copied from interface: RowIterator

Gets the size of the row set range.

Specified by:

getRangeSize in interface RowIterator

Returns:

the number of rows in the range.

getRangeStart

public abstract int getRangeStart()

Description copied from interface: RowIterator

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.

Specified by:

getRangeStart in interface RowIterator

Returns:

an index.

setRangeStart

public abstract int setRangeStart(int start)

Description copied from interface: RowIterator

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).

Specified by:

setRangeStart in interface RowIterator

Parameters:

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

scrollRange

public abstract int scrollRange(int amount)

Description copied from interface: RowIterator

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

Specified by:

scrollRange in interface RowIterator

Parameters:

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

Returns:

the number of rows actually scrolled.

scrollRangeTo

public abstract int scrollRangeTo(Row row,
                                  int index)

Description copied from interface: RowIterator

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

Specified by:

scrollRangeTo in interface RowIterator

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 final boolean setCurrentRowAtRangeIndex(int index)

Description copied from interface: RowIterator

Designates a given index as the current row.

Specified by:

setCurrentRowAtRangeIndex in interface RowIterator

Parameters:

index - the index of the new current row.

Returns:

true if the operation succeeded.

insertRowAtRangeIndex

public final void insertRowAtRangeIndex(int index,
Row row)

Description copied from interface: RowIterator

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.

Specified by:

insertRowAtRangeIndex in interface RowIterator

Parameters:

index - the point where row is to be added.

row - the Row object to be added.

getRangeIndexOf

public final int getRangeIndexOf(Row row)

Description copied from interface: RowIterator

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

Specified by:

getRangeIndexOf in interface RowIterator

Parameters:

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

Returns:

the index of row,

getRowCountInRange

public final int getRowCountInRange()

Description copied from interface: RowIterator

Gets the size of the row set range.

Specified by:

getRowCountInRange in interface RowIterator

Returns:

the number of rows in the range.

isRangeAtBottom

public final boolean isRangeAtBottom()

Description copied from interface: RowIterator

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

Specified by:

isRangeAtBottom in interface RowIterator

Returns:

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

isRangeAtTop

public final boolean isRangeAtTop()

Description copied from interface: RowIterator

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

Specified by:

isRangeAtTop in interface RowIterator

Returns:

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

enumerateRowsInRange

public final java.util.Enumeration enumerateRowsInRange()

Description copied from interface: RowIterator

Gets an Enumeration interface for the row set.

Specified by:

enumerateRowsInRange in interface RowIterator

Returns:

an Enumeration interface.

getAllRowsInRange

public final Row[] getAllRowsInRange()

Description copied from interface: RowIterator

Extracts the rows in the range.

Specified by:

getAllRowsInRange in interface RowIterator

Returns:

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

findByKey

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

Description copied from interface: RowIterator

Finds and returns View rows that match the specified key.

If this View Object has multiple Entity Object bases, the key need not be specified for all. However, if a key is specified for n-th Entity Object, and if this Entity Object's primary key consists of multiple parts, all parts of the key must be specified.

If not all Entity keys are included, multiple rows may match the partial key. The maxNumOfRows parameter is used to specify the maximum number of rows to return.

For example, suppose the View Object has Emp and DeptLocation as its Entity Object bases. Suppose further that Emp has a one part primary key (employee number) and DeptLocation has a two part primary key (dept name and location).

The user can make the following call to look for all employees working in ACCOUNTING's NEW YORK office:

    // The key will consist of 3 parts.  The first part is
    // for the employee number (which is null, meaning not
    // specified).  The second part is the department name.
    // The third is the location.
    Object [] keyValues = new Object[3];

    keyValues[0] = null;  // All employees
    keyValues[1] = "ACCOUNTING";
    keyValues[4] = "NEW YORK"; // third Entity Object, key part 1

    Row[] rows = myVO.findViewObject(new Key(keyValues), -1);

In this example, if you were to include the key for DeptLocation, you must specify both key parts.

Note that the position of the key must patch the order of the Entity Object bases and their keys. In the above example, keyValues[0] is always the employee number. You cannot specify the employee number in keyValues[1] or keyValues[2].

This method works even on a View Object which has no Entity Object base. For this work, however, the ViewObject's key attribute list must have been set up through a call to #oracle.jbo.server.ViewObjectImpl.setAttributeDefs(int[]). For example, suppose we have a View Object with 5 attributes where attribute 0 and 2 are to be its key attributes.

Then, the following code block will retrieve all rows whose attribute 0 is "PERM" and attribute 2 is 30.

    // The key will consist of 2 parts.  The first part is
    // for attribtue 0 and the second is for attribute 2.
    Object [] keyValues = new Object[2];

    keyValues[0] = "PERM";
    keyValues[1] = new Integer(30);

    Row[] rows = myVO.findViewObject(new Key(keyValues), -1);

Internally, findByKey() works as follows for a View Object with Entity Object bases: It takes the first non-null entity key from key. It uses it to find the Entity row in the cache. If it finds it, then it looks at all View rows in the Row Set collection that uses that Entity row and apply the remaining keys to qualify them. It may or may not find as many rows as requested.

If the requested number of rows have been found, the array returns. Otherwise, a check is made to see if the View Object's fetch size is unlimited (which is -1, see #ViewObject.setMaxFetchSize()) and the Row Set has fetched all the rows out of database into its collection. If this is the case, we return the array even if the requested number of rows have not been found. This is because these conditions imply that all rows have been brought into Row Set collection and no further search is necessary.

Otherwise (the requested number of rows not yet found and the Row Set has not yet fetched all rows or the fetch size is not -1), the search continues. We now use the key build a where-clause for an internal View Object. That where-clause is applied and qualifying rows are retrieved from it to find the requested number of rows.

For a View Object which has no Entity Object base, we simply skip the step of looking in the Entity Object cache. Other than that, the logic is applied.

As new rows are retrieved from database they are added to the Row Set collection. Thus, the user can work with these rows immediately, e.g., call RowIterator.setCurrentRow(Row) with one of them. Care is applied to make sure the same row is not added to the Row Set collection multiple times.

This method does not fire any navigation event, nor does it move the range or the current row. However, if rows are added to the Row Set collection (as described above), it will send a #oracle.jbo.InsertEvent to #oracle.jbo.RowSetListener.rowInserted(oracle.jbo.InsertEvent). 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).

Specified by:

findByKey in interface RowIterator

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.

createKey

public final Key createKey(AttributeList nvp)

Description copied from interface: RowIterator

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.

Specified by:

createKey in interface RowIterator

findByEntity

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

Description copied from interface: RowIterator

Finds and returns View rows that use the Entity row, identified by the Entity row handle, eRowHandle.

Specified by:

findByEntity in interface RowIterator

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 abstract void setRowValidation(boolean flag)

Description copied from interface: RowIterator

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.

Specified by:

setRowValidation in interface RowIterator

Parameters:

flag - Whether to turn row validation off or not.

getIterMode

public abstract int getIterMode()

Description copied from interface: RowIterator

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.

Specified by:

getIterMode in interface RowIterator

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 abstract void setIterMode(int mode)

Description copied from interface: RowIterator

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.

Specified by:

setIterMode in interface RowIterator

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".