Accessing the View Object for Programmatic Access to Business Objects

A "view object" is an Oracle ADF component that simplifies querying and working with business object rows. The newView() function allows you to access a view object dedicated to programmatic access for a given business object.

By default, any custom object you create is enabled to have such a view object, and selected standard objects will be so-enabled by the developers of the original application you are customizing. Each time the newView(objectAPIName) function is invoked for a given value of object API name, a new view object instance is created for its programmatic access. This new view object instance is in a predictable initial state. Typically, the first thing you will then do with this new view object instance is:

Call the findByKey() function on the view object to find a row by key, or
Append a view criteria to restrict the view object to only return some desired subset of business objects rows that meet your needs, as described in Finding Objects Using a View Criteria.

A view object will typically be configured to return its results in sorted order. If the default sort order does not meet your needs, you can use the setSortBy() method on the view object to provide a comma-separated list of field names on which to sort the results. The new sort order will take effect the next time you call the executeQuery() method on the view object. See Defining the Sort Order for Query Results for further details on sorting options available.

A view object instance for programmatic access to a business object is guaranteed not to be used by any application user interface pages. This means that any iteration you perform on the view object in your script will not inadvertently affect the current row seen in the user interface. That said, the end user will see the results of any field values that you change, any new rows that you add, and any existing rows that you modify, presuming that they are presently on a page where said objects and fields are visible.

For example, suppose the user interface is displaying an employee along with the number and associated name of the department in which she works. If a script that you write...

uses newView() to obtain the view object for programmatic access for the Department object, then
uses findByKey() to find the department whose id matches the current employee's department, and finally
changes the name of the current employee's department

then this change should be reflected in the screen the next time it is updated. Once you've accessed the view object, the most common methods that you will use on the view object are shown in the following table.

Most Commonly Used View Object Methods

Method Name	Description
`findByKey()`	Allows you to find a row by unique id. Returns: an array of rows having the given key, typically containing either zero or one row. Parameters: `key` - a key object representing the unique identifier for the desired row `maxRows` - an integer representing the maximum number of rows to find (typically `1` is used) Example: See Finding an Object by Id
`findRowsMatchingCriteria()`	Allows you to find a set of matching rows based on a filter criteria. Returns: an iterator you can use to process the matching rows using methods `iter.hasNext()` and `iter.next()` ofr one row. Parameters: `viewCriteria` - a view criteria representing the filter. The easiest way to create a new view criteria is to use the `newViewCriteria()` function. `maxRows` - an integer representing the maximum number of rows to find ( `-1` means return all matching rows up to a limit of `500`) Example: See Finding Rows in a Child Rowset Using findRowsMatchingCriteria
`appendViewCriteria()`	Appends an additional view criteria query filter. Parameters: `filterExpr` - a String representing a filter expression. `ignoreNullBindVarValues` - an optional boolean parameter indicating whether expression predicates containing null bind variable values should be ignored (defaults to false if not specified). Returns: - `void`. Alternatively, if you already have created a view criteria using `newViewCriteria()` you can pass that view criteria as the single argument to this function.
`executeQuery()`	Executes the view object's query with any currently appended view criteria filters. Returns: - `void`.
`hasNext()`	Returns: - `true` if the row iterator has more rows to iterate over, `false` if there are no further rows in the iterator or it is already on or beyond the last row.
`next()`	Returns: - the next row in the iterator
`reset()`	Resets the view object's iterator to the "slot" before the first row. Returns: - `void`.
`first()`	Returns: - the first row in the row iterator, or `null` if the iterator's row set is empty
`createRow()`	Creates a new row, automatically populating its system-generated `Id` primary key field. Returns: - the new row
`insertRow()`	Inserts a new row into the view object's set of rows. Returns: - `void`
`setSortBy()`	Set the sort order for query results. Returns: - `void`