oracle.jbo
Interface ViewObject

All Superinterfaces:

ComponentObject, NavigatableRowIterator, Properties, RowIterator, RowSet, RowSetIterator, StructureDef, VariableManagerOwner, VariableManagerOwnerBase

All Known Implementing Classes:

ViewObjectImpl

public interface ViewObject
extends StructureDef, ComponentObject, RowSet

ViewObject decribes how the application will view and update data. A view object may be entity based or non-entity based. In the former case, the view object consists of one or more entity bases. The first one of these is referred to as the primary entity base. The rest are called secondary entity bases. An entity based view object maps its attribute (view attributes) to attributes in the entities (entity attributes). An entity based view object may map all its entity attributes or only some of them. However, an entity based view object is required to map all primary key attributes of the entity bases. An entity based view object may additional include attributes that are not mapped to an entity attribute. Such an attribute is referred to View level attribute.

A non-entity based view object is one where it does not have any entity base. All its attributes are view level attributes.

view object is responsible for managing database query statement. Regardless of whether the view object is entity based or not, it may have a SQL statement from which it draws its data. As rows are read from this query, it will populate a RowSet (of this view object) with view rows.

View object provides a number of APIs through which the client can modify and augment the query statement during runtime. For example, see setWhereClause(String).

A view level attribute (not mapped to an entity attribute) may map to a column or a SQL expression in the query statement. It may be a transient attribute (whose data is purely in memory and not mapped to any database column/expression. Or, it may be a dynamic attribute.

Since:

JDeveloper 3.0

See Also:

Row, RowSet, RowSetIterator, AttributeDef

Field Summary

static int	QUERY_MODE_SCAN_DATABASE_TABLES Specifies that rows should be produced from database query result.
static int	QUERY_MODE_SCAN_ENTITY_ROWS Specifies that rows should be produced from entity cache.
static int	QUERY_MODE_SCAN_UNPOSTED_ENTITY_ROWS Specifies that rows should be produced from the unposted rows in the entity cache.
static int	QUERY_MODE_SCAN_VIEW_ROWS These QUERY_MODE_SCAN_... constants are used to specify the query mode for the view object.
static int	QUERY_TIMEOUT_WAIT_FOREVER Specifies that the view object does not time out when executing query.

Fields inherited from interface oracle.jbo.RowSet

COPY_OPT_ALL_ROWS, COPY_OPT_LIMIT_RANGE, FORWARD_ONLY, RANGE_PAGING, RANGE_PAGING_AUTO_POST, RANGE_PAGING_INCR, SCROLLABLE

Fields inherited from interface oracle.jbo.RowIterator

CLASS_INSTANCE, ITER_MODE_LAST_PAGE_FULL, ITER_MODE_LAST_PAGE_PARTIAL, SLOT_BEFORE_FIRST, SLOT_BEYOND_LAST, SLOT_DELETED, SLOT_VALID

Method Summary

void	applyViewCriteria(ViewCriteria criteria) Applies the view criteria to this view object.
RowSet	createRowSet(java.lang.String name) Creates and returns a new (secondary) row set for this view object.
ViewCriteria	createViewCriteria() Creates a new view criteria (that is, "Query by Example") object for this view object.
AttributeDef[]	getKeyAttributeDefs() Returns the attribute definitions that make up the constituents of the key object for rows returned from this view object.
java.lang.String	getOrderByClause() Returns the query's ORDER BY clause.
java.lang.String	getQuery() Returns the query statement.
ViewCriteria	getRequiredViewCriteria() This method returns a reference to the required view criteria if one exists on this View Object.
RowSet[]	getRowSets() Gets all row sets that belong to this view object.
java.lang.String	getSortBy()
ViewCriteria	getViewCriteria() Gets the currently applied view criteria of this view object.
ViewCriteriaManager	getViewCriteriaManager()
java.lang.String	getWhereClause() Gets the query's where-clause.
boolean	isReadOnly() Tests if the view object is read-only.
ListBindingDef	lookupListBindingDef(java.lang.String lbName) Return listbinding definition if defined in this ViewObject (or in the entity definitions for entities that this ViewObject constitutes of).
void	setOrderByClause(java.lang.String expr) Sets the ORDER BY clause of the view object's query statement.
void	setQueryMode(int queryMode) Sets query mode for the view object.
void	setRequiredViewCriteria(ViewCriteria vc) Setting a view criteria as required will enforce the criteria whenever the view object's query is executed.
void	setRowMatch(RowMatch rowMatch) Sets an in-memory filter (RowMatch) for the view object.
void	setSortBy(java.lang.String sortBy)
void	setWhereClause(java.lang.String cond) Sets a where-clause bind value of the view object's query statement.

Methods inherited from interface oracle.jbo.StructureDef

findAttributeDef, getAttributeCount, getAttributeDef, getAttributeDefs, getAttributeIndexOf, getColumnNameForQuery, getDefFullName, getDefName, getFullName, getName, lookupAttributeDef

Methods inherited from interface oracle.jbo.ComponentObject

getDefFullName, getDefName, getFullName, getName, remove

Methods inherited from interface oracle.jbo.RowSet

cancelQuery, closeRowSet, createRowSetIterator, defineNamedWhereClauseParam, executeQuery, findRowSetIterator, getAccessMode, getApplicationModule, getEstimatedRowCount, getMasterRowSetIterators, getName, getNamedWhereClauseParam, getRowSetIterators, getViewObject, getWhereClauseParams, isAssociationConsistent, isExecuted, isFetchComplete, isForwardOnly, isMaxFetchSizeExceeded, removeMasterRowSetIterator, removeNamedWhereClauseParam, setAccessMode, setAssociationConsistent, setForwardOnly, setMasterRowSetIterator, setNamedWhereClauseParam, setWhereClauseParam, setWhereClauseParams, skipNamedWhereClauseParam

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, getResourceBundleDef, getVariableManager, hasVariables

Methods inherited from interface oracle.jbo.Properties

getProperties, getProperty, getProperty, refreshProperty

Field Detail

QUERY_MODE_SCAN_VIEW_ROWS

static final int QUERY_MODE_SCAN_VIEW_ROWS

These QUERY_MODE_SCAN_... constants are used to specify the query mode for the view object. Query mode controls how qualifying formulated for each row set in the view object. These constants can be OR'ed together. If more than one query mode is specified in this manner, rows for the collection will be produced from more than one source.

If you call setQueryMode(int) or ViewObject#addQueryMode(int) to change the query mode, the new query mode does not go into effect until you call RowSet.executeQuery() on the row set.

Rows can come from three different sources. If the row set currently has a collection of rows (View rows), QUERY_MODE_SCAN_VIEW_ROWS will indicate that the row match (see setRowMatch(RowMatch)) should be applied to further filter view rows. Unqualifying rows are removed from the collection.

If the query mode includes QUERY_MODE_SCAN_ENTITY_ROWS, the entity cache is scanned to see if qualifying rows can be produced. If so, these rows are added to the collection.

If the query mode includes QUERY_MODE_SCAN_DATABASE_TABLES, a database query is issued to produce rows from the query result. The default query mode is QUERY_MODE_SCAN_DATABASE_TABLES.

If the query mode specifies multiple sources, then care if taken to prevent duplicate rows from appearing.

See Also:

Constant Field Values

QUERY_MODE_SCAN_ENTITY_ROWS

static final int QUERY_MODE_SCAN_ENTITY_ROWS

Specifies that rows should be produced from entity cache. See above for details.

See Also:

Constant Field Values

QUERY_MODE_SCAN_DATABASE_TABLES

static final int QUERY_MODE_SCAN_DATABASE_TABLES

Specifies that rows should be produced from database query result. See above for details.

See Also:

Constant Field Values

QUERY_MODE_SCAN_UNPOSTED_ENTITY_ROWS

static final int QUERY_MODE_SCAN_UNPOSTED_ENTITY_ROWS

Specifies that rows should be produced from the unposted rows in the entity cache. See above for details.

See Also:

Constant Field Values

QUERY_TIMEOUT_WAIT_FOREVER

static final int QUERY_TIMEOUT_WAIT_FOREVER

Specifies that the view object does not time out when executing query. However, the client will be able to cancel the query using the ViewObject.CancelQuery and RowSet.CancelQuery.

See Also:

Constant Field Values

Method Detail

setWhereClause

void setWhereClause(java.lang.String cond)

Sets a where-clause bind value of the view object's query statement.

Bind variables can be specified using '?' as a place-holder for the value.

The new where-clause does not take effect until RowSet.executeQuery() is called. If the where-clause contains where-clause parameters, RowSet.setWhereClauseParam(int, Object) or RowSet.setWhereClauseParams(Object[]) needs to be called before executeQuery().

Note that calling setWhereClause() does not clear the previous settings of where-clause parameters. To reset where-clause parameters in the middle tier, call RowSet.setWhereClauseParams(Object[]) explicitly with a null value. For example:

 vo.setWhereClauseParams(null);
 

This method should not be overridden.

Parameters:

cond - a where-clause, but excluding the 'WHERE' keyword.

getWhereClause

java.lang.String getWhereClause()

Gets the query's where-clause. If the query does not have a where-clause, this method returns null.

This where-clause is obtained from the view object instance. In the middle tier, to get the complete where-clause built from the view object instance, the view definition, the view criteria, and the view links use ViewObjectImpl.buildWhereClause(java.lang.StringBuffer, int)

Returns:

the where-clause, excluding the 'WHERE' keyword; null if no where-clause exists.

setOrderByClause

void setOrderByClause(java.lang.String expr)

Sets the ORDER BY clause of the view object's query statement. Bind variables can be specified using '?' as a place-holder for the value. The new ORDER BY clause does not take effect until RowSet.executeQuery() is called.

This method should not be overridden.

Parameters:

expr - a ORDER BY clause, but excluding the 'ORDER BY' keywords.

getOrderByClause

java.lang.String getOrderByClause()

Returns the query's ORDER BY clause. If the query does not have an ORDER BY clause, this method returns null.

This method should not be overridden.

Returns:

a ORDER BY clause, but excluding the 'ORDER BY' keyword. null if the SQL statement has no ORDER BY clause.

getQuery

java.lang.String getQuery()

Returns the query statement. Unlike oracle.jbo.server.ViewObjectImpl#getUserDefinedQuery() this method will return a SQL statement regardless of whether the query was created in expert or non-expert Mode.

Returns:

the user-defined SQL query if one exists, otherwise, a query statement is assembled from defined from, where, and order by clauses.

isReadOnly

boolean isReadOnly()

Tests if the view object is read-only.

A view is read-only if it does not have primary keys or if all its entity references are reference-only.

This method should not be overridden.

Returns:

true if this view object is read-only; false if it is updateable.

getKeyAttributeDefs

AttributeDef[] getKeyAttributeDefs()

Returns the attribute definitions that make up the constituents of the key object for rows returned from this view object.

This method is used to pass AttributeDef[] to the Key.Key(String, AttributeDef[]) constructor to parse the constituent-bytes and convert them into value-objects that make up the key.

Use this method to find out how the key is composed for the view row. The view object's key is a composite key, consisting of view attributes mapped to the primary keys of its entity objects.

Returns:

the array of attribute definitions.

createViewCriteria

ViewCriteria createViewCriteria()

Creates a new view criteria (that is, "Query by Example") object for this view object. A view criteria object is an alternative to using an arbitrary SQL statement. A view criteria is a list of row criteria for a view object's where-clause, where a row criteria is an array containing criteria for the individual attributes.

A view criteria is a more structured way of creating a SQL query where-clause. After setting various conditions for the view criteria object, the application can call applyViewCriteria

This method should not be overridden.

Returns:

the new view criteria object.

See Also:

ViewCriteria, applyViewCriteria(ViewCriteria)

getViewCriteriaManager

ViewCriteriaManager getViewCriteriaManager()

setRowMatch

void setRowMatch(RowMatch rowMatch)

Sets an in-memory filter (RowMatch) for the view object. While the where-clause is used when a database query is issued, the row match is used for qualifying rows in memory. Calling this method does not cause filtering of rows by the row match. To filter, RowSet.executeQuery() must be called.

Parameters:

rowMatch - the new row match.

setSortBy

void setSortBy(java.lang.String sortBy)

getSortBy

java.lang.String getSortBy()

applyViewCriteria

void applyViewCriteria(ViewCriteria criteria)

Applies the view criteria to this view object.

View criteria rows are ORed together, while entries in the same row are ANDed together.

Parameters:

criteria - a view criteria object.

getViewCriteria

ViewCriteria getViewCriteria()

Gets the currently applied view criteria of this view object.

Returns:

the view criteria, or null if none was applied.

setQueryMode

void setQueryMode(int queryMode)

Sets query mode for the view object. Query mode controls how qualifying rows are formulated for each row set in the view object.

The queryMode parameter may be an OR'ed flag of QUERY_MODE_SCAN_... constants. See these constants for further details.

Calling this method does not cause automatically cause the new query mode to go into effect. Call RowSet.executeQuery() to apply the new query mode.

The default query mode is QUERY_MODE_SCAN_DATABASE_TABLES.

Parameters:

queryMode - the new query mode.

setRequiredViewCriteria

void setRequiredViewCriteria(ViewCriteria vc)

Setting a view criteria as required will enforce the criteria whenever the view object's query is executed. This criteria cannot be removed by using getViewCriteriaManager().clearViewCriterias or getViewCriteriaManager().removeViewCriteria API.

Parameters:

vc - Set the criteria as required view criteria for this view object instance.

getRequiredViewCriteria

ViewCriteria getRequiredViewCriteria()

This method returns a reference to the required view criteria if one exists on this View Object. See setRequiredViewCriteria(oracle.jbo.ViewCriteria)

createRowSet

RowSet createRowSet(java.lang.String name)

Creates and returns a new (secondary) row set for this view object.

Parameters:

name - the name for the new RowSet.

Returns:

the new row set.

lookupListBindingDef

ListBindingDef lookupListBindingDef(java.lang.String lbName)

Return listbinding definition if defined in this ViewObject (or in the entity definitions for entities that this ViewObject constitutes of).

getRowSets

RowSet[] getRowSets()

Gets all row sets that belong to this view object.

Returns:

the array of row sets.