|
Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile Client 11g Release 1 (11.1.1) E17503-02 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface RowIterator
The interface for Row Iterator. A Row Iterator is an iterator over a collection of View rows or Entity rows.
If the user invokes an Entity Association accessor of an Entity going to the many side of the Association, the accessor returns a Row Iterator over Entities.
In the View Row Iterator case, 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:
As mentioned earlier RowSetIterator
extends RowIterator
. The
and ViewObject
interfaces extend RowSet
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(<iterator-name>).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(<rowset-name>). findRowSetIterator(<iterator-name>).next();
BC4J allows the user to create other Row Iterators than the default one. See
for details. These
additional Row Iterators are referred to as "secondary iterators."
RowSet.createRowSetIterator(String)
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. Another aspect that illustrates instability of rowIndex is the same row may appear at a different index, if this ApplicationModule session is passivated and activated. Activation brings in a new collection from the database and that the same row may have moved. For these reasons, 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
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):
next()
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
to append the row at the end of the Row Set.
insertRow(Row)
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
is getCurrentRow()
null
. A method
returns a code indicating whether the currency is on
one of these imaginary slots and if so which kind.
getCurrentRowSlot()
Iteration Modes
RowIterator
supports an "iteration mode" which controls how the range behaves
when it reaches the end of the Row Set.
If the user calls
, 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()
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).
RowSetIterator
,
RowSet
,
ViewObject
,
NavigatableRowIterator
,
ApplicationModule
Field Summary | |
---|---|
static java.lang.Class |
CLASS_INSTANCE
|
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 | |
---|---|
Row |
createAndInitRow(AttributeList nvp)
Creates and initializes a new Row object, but does not insert it into the 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 of all rows in 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. |
RowIterator |
findByViewCriteria(ViewCriteria criteria,
int maxNumOfRows,
int queryMode)
Finds and returns View rows that match the specified View Criteria. |
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 fetched from database into the Row Set collection up to this point. |
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 Iterator range. |
int |
getRangeStart()
Gets the absolute row index of the first row in the Row Set Iterator range. |
Row |
getRow(Key key)
Locates and returns a row by its unique key. |
Row |
getRowAtRangeIndex(int index)
Accesses a row through its range index. |
int |
getRowCount()
Counts the total number of rows in the Row Set. |
int |
getRowCountInRange()
Gets the size of the Row Set Iterator 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)
Inserts a row to the Row Set, before the current row. |
void |
insertRowAtRangeIndex(int index,
Row row)
Inserts a row to the Row Set at the given range index. |
boolean |
isRangeAtBottom()
Tests if the Row Set Iterator range is at the end of the result set. |
boolean |
isRangeAtTop()
Tests if the Row Set Iterator range is at the beginning of the result set. |
boolean |
isRowValidation()
Gets the validation flag on this iterator. |
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. |
Row |
removeCurrentRowAndRetain()
Removes the current Row object from the collection and retain it for insertion into another location. |
void |
removeCurrentRowFromCollection()
Removes the current Row object from the collection. |
void |
reset()
Moves the currency to the slot before the first row. |
int |
scrollRange(int amount)
Moves the Row Set Iterator 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 range 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 Iterator range. |
int |
setRangeStart(int start)
Moves the Row Set Iterator range. |
void |
setRowValidation(boolean flag)
Sets the validation flag on this iterator. |
Field Detail |
---|
static final java.lang.Class CLASS_INSTANCE
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.
returns one of these constants.
getCurrentRowSlot()
SLOT_VALID
means that the RowIterator
is currently on a valid
row. In this case,
should return a
getCurrentRow()
.
Row
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.
returns one of these constants.
getCurrentRowSlot()
SLOT_DELETED
indicates that the user has just delete the current row. The
RowIterator
does not have a current row and
should return getCurrentRow()
null
.
Calling
returns the row next to the row that was
deleted (if there was the next row). Calling next()
returns the row before the row that was deleted (if there was the previous row).
previous()
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.
returns one of these constants.
getCurrentRowSlot()
SLOT_BEFORE_FIRST
indicates that the user has just opened or reset (see
) this iterator. The reset()
RowIterator
does not have a current row and
should
return getCurrentRow()
null
.
Calling
returns the first row in the iterator if a
row exists in the iterator. If the iterator has no row in it, next()
next()
will
return null
and the current slot status will change to
SLOT_BEYOND_LAST
.
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.
returns one of these constants.
getCurrentRowSlot()
SLOT_BEYOND_LAST
indicates that the user has just gone beyond the last row of
the iterator. If the user calls
, followed
immediately by last()
, the currency will be positioned to
the imaginary slot after the last row and the current slot status set to
next()
SLOT_BEYOND_LAST
.
If the iterator has no row in it (empty Row Set), and the current slot status is
SLOT_BEYOND_LAST
, calling
will
put the currency to the imaginary slot before the first row, and the current slot status set
to previous()
SLOT_BEFORE_FIRST
.
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.
returns one of these constants.
getIterMode()
should pass in one of these constants.
setIterMode(int)
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.
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.
returns one of these constants.
getIterMode()
should pass in one of these constants.
setIterMode(int)
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 |
---|
Row next()
next()
is called on an iterator whose Row Set has not yet been
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
.
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
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
for details.
ViewObjectImpl.getFetchMode()
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
will be
sent to ScrollEvent
.
To pick up such an event, the listener object must implement the
RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent)
interface. Further, this listener must be
registered through a call to
RowSetListener
(the listener
object passed in as the parameter to NavigatableRowIterator.addListener(Object)
addListener
).
If the currency is changed, it generates a
and sends it to
NavigationEvent
.
RowSetListener.navigated(oracle.jbo.NavigationEvent)
Row
object, or null
if there
is no next row.
ValidationException
- if row validation fails.Row previous()
previous()
is called on an iterator whose Row Set has not yet been
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
.
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
will be
sent to ScrollEvent
.
To pick up such an event, the listener object must implement the
RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent)
interface. Further, this listener must be
registered through a call to
RowSetListener
(the listener
object passed in as the parameter to NavigatableRowIterator.addListener(Object)
addListener
).
If the currency is changed, it generates a
and sends it to
NavigationEvent
.
RowSetListener.navigated(oracle.jbo.NavigationEvent)
Row
object, or null
if
there is no previous row.
InvalidOperException
- if the Row Set is marked as forward-only, as a foward-only Row Set cannot traverse
rows backwards. See RowSet.setForwardOnly(boolean)
for more info.
ValidationException
- if row validation fails.Row first()
first()
is called on an iterator whose Row Set has not yet been
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
. Note that the act of resetting the currency may cause the
range to scroll upward.
next()
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.,
and/or
ScrollEvent
. See NavigationEvent
for
details.
next()
Row
object, or null
if
there is no first row. In that case (null
return), the current slot
status will be SLOT_BEYOND_LAST
.
InvalidOperException
- if the Row Set is marked as forward-only and the currency is neither on the slot
before the first row nor on the first row. This is because a foward-only Row Set
will not permit the range to scroll upward. See
RowSet.setForwardOnly(boolean)
for more info.
ValidationException
- if row validation fails.Row last()
last()
is called on an iterator whose Row Set has not yet been
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
.
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
for details.
ViewObjectImpl.getFetchMode()
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
will be
sent to ScrollEvent
.
To pick up such an event, the listener object must implement the
RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent)
interface. Further, this listener must be
registered through a call to
RowSetListener
(the listener
object passed in as the parameter to NavigatableRowIterator.addListener(Object)
addListener
).
If the currency is changed, it generates a
and sends it to
NavigationEvent
.
RowSetListener.navigated(oracle.jbo.NavigationEvent)
Row
object, or null
if there
is no last row.
ValidationException
- if row validation fails.void reset()
After this method, the current slot status will be
.
A subsequent invocation of SLOT_BEFORE_FIRST
will cause the first row to become
the current row.
next()
It sends a
to
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 RowSetListener.rangeScrolled(oracle.jbo.ScrollEvent)
interface. Further, this listener must be registered through a call to
RowSetListener
(the listener
object passed in as the parameter to NavigatableRowIterator.addListener(Object)
addListener
).
boolean hasNext()
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
.boolean hasPrevious()
If the Row Set is forward-only, it returns false
.
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
.int getFetchedRowCount()
int getRowCount()
Note that this method retrieves all rows from the database then returns the number of rows in the Row Set collection.
Row getRow(Key key)
If the key being passed in has the row handle, it uses the row handle to locate the row. This
is a quick operation. (A key returned from a call to
contains the row handle.)
Row.getKey()
If the key does not have a row handle, or if the handle look up did not find the row in the View row cache, it performs a linear search through the Row Set collection looking for a match. Hence, this method could take quite a long time to complete.
This method is similar to
in that both methods
return Row(s) that match the given key. However, the user should understand the differences.
First, findByKey() performs random search. getKey() only performs random search if the key has
the row handle portion and if the row with that handle is currently in the Row Set collection.
Otherwise, getKey() does a linear search. Hence, findByKey() is generally faster.
findByKey(Key, int)
However, findByKey() may find the matching Row(s) out of sequence. When a row is not found in the View row cache, findByKey() issues a database query. Matching rows are retrieved and appended to the Row Set collection. For example, suppose the Row Set collection has 200 rows that qualify in the database. Suppose the user retrieved only 10 rows (190 not yet retrieved). Suppose, at this time, the user issues findByKey() that locates the 200-th row (the last row in database result set). That row is appended to the Row Set collection at the 11-th spot. Thus, when you use findByKey(), you may see rows out of sequence. In contrast, getRow() always retrieves rows in sequence.
If the Row Set collection is of any non-trivial size (say over 50), we would recommend findByKey().
findByKey() allows for partial key (only for View Objects that have multiple Entity bases). When a partial key is specified, multiple rows may return. getKey() returns one and only one row (exact match).
key
- the key.
Row getRowAtRangeIndex(int index)
index
- an index in the range: 0
to getRangeSize() - 1
.
null
if the index is out of range.Row getCurrentRow()
int getCurrentRowIndex()
int getCurrentRowSlot()
SLOT_
.boolean setCurrentRow(Row row)
row
- the new current row.
true
if the operation succeeded.Row createAndInitRow(AttributeList nvp)
createRow()
mainly in that this method allows the user to pass in
a list of name-value pairs with which row attributes are initialized.
nvp
is a named value pair. When building an nvp from scratch, use
NameValuePairs
to build a new nvp. Here is an example:
NameValuePairs nvp = new NameValuePairs(); nvp.setAttribute("EmpTyp", "C"); Row row = voEmp.createAndInitRow(nvp);This method is particularly useful when creating a subclass View Row or Entity Row. You can include polymorphic discriminator attribute values in
nvp
and correct subclass
row object will be created.
When this method is called, underlying entities are created. After the new entities are
created, a new view row is created. After that
ViewRowImpl.create(oracle.jbo.AttributeList)
is called with this
nvp
. ViewRowImpl.create(AttributeList)
walks thru the list of
entities and calls EntityImpl.create(AttributeList)
with the same
nvp
for each entity in the view row.
nvp
- a list of name-value pairs.
Row createRow()
void insertRow(Row row)
row
- the Row object to be added.void removeCurrentRow()
void removeCurrentRowFromCollection()
It does not cause the row to be deleted from the database table. It just removes the row from
the row collection. However, once the row is removed, it cannot be used any more. If you want
to remove the current row from collection and insert it elsewhere, call
, change currency to the
desired location, and then call removeCurrentRowAndRetain()
with that
row.
insertRow(oracle.jbo.Row)
Row removeCurrentRowAndRetain()
It does not cause the row to be deleted from the database table. It just removes the row from the row collection.
This method differs from
in that
after the current row is removed from the collection, it can be inserted back into the
collection at another location.
removeCurrentRowFromCollection()
To do so, call
, and get the returning
row. Then, change currency to the desired location, and call
removeCurrentRowAndRetain()
with that row.
insertRow(oracle.jbo.Row)
int setRangeSize(int size)
This method takes effect when the next set of data is fetched. For an example usage of setRangeSize, see setRangeStart.
size
- the new number of rows in the iterator range. Size of 0 is treated same as 1. Size <
-1 is treated same as -1.
setRangeStart(int)
int getRangeSize()
int getRangeStart()
The absolute index is 0-based, and is the row's index relative to the entire result set.
int setRangeStart(int start)
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).
start
- the absolute index of the new first row in the Row Set Iterator range.int scrollRange(int amount)
amount
- the number of rows to scroll. A negative value scrolls upward.
int scrollRangeTo(Row row, int index)
row
- the row.index
- the range index at which the row is to be found.
boolean setCurrentRowAtRangeIndex(int index)
index
- the index of the new current row.
true
if the operation succeeded.void insertRowAtRangeIndex(int index, Row row)
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.
index
- the point where row
is to be added.row
- the Row object to be added.int getRangeIndexOf(Row row)
row
- a Row object. or -1
if the row is not in range.
row
,int getRowCountInRange()
boolean isRangeAtBottom()
true
if the last row of the range is the last row of the result set.boolean isRangeAtTop()
true
if the first row of the range is the first row of the result set.java.util.Enumeration enumerateRowsInRange()
Enumeration
of all rows in the Row Set.
Enumeration
interface.Row[] getAllRowsInRange()
setViewSize()
.Row[] findByKey(Key key, int maxNumOfRows)
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 = myAM.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 to work,
however, the ViewObject's key attribute list must have been set up through a call to
. For
example, suppose we have a View Object with 5 attributes where attribute 0 and 2 are to be its
key attributes.
oracle.jbo.server.ViewObjectImpl#setKeyAttributeDefs(int[])
Then, the following code block will retrieve all rows whose attribute 0 is "PERM" and attribute 2 is 30.
// First set up the key attributes myVO.setKeyAttributeDefs(new int[] { 0, 2 }); // 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 = myAM.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
) 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.
oracle.jbo.ViewObject#setMaxFetchSize(int)
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
with one of them. Care is applied to make sure the same row is not added to the Row Set
collection multiple times.
setCurrentRow(Row)
This method does not fire any navigation event, nor does it move the range or the current row. Also, as rows are added to the Row Set collection, no insertion event fires (as this is analogous to fetching rows).
See
for comparison between this method and
getRow(Key)
getRow(Key)
.
key
- the key to match.maxNumOfRows
- the maximum size of the array to return, or -1 to return all rows.
RowIterator findByViewCriteria(ViewCriteria criteria, int maxNumOfRows, int queryMode)
ViewCriteria
for details on how to build and use a View Criteria.
The queryMode
parameter controls the manner in which the qualifying View rows
are searched. See the QUERY_MODE_...
constants in
for different contants that can be specified
(they can be OR'ed together).
ViewObject
If QUERY_MODE_SCAN_VIEW_ROWS
is specified, the existing View rows in the
current Row Set are scanned for matching rows.
If QUERY_MODE_SCAN_ENTITY_ROWS
is specified, the Entity cache is searched for
qualifying rows. If qualifying rows are found, they are added to the current Row Set. I.e.,
they become part of the current row collection. Internally, a finder View Object is created to
search the Entity cache and to produce View rows from the Entity cache.
If QUERY_MODE_SCAN_DATABASE_TABLES
is specified, a database query is issued to
find matching rows. The View Criteria is converted into a where-clause.
on the finder
View Object is invoked and the query executed.
ViewObject.applyViewCriteria(ViewCriteria)
Upon completion of this operation, the finder View Object is closed and removed.
criteria
- the View Criteria to be used to qualify View rows.maxNumOfRows
- the maximum size of the array to return, or -1 to return all rows. If a
value other than -1 is specified and if the specified number of rows is
reached, the method returns without performing any further operation.queryMode
- the mode in which qualify View rows are scanned. See above for further info.
Key createKey(AttributeList nvp)
Row[] findByEntity(int eRowHandle, int maxNumOfRows)
eRowHandle
.
eRowHandle
- the Entity row handle.maxNumOfRows
- the maximum size of the row array to return, or -1 to return all rows.
void setRowValidation(boolean flag)
flag
- Whether to turn row validation off or not.
InvalidOperException
- is thrown if this iterator is the default iterator of a ViewObject or a RowSet.boolean isRowValidation()
InvalidOperException
- is thrown if this iterator is the default iterator of a ViewObject or a RowSet.int getIterMode()
void setIterMode(int mode)
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".
|
Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile Client 11g Release 1 (11.1.1) E17503-02 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |