Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.jbo
Interface RowSet

All Superinterfaces:
  NavigatableRowIterator, Properties, RowIterator, RowSetIterator, VariableManagerOwner, XMLInterface

All Known Subinterfaces:
  ViewObject, ViewObjectDynAttr, WSRowSet

All Known Implementing Classes:
  EntityCacheOverRowSet, ViewObjectImpl, ViewRowSetImpl, ViewUsageImpl, WSRowSetImpl, WSViewObjectImpl

public interface RowSet
extends RowSetIterator, Properties, XMLInterface

A `RowSet` belongs to a view object. It manages a collection of view rows. One or more row set iterators may be open on the row set to enumerate through the rows. Row set iterator adds the concept of currency (current row) on top of a row set's collection of rows.

A view object may have many row sets. At the same time, a view object is a row set itself. Internally, for each view object, the default row set is created through which the view object can function as a row set. Other row sets that are not the default row set are referred to as secondary row sets.

Whereas a view object manages the query statement, a row set manages query bind parameter values. Hence, a query statement may contain bind variables ('?' for JDBC style, :1, :2, ... for Oracle style, and :var1, :var2, ... for Oracle name binding style) and multiple row sets may be created with different bind variable values.

For example (using Oracle style binding), given the query statement

        SELECT ... FROM EMP WHERE DEPTNO = :1

A row set may be opened with a bind value of 10. Such a row set will contain Employee rows of Department 10. Another row set may create opened through ``ViewObject.createRowSet(String)`` with a bind value of 20, which would represent Employees of Department 20.

Since:
  JDeveloper 3.0
See Also:
  `ViewObject`, `RowSetIterator`

Field Summary
`static byte` | `FORWARD_ONLY` Row set access mode constant.
`static byte` | `RANGE_PAGING` Row set access mode constant.
`static byte` | `RANGE_PAGING_AUTO_POST` Row set access mode constant.
`static byte` | `SCROLLABLE` Row set access mode constant.

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`

Fields inherited from interface oracle.jbo.XMLInterface
`XML_IGNORE_DEPTH_COUNT, XML_OPT_ALL_ROWS, XML_OPT_ASSOC_CONSISTENT, XML_OPT_CHANGES_ONLY, XML_OPT_LIMIT_RANGE`

Method Summary
`boolean` | `cancelQuery()` Cancels a running query.
`void` | `closeRowSet()` Closes the row set.
`RowSetIterator` | `createRowSetIterator(java.lang.String name)` Creates an iterator for the row set.
`void` | `defineNamedWhereClauseParam(java.lang.String name, java.lang.Object defaultValue, int[] indices)` Defines a named bind variable to use with the view object's where-clause.
`void` | `executeQuery()` Executes the query.
`RowSetIterator` | `findRowSetIterator(java.lang.String rsiName)` Gets the named row set iterator that was created at runtime for this row set.
`byte` | `getAccessMode()`
`ApplicationModule` | `getApplicationModule()` Gets the row set's application module that contains this row set.
`long` | `getEstimatedRowCount()` Counts the number of rows in the collection defined by the view object's query.
`RowSetIterator[]` | `getMasterRowSetIterators()` Return all controlling masters of this row set.
`java.lang.String` | `getName()` Gets the row set's name.
`RowSetIterator[]` | `getRowSetIterators()` Gets all row set iterators that belong to this row set.
`ViewObject` | `getViewObject()` Gets the view object that owns this row set.
`java.lang.Object[]` | `getWhereClauseParams()` Gets the bind variable values to be used with the view object's where-clause.
`boolean` | `isAssociationConsistent()` Returns the flag indicating whether association-consistent mode is on or not.
`boolean` | `isExecuted()` Returns true if the current ViewObject's query has been executed for this row set.
`boolean` | `isFetchComplete()` Tests if the query result set has been fetched to the end.
`boolean` | `isForwardOnly()` Tests if the row set is constrained to sequential access.
`boolean` | `isMaxFetchSizeExceeded()` Tests if the query result has been fetched to the end and the end was reached due to hitting the maxFetchSize limit
`boolean` | `removeMasterRowSetIterator(RowSetIterator masterRSI)` Removes a master row set iterator.
`void` | `removeNamedWhereClauseParam(java.lang.String name)` Removes a named where-clause parameter.
`void` | `setAccessMode(byte mode)` Constrains the row access based on the following settings:
`void` | `setAssociationConsistent(boolean consistent)` Sets the association-consistent flag for this row set.
`void` | `setForwardOnly(boolean forwardOnly)` Constrains the row set to sequential access.
`boolean` | `setMasterRowSetIterator(RowSetIterator masterRSI)` Sets the master iterator.
`void` | `setNamedWhereClauseParam(java.lang.String name, java.lang.Object value)` Sets the value of a named where-clause parameter for this row set.
`void` | `setWhereClauseParam(int index, java.lang.Object value)` Specifies a single bind variable value to use with the view object's where-clause.
`void` | `setWhereClauseParams(java.lang.Object[] values)` Specifies the bind variable values to use with the view object's where-clause.
`void` | `skipNamedWhereClauseParam(java.lang.String name)` Skips the named where-clause parameter for this row set.

Methods inherited from interface oracle.jbo.RowSetIterator
`addManagementListener, closeRowSetIterator, createDetailRowSet, getDetailRowSets, getEstimatedRangePageCount, getFilteredRows, getFilteredRowsInRange, getNextRangeSet, getPreviousRangeSet, getRowSet, getSyncLock, isNameGenerated, removeManagementListener, scrollToRangePage`

Methods inherited from interface oracle.jbo.NavigatableRowIterator
`addListener, removeListener`

Methods inherited from interface oracle.jbo.RowIterator
`createAndInitRow, createKey, createRow, enumerateRowsInRange, findByEntity, findByKey, findByViewCriteria, first, getAllRowsInRange, getCurrentRow, getCurrentRowIndex, getCurrentRowSlot, getFetchedRowCount, getIterMode, getRangeIndexOf, getRangeSize, getRangeStart, getRow, getRowAtRangeIndex, getRowCount, getRowCountInRange, hasNext, hasPrevious, insertRow, insertRowAtRangeIndex, isRangeAtBottom, isRangeAtTop, isRowValidation, last, next, previous, removeCurrentRow, removeCurrentRowAndRetain, removeCurrentRowFromCollection, reset, scrollRange, scrollRangeTo, setCurrentRow, setCurrentRowAtRangeIndex, setIterMode, setRangeSize, setRangeStart, setRowValidation`

Methods inherited from interface oracle.jbo.VariableManagerOwner
`ensureVariableManager, getMessageBundleClass, getVariableManager, hasVariables`

Methods inherited from interface oracle.jbo.Properties
`getProperties, getProperty, refreshProperty`

Methods inherited from interface oracle.jbo.XMLInterface
`readXML, readXML, writeXML, writeXML, writeXML, writeXML`

Field Detail

### SCROLLABLE

    public static final byte SCROLLABLE

  Row set access mode constant. When the access mode is set to this value, this row set will cache its view rows in a collection as rows are fetched.

  This is the most flexible mode for accessing rows and working with a row set. It allows forward and backward access to the all rows.

  See Also:
    Constant Field Values

### FORWARD_ONLY

    public static final byte FORWARD_ONLY

  Row set access mode constant. When the access mode is set to this value, this row set will only provide sequential access to rows in its collection. One is not allowed to scroll back.
  See Also:
    Constant Field Values

### RANGE_PAGING

    public static final byte RANGE_PAGING

  Row set access mode constant. When the access mode is set to this value, this row set will fetch rows in ranges (set using setRangeSize()--the default range size is -1 to fetch all rows), such that on scroll to the the next range or to fetch a row that's not in the current range, it's fetched back from the database using ROWNUM query and the row at the desired index is placed as the first row in the current range.

  New rows inserted in this mode will be inserted at the beginning of the rowset to maintain their row indices.

  If an attempt is made to get a row outside of the range when a new row is inserted or a row is removed in the current range, then an InvalidOperException is raised as the current set of changes needs to be posted to recalculate the right ROWNUM.

  See Also:
    Constant Field Values

### RANGE_PAGING_AUTO_POST

    public static final byte RANGE_PAGING_AUTO_POST

  Row set access mode constant. This mode is same as `RANGE_PAGING` except that it causes any changes in this transaction to be posted when the user accesses a row out of the current range, i.e., when the ROWNUM query is to be exected to get a different set of rows.
  See Also:
    Constant Field Values

Method Detail

### getName

    public java.lang.String getName()

  Gets the row set's name.
  Specified by:
    `getName` in interface `RowSetIterator`
  Returns:
    the name of the row set.

### setMasterRowSetIterator

    public boolean setMasterRowSetIterator(RowSetIterator masterRSI)

  Sets the master iterator.
  Parameters:
    `masterRSI` - the new master row set iterator for this row set.
  Returns:
    `true` if the operation succeeded.

### getViewObject

    public ViewObject getViewObject()

  Gets the view object that owns this row set.

  If this row set is the result of calling a view link accessor, the returned view object is an internal view object. ``ViewObject.isInternal()`` indicates whether the view object is internal or not. Even if a view link is defined between the master and detail view object, and even if an instance of them are included in the application module's data model, calling the view link by default uses a separate view object instance from the one in the AM's data model. To access the view link accessor's ViewObject, use the following code snippet (assuming that the detail side is called "MyDetail"):

          RowSet detailRS = (RowSet) masterViewRow.getMyDetail();
          ViewObject detailVO = detailRS.getViewObject();

  Returns:
    the parent view object.

### setWhereClauseParams

    public void setWhereClauseParams(java.lang.Object[] values)

  Specifies the bind variable values to use with the view object's where-clause.

  Setting the where-clause bind values through this method does not automatically execute the query. You must call ``executeQuery()`` to apply the new bind values.

  Parameters:
    `values` - an array of bind values. If the view object is using the JDBC style bindings (`"?"` for bind variable), `values[n]` is bound to the bind variable that appears in the n-th order (0 based indexing). If the view object is using the Oracle style bindings (`":1", ":2",` etc. for bind variable), `values[n]` is bound to the bind variable `:(n+1)`, i.e., `values[0]` is bound to `:1`, `values[1]` is bound to `:2`, etc.

### setWhereClauseParam

    public void setWhereClauseParam(int index,
                                    java.lang.Object value)

  Specifies a single bind variable value to use with the view object's where-clause.

  Setting the where-clause bind values through this method does not automatically execute the query. You must call ``executeQuery()`` to apply the new bind values.

  Parameters:
    `index` - the index identifying the bind variable. If the view object is using the JDBC style bindings (`"?"` for bind variable), `value` is bound to the bind variable that appears in the `index-th` order (0 based indexing). If the view object is using the Oracle style bindings (`":1", ":2",` etc. for bind variable), `value` is bound to the bind variable `:(index+1)`. If `index` is 0, `value` is bound to `:1`. If `index` is 1, `value` is bound to `:2`.
    `value` - the bind variable value.

### defineNamedWhereClauseParam

    public void defineNamedWhereClauseParam(java.lang.String name,
                                            java.lang.Object defaultValue,
                                            int[] indices)

  Defines a named bind variable to use with the view object's where-clause.

  This named where-clause parameter will be defined as a variable on the view object. That is, if a named where-clause parameter is defined through one row set, all other row sets that belongs to the same parent view object will "see" that parameter.

  Through the `defaultValue`, one can specify the default value for this where-clause parameter. If no default value is supplied, `null` will be used as the parameter value.

  The `indices` parameter specifies where-clause parameter indices into which this named parameter will be bound. The same value can be bound into multiple indices. For example, if `{ 1, 2 }` is specified for `indices`, the value will be bound for where-clause parameter indices of 1 and 2. I.e., this parameter will produce `setWhereClauseParam(1, value)` and `setWhereClauseParam(2, value)`.

  This method can be invoked to redefine an existing named where-clause paramter (to change the default value and the indices) only if the named parameter is found on the view object. If the named parameter/variable is found on one of the parent objects, a new where-clause parameter definition is still added to the view object.

  When redefining, a check is made to ensure that the existing variable has no kind specification (`null`) or is of the `"where"` kind (which means that the existing variable is a where-clause parameter). If not, an `InvalidParamException` is thrown.

  Defining a named where-clause parameter does not automatically execute the query. You must call ``executeQuery()`` to apply the new bind value.

  Parameters:
    `name` - the name of the where-clause parameter.
    `defaultValue` - specifies the default value for this where-clause parameter. This default value can be overridden through a call to `setNamedWhereClauseParam()`.
    `indices` - where-clause indices into which this parameter value should be bound. See above.
  Throws:
    `InvalidParamException` - if this method is being called to redefine an old parameter and the variable turns out not to be a where-clause parameter.

### removeNamedWhereClauseParam

    public void removeNamedWhereClauseParam(java.lang.String name)

  Removes a named where-clause parameter.

  This method removes previously defined named where-clause parameter. A check is made to ensure that the variable being removed is a where-clause parameter (variable kind = `"where"`). If not, an `InvalidParamException` is thrown.

  If the named where-clause parameter is found but it does not belong to the view object that owns this row set, an `InvalidOperException` is thrown. This means one is disallowed from removing a named where-clause parameter that belongs to the View definition, for example.

  Removing a named where-clause parameter does not automatically execute the query. You must call ``executeQuery()`` for the removal to take effect.

  Parameters:
    `name` - the name of the where-clause parameter to remove.
  Throws:
    `InvalidParamException` - if the specified variable is not a where-clause parameter.
    `InvalidOperException` - if the specified variable does not belong to the view object that owns this row set.

### setNamedWhereClauseParam

    public void setNamedWhereClauseParam(java.lang.String name,
                                         java.lang.Object value)

  Sets the value of a named where-clause parameter for this row set.

  If the view object owns multiple row sets, each row set may have its own (different) named where-clause parameter value.

  Setting a named where-clause parameter does not automatically execute the query. You must call ``executeQuery()`` to apply the new bind value.

  Parameters:
    `name` - the name of the where-clause parameter.
    `value` - the where-clause parameter value for this row set.
  Throws:
    `InvalidParamException` - if the named variable turns out not to be a where-clause parameter.
    `NoDefException` - if the named where-clause parameter does not exist.

### skipNamedWhereClauseParam

    public void skipNamedWhereClauseParam(java.lang.String name)

  Skips the named where-clause parameter for this row set. This method does not remove the named where-clause parameter. However, it "masks out" the named where-clause parameter, so that the parameter is skipped when the query is executed.

  Skipping a named where-clause parameter does not automatically execute the query. You must call ``executeQuery()`` for the skip to take effect.

  Parameters:
    `name` - the name of the where-clause parameter.
  Throws:
    `InvalidParamException` - if the named variable turns out not to be a where-clause parameter.
    `NoDefException` - if the named where-clause parameter does not exist.

### getWhereClauseParams

    public java.lang.Object[] getWhereClauseParams()

  Gets the bind variable values to be used with the view object's where-clause.
  Returns:
    an array of bind-variable values.

### executeQuery

    public void executeQuery()

  Executes the query.

### cancelQuery

    public boolean cancelQuery()

  Cancels a running query.
  Returns:
    a flag indicating whether the request to cancel was honored or not. It will return `false` if the JDBC statement is not executing a query.

### isExecuted

    public boolean isExecuted()

  Returns true if the current ViewObject's query has been executed for this row set.
  Returns:
    `true` if query has been executed.

### createRowSetIterator

    public RowSetIterator createRowSetIterator(java.lang.String name)

  Creates an iterator for the row set.
  Parameters:
    `name` - the name to be given to the iterator.
  Returns:
    an iterator for `this`.

### getRowSetIterators

    public RowSetIterator[] getRowSetIterators()

  Gets all row set iterators that belong to this row set.
  Returns:
    the array of row set iterators.

### findRowSetIterator

    public RowSetIterator findRowSetIterator(java.lang.String rsiName)

  Gets the named row set iterator that was created at runtime for this row set.
  Parameters:
    `rsiName` - a row set iterator name. If `null`, it returns the the row set.
  Returns:
    the row set iterator. `null` if the named row set iterator is not not found.

### removeMasterRowSetIterator

    public boolean removeMasterRowSetIterator(RowSetIterator masterRSI)

  Removes a master row set iterator.
  Parameters:
    `masterRSI` - the iterator to be removed.
  Returns:
    `true` if `masterRS` was found, `false` otherwise.

### getMasterRowSetIterators

    public RowSetIterator[] getMasterRowSetIterators()

  Return all controlling masters of this row set.
  Returns:
    An array of master iterators.

### getApplicationModule

    public ApplicationModule getApplicationModule()

  Gets the row set's application module that contains this row set.

  Strictly speaking, a row set belongs to a view object and the view object to an application module. This method returns the application module that cotains the view object, which contains this row set.

  If this row set is the result of calling a View Link accessor, this row set belongs to an internal view object (see ``ViewObject.isInternal()``). Such an internal view object belongs to the root application module. Put differently, if you call this method on a row set which is the result of calling a View Link accessor, it will return the root application module.

  Returns:
    the `ApplicationModule` to which this row set belongs.

### getEstimatedRowCount

    public long getEstimatedRowCount()

  Counts the number of rows in the collection defined by the view object's query.

  This method uses a "SELECT COUNT(1) FROM (<query-statement>)" query to obtained the initial count. After that, changes to row count (such as insertion and deletion of rows) is kept up to date.

  However, since the row counting query and the query to retrieve actual rows are issued at two different times, it is possible for the accurate count to change between these two points. This is why this method is named `getEstimatedRowCount()`.

  Returns:
    an estimated number of rows.

### isForwardOnly

    public boolean isForwardOnly()

  Tests if the row set is constrained to sequential access.
  Returns:
    `true` if the row set is restricted to forward-only processing.
  See Also:
    `setForwardOnly(boolean)`

### setForwardOnly

    public void setForwardOnly(boolean forwardOnly)

  Constrains the row set to sequential access.

  When set to `true`, a row preceeding the current row cannot be designated as the new current row. This restriction allows performance to be optimized.

  Parameters:
    `forwardOnly` - `true` restricts the row set to forward-only processing, `false` otherwise.

### getAccessMode

    public byte getAccessMode()

  Returns:
    Returns the current access mode for this row set.
  See Also:
    `setAccessMode(byte)`

### setAccessMode

    public void setAccessMode(byte mode)

  Constrains the row access based on the following settings:

  Switching access modes for a rowset will not take effect until the next explicit call to executeQuery. Switching accessmode back to SCROLLABLE from any other mode is not allowed.

  Parameters:
    `mode` - One of the four enumerated values ``SCROLLABLE``, ``FORWARD_ONLY``, ``RANGE_PAGING``, ``RANGE_PAGING_AUTO_POST``.

### setAssociationConsistent

    public void setAssociationConsistent(boolean consistent)

  Sets the association-consistent flag for this row set.

  Association-consistent mode allows the user to see new rows created/inserted through another view object. Note that this mode is effective only for view objects that are entity based. If the view object has no entity base, this mode has no effect.

  Suppose we have an entity named E. Suppose two view objects, V1 and V2 are based on E. (V1 and V2 do not have to come from the same view definition.) Suppose the user creates a new row through V1. This creates an instance of E as well. The new entity row is registered only when its primary key is attribute set. At this time, an event is sent out to all view objects based on E, i.e., V1 and V2.

  When V2 receives this event, it enumerates through all its collections (essentially its row sets--strictly speaking its query collections) looking for those whose `isAssociationConsistent()` value is true. For each row set whose flag value is true (say R2), it checks to see if it has any view row mapped to the new entity row. If not, it create a new view row and maps it to the new entity row. A `rowInserted` event fires.

  Thus, from the user's view point, R2 is "seeing" the new row, although the row has not yet been posted to database. Hence, setting this flag to `true` enables the user to see new rows before the row is posted/queried when the view object is entity based.

  If flag is false or if the view object is not entity based, the user needs to post the new row through ``Transaction.postChanges()`` and requery the row set through ``executeQuery()`` to see the new row.

  The default value for this flag can be globally controlled through the `jbo.viewlink.consistent` property. Its value can be `true`, `false`, or `DEFAULT`. If the property is not specified, the default value is `DEFAULT`. A similar property `jbo.assoc.consistent` controls whether the new-row-appearing behavior should be supported for row sets returned from entity association accessor calls. For `jbo.assoc.consistent`, supported values are `true` or `false`.

  If the property value is set to `true`, all row sets will have `true` for its initial `isAssociationConsistent()` value. If the property value is set to `false`, all row sets will have `false` for its initial value. If the property value is set to `DEFAULT` (which is the default), the view object will use the following logic to compute its initial `isAssociationConsistent()` value: if the view object has multiple entity bases that are updateable, then the initial value is `false`. If the view object has a where-clause, then the initial value is `false`. Otherwise, it is true.

  Once this method is called to set the flag value manually, neither the property setting nor the view object's initial flag value has an effect.

  Parameters:
    `consistent` - indicates whether association-consistency should be on or not.

### isAssociationConsistent

    public boolean isAssociationConsistent()

  Returns the flag indicating whether association-consistent mode is on or not.
  Returns:
    `true` if un-posted new rows are to appear, `false` otherwise. This flag has no effect if the view object is not entity based.
  See Also:
    `setAssociationConsistent(boolean)`

### closeRowSet

    public void closeRowSet()

  Closes the row set. It closes all row set iterators that belong to this row set. If this row set is a detail row set in a master-detail relationship, `closeRowSet` removes this row set from the master row set iterator.

### isFetchComplete

    public boolean isFetchComplete()

  Tests if the query result set has been fetched to the end.
  Returns:
    `true` if the result set has been fetched to the end.

### isMaxFetchSizeExceeded

    public boolean isMaxFetchSizeExceeded()

  Tests if the query result has been fetched to the end and the end was reached due to hitting the maxFetchSize limit
  Returns:
    `true` if the result set has been fetched to the maxFetchSize limit and there are still more rows in the database.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1997, 2005, Oracle. All rights reserved.