oracle.jbo
Interface ViewObject

All Superinterfaces:

ComponentObject, NavigatableRowIterator, Properties, RowIterator, RowSet, RowSetIterator, StructureDef, 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 ViewObject#setWhereClause().

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, StructureInfo, AttributeDef

Field Summary

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	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 Ret 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.
java.lang.String	getQueryOptimizerHint() Returns Query Optimizer Hint set for this ViewObject or for its definition object.
RowSet[]	getRowSets() Gets all Row Sets that belong to this View Object.
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	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 \/*+ *\/ columns...
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

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

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

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 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 ViewObjectImpl.executeQuery() is called. For an example usage of this method, see ViewObjectImpl.setWhereClauseParam(int, Object).

Note that calling setWhereClause() does not clear the previous settings of WHERE clause parameters. To reset WHERE clause parameters in the middle tier, call ViewObjectImpl.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 WHERE clauses built from the View Object instance, the View definition, and the detail View Objects, 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 ViewObjectImpl.executeQuery() is called.

This method should not be overridden.

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.

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 Ret 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 ViewObject 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().

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 \/*+ *\/ columns... For expert mode queries, this hint is appended in the outer Select like: SELECT \/*+ *\/ * FROM ()

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.

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)