D.1 Most Commonly Used Methods in the Client Tier

All of the interfaces described in this section are designed for use by client-layer code and are part of the oracle.jbo.* package.

Note: The corresponding implementation classes for these oracle.jbo.* interfaces are consciously designed to not be directly accessed by client code. As you'll see in the Section D.2, "Most Commonly Used Methods In the Business Service Tier" section below, the implementation classes live in the oracle.jbo.server.* package and generally have the suffix Impl in their name to help remind you not to using them in your client-layer code.

D.1.1 ApplicationModule Interface

The ApplicationModule is a business service component that acts as a transactional container for other ADF components and coordinates with them to implement a number of J2EE design patterns important to business application developers. These design pattern implementations enable your client code to work easily with updatable collections of value objects, based on fast-lane reader SQL queries that retrieve only the data needed by the client, in the way the client wants to view it. Changes made to these value objects are automatically coordinated with your persistent business domain objects in the business service tier to enforce business rules consistently and save changes back to the database.

Table D-1 ApplicationModule Interface

If you want to...	Call this ApplicationModule interface method...
Access an existing view object instance by name	findViewObject()
Creating a new view object instance from an existing definition	createViewObject()
Creating a new view object instance from a SQL Statement	createViewObjectFromQueryStmt() Note: This incurs runtime overhead to describe the "shape" of the dynamic query's SELECT list. Oracle recommends using this only when you cannot know the SELECT list for the query at design-time. Furthermore, if you are creating the dynamic query based on some kind of custom runtime repository, you can follow this tip to create (both read-only and updatable) dynamic view objects without the runtime-describe overhead with a little more work. If only the WHERE needs to be dynamic, create the view object at design time, then set the where clause dynamically as needed using ViewObject API's.
Access a nested application module instance by name	findApplicationModule()
Create a new nested application module instance from an existing definition	createApplicationModule()
Find a view object instance in a nested application module	findViewObject() Note: To find an instance of a view object belonging to a nested application module you use a dot notation nestedAMInstanceName.VOInstanceName
Accessing the current transaction object	getTransaction()

In addition to generic ApplicationModule access, Oracle JDeveloper 10g can generate you a custom YourApplicationModuleName interface containing service-level custom methods that you've chosen to expose to the client. You do this by visiting the Client Interface tab of the Application Module editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourApplicationModuleNameClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

D.1.2 Transaction Interface

The Transaction interface exposes methods allowing the client to manage pending changes in the current transaction.

Table D-2 Transaction Interface

If you want to...	Call this Transaction interface method...
Commit pending changes	commit()
Rollback pending changes	rollback()
Execute a one-time database command or block of PL/SQL	executeCommand() Note: Commands that require retrieving OUT parameters, that will be executed more than once, or that could benefit by using bind variables should not use this method. Instead, expose a custom method on your application module.
Validate all pending invalid changes in the transaction	validate()
Change the default locking mode	setLockingMode() Note: You can set the locking mode in your configuration by setting the property jbo.locking.mode to one of the four supported values: none, optimistic, pessimistic, optupdate. If you don't explicitly set it, it will default to pessimistic. For web applications, Oracle recommends using optimistic or optupdate modes.
Decide whether to use bundled exception reporting mode or not.	setBundledExceptionMode() Note: ADF controller layer support sets this parameter to true automatically for web applications.
Decide whether entity caches will be cleared upon a successful commit of the transaction.	setClearCacheOnCommit() Note: Default is false
Decide whether entity caches will be cleared upon a rollback of the transaction.	setClearCacheOnRollback() Note: Default is true
Clear the entity cache for a specific entity object.	clearEntityCache()

D.1.3 ViewObject Interface

A ViewObject encapsulates a database query and simplifies working with the RowSet of results it produces. You use view objects to project, filter, join, or sort business data using SQL from one or more tables into exactly the format that the user should see it on the page or panel. You can create "master/detail" hierarchies of any level of depth or complexity by connecting view objects together using view links. View objects can produce read-only query results, or by associating them with one ore more entity objects at design time, can be fully updatable. Updatable view objects can support insertion, modification, and deletion of rows in the result collection, with automatic delegation to the correct business domain objects.

Every ViewObject aggregates a "default rowset" for simplifying the 90% of use cases where you work with a single RowSet of results for the ViewObject's query. A ViewObject implements all the methods on the RowSet interface by delegating them to this default RowSet. That means you can invoke any RowSet methods on any ViewObject as well.

Every ViewObject implements the StructureDef interface to provide information about the number and types of attributes in a row of its row sets. So you can call StructureDef methods right on any view object.

Table D-3 ViewObject Interface

If you want to...	Call this ViewObject interface method...
Set an additional runtime WHERE clause on the rowset	setWhereClause() Note: This WHERE clause augments any WHERE clause specified at design time in the base view object. It does not replace it.
Set a dynamic ORDER BY clause	setOrderByClause()
Create a Query-by-Example criteria collection	createViewCriteria() Note: You then create one or more ViewCriteriaRow objects using the createViewCriteriaRow() method on the ViewCriteria object you created. Then, you add() these view criteria rows to the view criteria collection and apply the criteria using the method below.
Apply a Query-by-Example criteria collection	applyViewCriteria()
Set a query optimizer hint	setQueryOptimizerHint()
Access the attribute definitions for the key attributes in the view object	getKeyAttributeDefs()
Add a dynamic attribute to rows in this view object's row sets	addDynamicAttribute()
Clear all row sets produced by a view object	clearCache()
Remove view object instance an its resources	remove()
Set an upper limit on the number of rows that the view object will attempt to fetch from the database.	setMaxFetchSize() Note: Default is -1 which means to impose no limit on how many rows would be retrieved from the database if you iterate through them all. By default they are fetched lazily as you iterate through them.

In addition to generic ViewObject access, JDeveloper 10g can generate you a custom YourViewObjectName interface containing view-object level custom methods that you've chosen to expose to the client. You do this by visiting the Client Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourViewObjectNameClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

D.1.4 RowSet Interface

A RowSet is a set of rows, typically produced by executing a ViewObject's query.

Every RowSet aggregates a "default rowset iterator" for simplifying the 90% of use cases where you only need a single iterator over the rowset. A RowSet implements all the methods on the RowSetIterator interface by delegating them to this default RowSetIterator. This means you can invoke any RowSetIterator method on any RowSet (or ViewObject, since it implements RowSet as well for its default RowSet).

Table D-4 RowSet Interface

If you want to...	Call this RowSet interface method...
Set a where clause bind variable value	setWhereClauseParam() Note: Bind variable ordinal positions are zero-based
Avoid view object row caching if data is being read only once	setForwardOnly()
Force a row set's query to be (re)executed	executeQuery()
Estimate the number of rows in a view object's query result	getEstimatedRowCount()
Produce XML document for rows in View Object rowset	writeXML()
Process all rows from an incoming XML document	readXML()
Set whether rowset will automatically see new rows based on the same entity object created through other rowsets	setAssociationConsistent()
Create secondary iterator to use for programmatic iteration	createRowSetIterator() Note: If you plan to find and use the secondary iterator by name later, then pass in a string name as the argument, otherwise pass null for the name and make sure to close the iterator when done iterating by calling its closeRowSetIterator() method.

D.1.5 RowSetIterator Interface

A RowSetIterator is an iterator over the rows in a RowSet. By default it allows you to iterate both forward and backward through the rows.

Table D-5 RowSetIterator Interface

If you want to...	Call this RowSetIterator interface method...
Get the first row of the iterator's rowset	first()
Test whether there are more rows to iterate	hasNext()
Get the next row of iterator's rowset	next()
Find row in this iterator's rowset with a given Key value	findByKey() Note: It's important that the Key object that you pass to findByKey be created using the exact same datatypes as the attributes that comprise the key of the rows in the view object you're working with.
Create a new row to populate for insertion	createRow() Note: The new row will already have default values set for attributes which either have a static default value supplied at the entity object or view object level, or if the values have been populated in an overridden create() method of the underlying entity object(s).
Create a view row with an initial set of foreign key and/or discriminator attribute values	createAndInitRow() Note: You use this method when working with view objects that can return one of a "family" of entity object subtypes. By passing in the correct discriminator attribute value in the call to create the row, the framework can create you the correct matching entity object subtype underneath.
Insert a new row into the iterator's rowset	insertRow() Note: It's a good habit to always immediately insert a newly created row into the rowset. That way you will avoid a common gotcha of creating the row but forgetting to insert it into the rowset.
Get the last row of the iterator's rowset	last()
Get the previous row of the iterator's rowset	previous()
Reset the current row pointer to the slot before the first row	reset()
Close an iterator when done iterating	closeRowSetIterator()
Set a given row to be the current row	setCurrentRow()
Remove the current row	removeCurrentRow()
Remove the current row to later insert it at a different location in the same iterator.	removeCurrentRowAndRetain()
Remove the current row from the current collection but do not remove it from the transaction.	removeCurrentRowFromCollection()
Set/change the number of rows in the range (a "page" of rows the user can see)	setRangeSize()
Scroll to view the Nth page of rows (1-based)	scrollToRangePage()
Scroll to view the range of rows starting with row number N	scrollRangeTo()
Set row number N in the range to be the current row	setCurrentRowAtRangeIndex()
Get all rows in the range as a Row array	getAllRowsInRange()

D.1.6 Row Interface

A Row is generic value object. It contains attributes appropriate in name and Java type for the ViewObject that it's related to.

Table D-6 Row Interface

If you want to...	Call this Row interface method...
Get the value of an attribute by name	getAttribute()
Set the value of an attribute by name	setAttribute()
Produce an XML document for a single row	writeXML()
Eagerly validate a row	validate()
Read row attribute values from XML	readXML()
Remove the row	remove()
Flag a newly created row as temporary (until updated again)	setNewRowState(Row.STATUS_INITIALIZED)
Retrieve the attribute structure definition information for a row	getStructureDef()
Get the Key object for a row	getKey()

In addition to generic Row access, JDeveloper 10g can generate you a custom YourViewObjectNameRow interface containing your type-safe attribute getter and setter methods, as well as any desired row-level custom methods that you've chosen to expose to the client. You do this by visiting the Client Row Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourViewObjectNameRowClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

D.1.7 StructureDef Interface

A StructureDef is an interface that provides access to runtime metadata about the structure of a Row.

In addition, for convenience every ViewObject implements the StructureDef interface as well, providing access to metadata about the attributes in the resulting view rows that its query will produce.

Table D-7 StructureDef Interface

If you want to...	Call this StructureDef interface method...
Access attribute definitions for all attributes in the view object row	getAttributeDefs()
Find an attribute definition by name	findAttributeDef()
Get attribute definition by index	getAttributeDef()
Get number of attributes in a row	getAttributeCount()

D.1.8 AttributeDef Interface

An AttributeDef provides attribute definition information for any attribute of a View Object row or Entity Object instance like attribute name, Java type, and SQL type. It also provides access to custom attribute-specific metadata properties that can be inspected by generic code you write, as well as UI hints that can assist in rendering an appropriate user interface display for the attribute and its value.

Table D-8 AttributeDef Interface

If you want to...	Call this AttributeDef interface method...
Get the Java type of the attribute	getJavaType()
Get the SQL type of the attribute	getSQLType() Note: The int value corresponds to constants in the JDBC class java.sql.Types
Determine the kind of attribute	getAttributeKind() Note: If it's a simple attribute, it returns one of the constants ATTR_PERSISTENT, ATTR_SQL_DERIVED, ATTR_TRANSIENT, ATTR_DYNAMIC, ATTR_ENTITY_DERIVED. If it is an 1-to-1 or many-to-1 association/viewlink accessor it returns ATTR_ASSOCIATED_ROW. If it is an 1-to-many or many-to-many association/viewlink accessor it returns ATTR_ASSOCIATED_ROWITERATOR
Get the Java type of elements contained in an Array-valued attribute	getElemJavaType()
Get the SQL type of elements contained in an Array-valued attribute	getElemSQLType()
Get the name of the attribute	getName()
Get the index position of the attribute	getIndex()
Get the precision of a numeric attribute or the maximum length of a String attribute	getPrecision()
Get the scale of a numeric attribute	getScale()
Get the underlying column name corresponding to the attribute	getColumnNameForQuery()
Get attribute-specific custom property values	getProperty(), getProperties()
Get the UI AttributeHints object for the attribute	getUIHelper()
Test whether the attribute is mandatory	isMandatory()
Test whether the attribute is queriable	isQueriable()
Test whether the attribute is part of the primary key for the row	isPrimaryKey()

D.1.9 AttributeHints Interface

The AttributeHints interface related to an attribute exposes UI hint information that attribute that you can use to render an appropriate user interface display for the attribute and its value.

Table D-9 AttributeHints Interface

If you want to...	Call this AttributeHints interface method...
Get the UI label for the attribute	getLabel()
Get the tool tip for the attribute	getTooltip()
Get the formatted value of the attribute, using any format mask supplied	getFormattedAttribute()
Get the display hint for the attribute	getDisplayHint() Note: Will have a String value of either Display or Hide.
Get the preferred control type for the attribute	getControlType()
Parse a formatted string value using any format mask supplied for the attribute	parseFormattedAttribute()