oracle.jbo
Interface ViewObject

All Superinterfaces:

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

All Known Subinterfaces:

ViewObjectDynAttr

All Known Implementing Classes:

ViewObjectImpl, ViewUsageImpl, WSViewObjectImpl

public interface ViewObject

extends StructureDef, RowSet, ComponentObject

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_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

FORWARD_ONLY, RANGE_PAGING, RANGE_PAGING_AUTO_POST, SCROLLABLE

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

AttributeDef	addDynamicAttribute(java.lang.String attrName) Adds a dynamic attribute (an AttributeDefImpl) to this view object's row set.
void	addQueryMode(int queryMode) Adds query mode for the view object.
void	applyViewCriteria(ViewCriteria criteria) Applies the view criteria to this view object.
void	clearCache() Clears the view object cache.
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.
RowSet	findRowSet(java.lang.String rsName) Gets the named row set that was created at runtime for this view object.
AttributeDef	findViewLinkAccessor(ViewLink vl) Finds the view link accessor attribute.
AttributeDef[]	getAttrDefsForEntityAttr(java.lang.String eoName, java.lang.String eoAttrName) Returns the definitions of view attributes that are mapped to the entity attribute identified by the entity name (the eoName parameter) and the entity attribute name (the eoAttrName).
AttributeDef[]	getKeyAttributeDefs() Returns the attribute definitions that make up the constituents of the key object for rows returned from this view object.
int	getMaxFetchSize() Maximum number of rows to fetch for this view object.
java.lang.String	getOrderByClause() Returns the query's ORDER BY clause.
java.lang.String	getQuery() Returns the query statement.
int	getQueryMode() Gets the current query mode of this view object.
java.lang.String	getQueryOptimizerHint() Returns query optimizer Hint set for this ViewObject or for its definition object.
int	getQueryTimeOut() Returns the current query time out value.
RowMatch	getRowMatch() Gets the in-memory filter (RowMatch) for the view object.
RowSet[]	getRowSets() Gets all row sets that belong to this view object.
java.lang.String	getSortBy()
ViewCriteria	getViewCriteria() Gets the view criteria for this view object.
java.lang.String[]	getViewLinkNames() Constructs an array of names of view links that involve this view object.
java.lang.String	getWhereClause() Gets the query's where-clause.
boolean	isInternal() Returns whether this view object was created internally by BC4J or by an explicit user request.
boolean	isReadOnly() Tests if the view object is read-only.
void	readRowXML(Element elem, int depthCount) Reads the data in XML form (in the format as generated by writeXML()) by finding a row that matches the key in the given XML and then reading in that row.
void	readRowXML(Element elem, int depthCount, XSLStylesheet xslt)
void	setMaxFetchSize(int max) Maximum number of rows to fetch for this view object.
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	setQueryOptimizerHint(java.lang.String hintText) If this ViewObject does not have an expert mode query, then this hint is added to the select clause of the SQL for this ViewObject before the columns are listed e.g., SELECT \/*+ <hintText> *\/ columns...
void	setQueryTimeOut(int timeOutMills) Sets the query time out value for the view object.
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, getDefFullName, getDefName, getFullName, getName, lookupAttributeDef

Methods inherited from interface oracle.jbo.RowSet

cancelQuery, closeRowSet, createRowSetIterator, defineNamedWhereClauseParam, executeQuery, findRowSetIterator, getAccessMode, getApplicationModule, getEstimatedRowCount, getMasterRowSetIterators, getName, 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, 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

Methods inherited from interface oracle.jbo.ComponentObject

getDefFullName, getDefName, getFullName, getName, remove

Field Detail

QUERY_MODE_SCAN_VIEW_ROWS

public 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 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

public 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

public 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_TIMEOUT_WAIT_FOREVER

public 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

addDynamicAttribute

public AttributeDef addDynamicAttribute(java.lang.String attrName)

Adds a dynamic attribute (an AttributeDefImpl) to this view object's row set.

Dynamic attributes are typeless, in that the application can set the attribute value to any object. You can use a dynamic attribute to store information created at runtime that you want to store with the row data. It is used only by the view object that created it. Attributes can be any serializable (java.io.Serializable) object.

This method should not be overridden.

Parameters:

attrName - the name of the dynamic attribute.

Returns:

the attribute definition the newly added dynamic attribute.

Throws:

NameClashException - if an attribute of the same name already exists.

setWhereClause

public 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

public 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

public 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

public 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

public java.lang.String getQuery()

Returns the query statement. Unlike 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.

setRowMatch

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

getRowMatch

public RowMatch getRowMatch()

Gets the 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.

Returns:

the current row match.

setSortBy

public void setSortBy(java.lang.String sortBy)

getSortBy

public java.lang.String getSortBy()

setQueryMode

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

addQueryMode

public void addQueryMode(int queryMode)

Adds 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. This method OR'es in the incoming queryMode to the view object's current query mode. 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.

Parameters:

queryMode - the new query mode to be added (OR'ed).

getQueryMode

public int getQueryMode()

Gets the current query mode of this view object. Query mode controls how qualifying rows are formulated for each row set in the view object.

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

The default query mode is QUERY_MODE_SCAN_DATABASE_TABLES.

Returns:

query mode.

isReadOnly

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

createRowSet

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

getRowSets

public RowSet[] getRowSets()

Gets all row sets that belong to this view object.

Returns:

the array of row sets.

findRowSet

public RowSet findRowSet(java.lang.String rsName)

Gets the named row set that was created at runtime for this view object.

Parameters:

rsName - a row set name. If null, it returns the the view object.

Returns:

the row set. null if the named row set is not not found.

getViewLinkNames

public java.lang.String[] getViewLinkNames()

Constructs an array of names of view links that involve this view object.

A view link may use this view object as either its source or destination. This method should not be overridden.

Returns:

the array of view link names.

createViewCriteria

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

applyViewCriteria

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

This method should not be overridden.

Parameters:

criteria - a view criteria object.

getViewCriteria

public ViewCriteria getViewCriteria()

Gets the view criteria for this view object.

This method should not be overridden.

Returns:

the view criteria, or null if none is specified.

findViewLinkAccessor

public AttributeDef findViewLinkAccessor(ViewLink vl)

Finds the view link accessor attribute.

Parameters:

vl - the view link whose accessor is being sought.

Returns:

the attribute definition if one is found. null if not.

getKeyAttributeDefs

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

getAttrDefsForEntityAttr

public AttributeDef[] getAttrDefsForEntityAttr(java.lang.String eoName,
                                               java.lang.String eoAttrName)

Returns the definitions of view attributes that are mapped to the entity attribute identified by the entity name (the eoName parameter) and the entity attribute name (the eoAttrName).

Note that it returns an array because more than one view object attribute may be mapped to one entity attribute.

This method can be used to identify view attributes that map into a particular entity object attribute. In particular, if a validation error fails on an entity attribute, this method can be used to find view attributes that map into that entity attribute.

Parameters:

eoName - fully qualified name of the entity object.

eoAttrName - entity object attribute name.

Returns:

the array of attribute definitions.

clearCache

public void clearCache()

Clears the view object cache. This method can be called for resource conservation. Calling this method marks the view object and all its row sets as "needing to refresh its data". If another method that requires the result set is called (e.g., executeQuery(), next(), previous()) after this method, the query will be executed and the view object/row set's cache refreshed from the database.

getMaxFetchSize

public int getMaxFetchSize()

Maximum number of rows to fetch for this view object. This number takes effect in when the query for this view object is executed the next time.

setMaxFetchSize

public void setMaxFetchSize(int max)

Maximum number of rows to fetch for this view object. This number takes effect the next time the query for this view object is executed.

Passing -1 to this method will retrieve an unlimited number of rows. This is the default.

Passing 0 to this method will cause the database query not to be executed. The view object will initially work with an empty row set. If you want to execute query later, call setMaxFetchSize again with a non-zero argument, then call executeQuery().

Parameters:

max - the maximum number of rows to fetch. The default, -1, retrieves an unlimited number of rows. 0 causes the query not to be executed, and row set is empty.

setQueryOptimizerHint

public void setQueryOptimizerHint(java.lang.String hintText)

If this ViewObject does not have an expert mode query, then this hint is added to the select clause of the SQL for this ViewObject before the columns are listed e.g., SELECT \/*+ <hintText> *\/ columns... For expert mode queries, this hint is appended in the outer select like: SELECT \/*+ <hintText> *\/ * FROM (<expert-query>)

getQueryOptimizerHint

public java.lang.String getQueryOptimizerHint()

Returns query optimizer Hint set for this ViewObject or for its definition object.

isInternal

public boolean isInternal()

Returns whether this view object was created internally by BC4J or by an explicit user request.

Returns:

a flag indicating whether the view object is internal or not.

getQueryTimeOut

public int getQueryTimeOut()

Returns the current query time out value. The default is QUERY_TIMEOUT_WAIT_FOREVER.

Returns:

the current query time out value.

setQueryTimeOut

public void setQueryTimeOut(int timeOutMills)

Sets the query time out value for the view object. The default is QUERY_TIMEOUT_WAIT_FOREVER (-1), which means that the query will not time out. The user will be able to cancel the long running query by calling cancelQuery()

If a positive timeout value is specified, the query is monitored by a global monitor thread. The monitor thread waits the specified amount of time (approximately) in milli-seconds, and cancels the query by calling JDBC's Statement.cancel().

Parameters:

timeOutMills - if non-negative, number of milli-seconds before the query is timed out. Or, it can be the QUERY_TIMEOUT_WAIT_FOREVER constants.

readRowXML

public void readRowXML(Element elem,
                       int depthCount)

Reads the data in XML form (in the format as generated by writeXML()) by finding a row that matches the key in the given XML and then reading in that row. If the row is not found, it tries to insert that row into this ViewObject with the attribute values from XML.

The depthcount parameter represents to what level the rendering should recurse. A depthcount of zero (0) means do not traverse any view links while rendering. One (1) means traverse the view links on this object but no view links thereafter, and so on.

readRowXML

public void readRowXML(Element elem,
                       int depthCount,
                       XSLStylesheet xslt)