Skip Headers

Oracle® Application Development Framework Development Guidelines Manual 10g Release 2 (10.1.2) Part No. B14362-02 |
| Library | Product | Contents

Previous | Next |

# 4 Overview of the Oracle ADF Model Layer

The Oracle Application Development Framework (Oracle ADF) in JDeveloper supports data controls based on Java classes, EJB session beans, web services, and Oracle ADF application modules. The Oracle ADF components, including data controls and data bindings, are configured using XML metadata. This capability allows a small set of framework base classes to handle most of the application development needs without coding. In JDeveloper, you use the design time to expose desired business service data sources in the Oracle ADF model layer. The design time tools lets all developers visualize the exposed business services in a uniform way.

This chapter provides an overview of how you can work with JDeveloper to create the Oracle ADF data controls and data binding objects of the ADF model layer. Creating the Oracle ADF model layer objects is a preliminary step to working with the data binding objects in the application controller and view layers, as is described in Overview of Oracle ADF Integration with Struts and Overview of Oracle ADF Data Binding in View Technologies.

## 4.1 Summary

- Role of the Model Layer

  - About MetaData for the Oracle ADF Binding Context

  - Oracle ADF Model API Overview

- Benefiting from the Oracle ADF Model Layer

  - Role of the Oracle ADF Data Controls

  - Role of the Oracle ADF Bindings

  - Generic Runtime Properties for All Oracle ADF Bindings

- Oracle ADF Data Control Runtime Integration with Business Services

- Creating the Oracle ADF Model Layer in JDeveloper

  - Oracle ADF Business Components as Data Controls

  - Oracle ADF Data Controls for EJB Components

  - Oracle ADF Data Controls for Web Services

  - Oracle ADF Data Controls for JavaBeans and TopLink-Based Beans Components

- Summary of Oracle ADF Data Control Operations

- Summary of Oracle ADF Bindings

  - About the Iterator Binding

  - About the Value Bindings

  - About the Action Binding

## 4.2 Role of the Model Layer

In a J2EE application that uses the Oracle ADF model, model data is surfaced to the view and controller layers through data control objects implemented for each type of data provider. A model-specific set of data controls:

- Manages the J2EE application's connection to the data provider

- Presents bindings and binding containers to the J2EE application client or controller

Once the data is surfaced by data control adapter classes, interaction with the business service by the J2EE application is possible by any method that acts on or retrieves data from data objects and collections (also described as rows and row sets).

### 4.2.1 About MetaData for the Oracle ADF Binding Context

Using the JDeveloper design time, you create a set of XML files that declaratively define the Oracle ADF data controls and data bindings. At runtime, the application creates the Oracle ADF binding context from the files in the application, as shown in the following diagram.

The client binding description file (`.cpx`) references the binding definitions in the client binding container definition files (`.xml`). The `.cpx` file also contains a reference to the data control description file (`.dcx`), which specifies the data control factory to use for a specific business service.

The design time supports creating these files through your interaction with the Data Control Palette, a visual editor, the Structure window, and the Property Inspector. After you use the Data Control Palette to insert a databound UI component into the displayed web page or JClient panel, the binding definition is created in the document's binding definition file. Additionally, source code is added to the document that references the binding objects, which the application makes available through the Oracle ADF binding context `bindings` namespace.

For more information about the generated project files and design time tools, see Overview of Oracle ADF Data Binding in View Technologies.

### 4.2.2 Oracle ADF Model API Overview

Specifically, these objects in the ADF model layer provide runtime access to business services:

- Binding context object (`oracle.adf.model.BindingContext`)

  Defines a common namespace for use by the client application and allows all model objects to be exposed through a convenient root name. Each web page or Java panel registers with the binding context using the definition for the variable name `binding`.

- Data control interfaces (`oracle.adf.model.binding.DCDataControl`)

  Provides the client application with an interface into the model objects. One data control is needed to wrap the model objects of each business service configuration. Also, in the case of a JavaBeans model object, provides direct access to the native object, when programmatic access is desired.

- Binding container objects (`oracle.adf.model.binding.DCBindingContainer`)

  Defines a container for data binding objects, including iterator bindings and control bindings. One binding container is created for each web page or Java panel, but may be reused in multiple pages and panels when they share the same data. The binding container object also lets you specify whether the page or panel is to be used in data entry mode or query mode.

- Iterator binding objects (`oracle.adf.model.binding.DCIteratorBinding`)

  Handles the events generated from the associated business service row iterator and sends the current row to individual control bindings to display current data. Iterator bindings can specify the number of rows to display in a web page.

- Control binding objects (`oracle.jbo.uicli.binding.JUControlBinding`)

  Defines the way a specific UI component interacts with the corresponding business service. For example, depending upon the control binding selection, a text field may be bound to an Oracle ADF Business Components view object attribute and display as an editable field or a static label. Or, if the business service attribute defines an enumerated list of values, the bound UI component might display a static list, a single-selection list, or a multi-selection list. Other more complex UI components, such as table and graphs, are also supported by their own control bindings.

- Action binding objects (`oracle.jbo.uicli.binding.JUCtrlActionBinding`)

  At runtime, when the user initiates the action, using a button control, the action binding accesses the Oracle ADF binding context and initiates the specified action on the data objects of the selected collection. Action bindings can take parameters that will be passed to the controller to handle.

## 4.3 Benefiting from the Oracle ADF Model Layer

### 4.3.1 Role of the Oracle ADF Data Controls

Oracle ADF data controls provide an abstraction of the business service's data model. The Oracle ADF data controls provide a consistent mechanism for clients and web application controllers to access data and actions defined by these diverse data-provider technologies:

- Oracle ADF Business Components

- JavaBeans, including TopLink Plain Old Java Objects (TopLink POJO)

- EJB session beans

- Web services

For most of these, the data controls are implemented by a thin layer of adapter classes. The exception is Oracle ADF Business Components technology, which implements the data controls directly in the component classes.

Oracle ADF data controls are represented on the Data Control Palette, where they can be added to the view as UI controls or to the controller as operations.

The remainder of this section provides an overview of the base features of the provided data controls. The following terms have these definitions:

- Business service: Any JavaBean that publishes business objects and provides methods that manipulate business objects. Examples of business services include web services, EJB session beans, or any Java class being used as an interface to some functionality.

- Business object: A JavaBean that models a business entity. Business objects are typically persisted to a data source. Examples of business objects in an order entry application may include Order, Customer, and Product.

- Data collection: A collection of business objects. A collection may be an instance of `java.util.Collection`, `java.util.Iterator`, or `java array`, or a single business object that is treated as a collection of one.

#### 4.3.1.1 Business Object Access Services

The business object access services provide built-in Oracle ADF support for binding to data collections and business objects using a business service or a business object. The business object access services are:

- Business collection iteration services

  The Oracle ADF data controls provide an Iterator pattern implementation that may be used with any business collection. You may use built-in operations on this iterator binding implementation to display or iterate business objects. Examples of operations include first, next, previous, and last.

- Find and refresh services

  The Oracle ADF model provides features for defining search parameters for a page model or an ADF model layer iterator. You may use built-in operations to toggle the Oracle ADF model find mode for defining search parameters and to refresh the Oracle ADF model layer iterator bindings.

- Business object property services

  The Oracle ADF model provides features for accessing JavaBeans-style properties of business objects. You may use built-in operations to bind to business object properties. A special class of business object properties includes properties whose accessor methods (like `Customer.getOrders()`) access business collections. These properties are referred to as accessor attribute properties or accessor attributes.

- Method invocation services

  The Oracle ADF model provides features for invoking business object and business service methods. You may use built-in operations to invoke methods and to bind iterators to the results of operations.

#### 4.3.1.2 Transaction Services

The transaction services provide built-in Oracle ADF model layer support for mutating business objects. Please note that the Oracle ADF model transaction services do not provide a transaction system itself. Instead, the Oracle ADF model transaction services provide a notification system that individual Oracle ADF data controls integrate with. The presence of a notification system allows custom Oracle ADF data controls to be created that can integrate a model transaction service with the Oracle ADF model layer.

The transaction services are:

- Business object services

  The Oracle ADF model provides features for adding business objects to a collection, for removing business objects from a collection, and for mutating the JavaBeans-style properties of business objects. You may use built-in operations to invoke these services, and the Oracle ADF model layer will automatically notify the Oracle ADF data control of a create, remove, or update event.

- Transaction demarcation services

  The Oracle ADF model provides features for committing and rolling back transactions. You may use built-in operations to notify the Oracle ADF data control to commit or roll back transaction changes.

#### 4.3.1.3 State Management Services

The state management services provide built-in Oracle ADF model layer support for managing Oracle ADF data control user state. The state management services are:

- Data control lifecycle notifications

  The Oracle ADF model provides Oracle ADF data control lifecycle notifications to the Oracle ADF data control. The individual data controls implement these notifications to passivate or activate the business service user state.

- State distribution services

  The Oracle ADF model provides features to distribute state or to fail over state to other tiers.

For further details about the design time for working with the Oracle ADF model layer and the code generated by the design time, see Creating the Oracle ADF Model Layer in JDeveloper.

### 4.3.2 Role of the Oracle ADF Bindings

Oracle ADF provides several types of binding objects to support the attributes and operations exposed by the Oracle ADF data controls for a particular business object:

- Iterator binding, one per accessor attribute that your page or panel displays. Iterates over the business objects of the data collection and maintains the row currency and state.

- Value bindings, one for each databound UI component. Provides access to data.

- Action binding, one for each button component. Provides access to operations defined by the business object.

You create these bindings in JDeveloper through your interaction with the Data Control Palette, a visual editor, the Structure window, and the Property Inspector. You can view the binding in your application in any one of several ways:

In the source code view of a web page, where binding references appear in expressions that get evaluated at runtime using the expression language (EL) features. In the code view, the expression looks like this:

    <c:forEach var="rv"
                items="${bindings.DataBindingObject.theCollectionProperty}"

The data binding object accesses the Oracle ADF binding container through the `bindings` variable, which is a variable that specifies the namespace for the binding containers in the Oracle ADF binding context. The binding container is initialized for Model 2–style web applications in the Oracle ADF class `oracle.adf.controller.struts.actions.DataAction`.

Note: Although a data action class does not appear in your project, you can see that the action mapping for data action appears in the `struts-config.xml` file, which defines the `modelReference` property to initialize the binding container from the `pageNameUIModel.xml` file.

- In the code view of a JClient panel or form, where the `setModel()` method call on the UI component initializes the data binding object and accesses the binding container through the ADF binding context (specified by the `setBindingContext()` method call on the data panel).

The binding container is initialized from the `PanelNameUIModel.xml` file in the JClient project when the panel binding is created (by the `JUPanelBinding panelBinding` constructor).

- In the Structure window for either client type (web page or JClient panel), where the data binding objects defined for each UI component in your view document appear in the UI Model tab. To edit the declarative properties of the binding definitions, right-click and choose Edit. To understand what values you can set for runtime-only properties, select the binding node and press F1.

### 4.3.3 Generic Runtime Properties for All Oracle ADF Bindings

When you create a databound component using the Data Control Palette, JDeveloper adds metadata to the `UIModel.xml` file defined for your view-controller project. The metadata determines the default display characteristics of each databound UI component and sets properties of the binding object at runtime. You can work with the data binding metadata through:

- Design time editors that you display on specific bindings in the UI Model tab of the Structure window

  Additionally, each binding's implementing class defines methods that give you access to runtime information about the binding. You can work with runtime-specific properties through:

- EL expressions that you insert into the HTML of your web page when you want to access the runtime properties of the value binding object

  The `oracle.jbo.uicli.binding.DCControlBinding` class provides accessor methods for these properties that are accessible by all value bindings:

- error returns any cached exception which was raised during the invocation of the method or action to which the binding is bound.

- fullName returns the fully qualified name of the binding object in the Oracle ADF binding context.

- iteratorBinding returns the iterator binding that provides access to the data collection.

- name returns the name of the binding object in the context of the binding container to which it is registered.

- rowKeyStr returns the key of the data collection. The key specifies the location of the data object and is returned in its String format.

## 4.4 Oracle ADF Data Control Runtime Integration with Business Services

At runtime, the interaction with the business services initiated from the client or controller is managed by the application through a single object known as the Oracle ADF model binding context. The Oracle ADF binding context is a container object that defines a hierarchy of data controls and data binding objects derived from the Oracle ADF model layer, as shown in the following figure.

The binding context defines these hierarchies, whose objects reference one another in order to allow the Oracle ADF model to service the controller and view layers.

The hierarchy for the data controls looks like this:

- binding context -> data controls

The hierarchy for the data binding objects, which also starts from the same parent container, looks like this:

- binding context -> binding container -> iterator bindings

and, additionally:

- binding context -> binding container -> data control binding -> value bindings and action bindings

The following diagram depicts binding container containment hierarchy in detail. Note that the definition of the binding context and the data binding objects available to the application are specified by XML-based files at the level of the client project. For details about the client project, see Overview of Oracle ADF Data Binding in View Technologies.

Through the iterator binding's object hierarchy path, the iterator binding accesses the data collection and iterates over its data objects. In contrast, value binding objects allow UI components to display or update the current data object of the collection being iterated over.

For example, in the source of the web page or Java panel, a UI component's value binding definition references the page or panel's iterator binding object. The iterator binding object, in turn, references the data controls, which completes the data-access path and allows the Oracle ADF model to traverse the object hierarchy:

1. Starting from an event (such as rendering the data) that is received by the control binding

2. All the way back to the data controls, specified by the binding context, that interact finally with business services

   Note: The above description has been simplified to include both web applications and Java client applications. In an actual web application, the controller layer is responsible for populating the Oracle ADF model binding context prior to dispatching to the view layer. Then, following the pull model for interactive web applications, the view layer pulls the data to render values in the page.

## 4.5 Creating the Oracle ADF Model Layer in JDeveloper

Oracle ADF data controls permit the application client to access business services defined by your application's model object layer. Business services can be any collection, value, or action that your model project defines. At runtime, the Oracle ADF binding context is initialized with the data control definition to permit databound UI components to access the business services.

Before you create data controls, ensure that you have created (or otherwise have access to) business services.

### 4.5.1 Oracle ADF Business Components as Data Controls

Note: You do not need to create data controls for Oracle ADF Business Components—Oracle ADF BC data model components already implement the data control interfaces.

If you use Oracle ADF Business Components as your business service technology, your data model components will be exposed in the model layer as Oracle ADF data controls, as shown in the following figure.

1 The application module

This node represents the top-level application module itself (nested application modules are represented by the same icon). Directly under this node, you can find nested application modules, top-level view object instances, and application module–level methods.

2 Row sets

These nodes represent row sets—usually view object instances in the data model, but also the row sets returned by view link accessors. In this case, AllDepartments represents a top-level view object instance, DepartmentEmployees represents a detail instance of AllDepartments, and both DeptMgrFkLinkDetail and EmpMgrFkLinkDetail represent the static row sets returned by view link accessors of the same name. For more information on view links, see the JDeveloper help system.

3 Attributes

These nodes represent individual view object attributes.

4 Standard operations

These nodes represent standard row set–level operations. The application module has similar nodes that represent transaction-level operations. The operations available for a row set include previous set and next set, which scroll through the row set based on range size. For more information, see Summary of Oracle ADF Data Control Operations.

5 Special navigation operations

These nodes allow you to set the row set's current row to a particular displayed row.

6 Custom method

Exported custom service methods will appear on the Data Control Palette.

### 4.5.2 Oracle ADF Data Controls for EJB Components

If you use EJB technology as your business service technology, model information will be exposed to the view and controller layers through Oracle ADF data control interfaces implemented by thin, Oracle-provided adapter classes.

To create adapter classes and data controls:

1. In the navigator, select the Model project which contains the model objects you want to expose to the application client.

2. In the model project, right-click a stateless session bean and choose Create Data Control.

   OR

3. Drag the session bean from the Application Navigator onto the Data Control Palette to create the data controls.

   Note: You can create data controls only from stateless session beans. If your bean defines attributes or methods that return a `Collection` type, you must specify the return type for the data control. JDeveloper adds the data control definition file (`DataControls.dcx`) to the model project. The `.dcx` file identifies the Oracle ADF model layer adapter classes that facilitate the interaction between the client and the available business services.

To view the business services you have registered for use with your client application:

- If the palette is not yet displayed, choose View | Data Control Palette.

  OR

- If the palette is already displayed, right-click in the palette and choose Refresh Palette.

If you use EJB technology as your business service technology, model information will be exposed to the view and controller layers through Oracle ADF data control interfaces implemented by thin, Oracle-provided adapter classes, as shown in the following figure.

1 The data control

This node represents the data control, which in this case is a session facade. Drag a stateless session bean from the navigator and drop it onto the Data Control Palette to create the Oracle ADF data control or to refresh its contents.

2 Row sets

These nodes represent collections:

- AllDepartments is a collection of the Departments DTO.

- employees_departmentIdDTO is a collection within AllDepartments, equivalent to a master-detail relationship.

3 Attributes

These nodes represent individual attributes.

4 Standard operations

These nodes represent standard collection operations. The session facade has similar nodes that represent transaction-level operations. The operations available for a collection include previous set and next set, which scroll through the data based on range size.

5 Special navigation operations

These nodes allow you to set the row set's current row to a particular displayed row.

6 Custom method

Custom service methods will appear on the Data Control Palette.

There are four files that are generated when you create a data control from a session bean, two Java files and two XML files. The JDeveloper design time creates the XML files automatically to facilitate such things as resolving accessor types in the Property Inspector. The four generated files are:

- `SessionEJB.xml` is a generated XML document that represents all JavaBeans surfaced through the ADF data controls, other than built-in classes like `java.lang.String`. The `create()` method exposed through the session EJB data control returns a session EJB instance. This is the XML file to represent that Java type.

- `SessionEJBDataControl.java` is a generated Java class that provides a JavaBeans wrapper to expose the stateless session bean's remote (or local, if no remote interface is exposed) methods, delegating the method requests to a lazily-created session bean instance.

- `SessionEJBDataControl.xml` is an XML document that may be edited through the Property Inspector, typically to assign member type information for collection or list methods exposed through the session bean's component interface.

- `SessionEJBDataControlBeanInfo.java` is the BeanInfo class for `SessionEJBDataControl.java`. The BeanInfo class serves to filter out noncomponent interface methods.

### 4.5.3 Oracle ADF Data Controls for Web Services

If you use web services as your business service technology, model information will be exposed to the view and controller layers through Oracle ADF data control interfaces implemented by thin, Oracle-provided adapter classes.

JDeveloper creates Oracle ADF data controls for a web service by generating a stub or proxy to the service, and creating the data controls from the stub. Any web service is available to be exposed as a data control in JDeveloper as long as the design time can create a stub for that web service.

You can create data controls for web services that you have created in JDeveloper as part of your application with just one mouse-click. The process of creating data controls for external web services, that is web services somewhere on the Web, is different in that you have to make the WSDL document available in the navigator first. Creating data controls is described for both these cases below.

Finally, you can view the business services you have registered for use with your client application.

#### 4.5.3.1 Creating Data Controls for Web Services Created in JDeveloper

You can incorporate the functionality of a web service that you have created in JDeveloper in your application. This can be either a SOAP web service or a J2EE web service, and in either case the service should be deployed in the usual manner before creating data controls. When you have created a web service in JDeveloper, the web service container is listed in the navigator.

To create data controls for a web service created in JDeveloper:

- With the web service deployed, right-click the web service container in the navigator and choose Create Data Control. Alternatively, drag the web service container node to the Data Control Palette.

  OR

- With the web service container selected in the navigator, right-click the WSDL in the Structure window and choose Create Data Control. Alternatively, drag the WSDL node to the Data Control Palette.

#### 4.5.3.2 Creating Data Controls for External Web Services

When you know the URL of the WSDL document, you need to make the WSDL available in the Application Navigator before you can create data controls for the service. There are two ways to do this:

- By creating a new WSDL document and importing the external WSDL document into it

- By creating a stub to the web service, and allowing the wizard to add the WSDL document to the navigator

Another way of using an external web service in an Oracle ADF application is to locate the service in a UDDI registry, and create the data controls from the Connection Navigator.

These three cases are described below.

To create data controls for an external web service by creating a new WSDL document:

1. Create a new WSDL document, accepting the defaults.

2. In a browser, open the WSDL document of the external web service you want to use as the service provider. View the source of the document, and copy the XML source of the WSDL.

3. Replace the contents of the WSDL document you have just created with the source from the WSDL document of the web service you want to create data controls for.

4. Right-click the WSDL document and choose Create Data Control. Alternatively, drag the WSDL node from the navigator to the Data Control Palette.

To create data controls for an external web service using a wizard:

1. Create a stub to the web service, and paste the WSDL URL into the WSDL Document URL field on the Select Web Service Description page. On the same page, select Import WSDL URL Into Project, and complete the wizard.

2. Right-click the WSDL document and choose Create Data Control. Alternatively, drag the WSDL node from the navigator to the Data Control Palette.

To create data controls for a web service located in a UDDI registry:

1. Locate the web service in the UDDI registry. The service is listed in the Connection Navigator under the UDDI registry node.

2. Right-click the web service and choose Create Data Control, as shown in the following figure.

To view the business services you have registered for use with your client application:

- If the palette is not yet displayed, choose View | Data Control Palette.

  OR

- If the palette is already displayed, right-click in the palette and choose Refresh Palette.

If you use web services as your business service technology, model information will be exposed to the view and controller layers through ADF data control interfaces implemented by thin, Oracle-provided adapter classes, as shown in the following figure.

1 Web Service Data Control

The MyWebService1DataControl is the data control node. It is created by right-clicking on the web service container MyWebService1 in the navigator, and choosing Crea t e Data Control.

2 Operations

Under the Operations node you can find the available web methods for the web service.

3 Data Control Associated with Web Service Method

The returnAllPersons() node is the data control associated with the web service.

4 return Node

This node is the return from the method on the web service.

#### 4.5.3.3 Web Services That Return Arrays

When a web service returns an array, it is important that the array node be the one used to provide the return values in the application, as shown in the following figure.

The following files are created:

- `DataControls.dcx` identifies the Oracle ADF model layer adapter classes that facilitate the interaction between the client and the available business services.

- `<WebService>``.xml`, which contains metadata used by the data control.

- `<WebService>``.java`, which contains connection information to the service.

- `<WebService>``BeanInfo.java`, which provides the methods available in the web service.

- `<Bean>``.java` is created when you register an external web service from the WSDL node in the Application Navigator, and it acts as a proxy to the service.

### 4.5.4 Oracle ADF Data Controls for JavaBeans and TopLink-Based Beans Components

If you use JavaBeans technology as your business service technology, model information will be exposed to the view and controller layers through Oracle ADF data control interfaces implemented by thin, Oracle-provided adapter classes.

Note: Your JavaBean may have been created based on TopLink mappings that you specified.

To create adapter classes and data controls:

1. In the navigator, select the Model project which contains the model objects you want to expose to the application client.

2. In the model project, right-click the bean and choose Create Data Control.

   OR

   Drag the bean from the Application Navigator onto the Data Control Palette to create the data controls.

3. If your bean defines attributes or methods that return a `Collection` type, you must specify the return type for the data control.

JDeveloper adds the data control definition file (`DataControls.dcx`) to the model project. The `.dcx` file identifies the Oracle ADF model layer adapter classes that facilitate the interaction between the client and the available business services.

To view the business services you have registered for use with your client application:

- If the palette is not yet displayed, choose View | Data Control Palette.

  OR

- If the palette is already displayed, right-click in the palette and choose Refresh Palette.

If you use JavaBeans technology as your business service technology, model information will be exposed to the view and controller layers through ADF data control interfaces implemented by thin, Oracle-provided adapter classes.

If you use Oracle TopLink POJO to create JavaBeans as your business service technology, your application can also use Oracle ADF data controls to access them.

For more information, see the TopLink documentation provided by the JDeveloper help system.

## 4.6 Summary of Oracle ADF Data Control Operations

When you create and register business services for an application, the Data Control Palette displays two types of actions:

- Actions that typically operate on all data collections in the current web page's binding context (such as commit and rollback) in the Operations folder at the root level of the hierarchy.

- Operations on a specific data collection (for example, EmployeesView). Data collection–specific operations (such as create and delete) appear in the Operations folder as child nodes of the collection in the Data Control Palette.

Typical data control–level, global actions defined by business services include:

- Commit commits a transaction that updates the values of data objects from the bound data collection to the database.

- Rollback rolls back a transaction meant to update the values of data objects in the bound data collection. No data is sent to the database.

Typical data collection–specific operations defined by business services include:

- Create creates a new data object in the bound data collection.

- Delete deletes the current data object from the bound data collection.

- Execute executes the bound action defined by the data collection. In the case of a JavaBean, the execute operation will refresh the data control.

- Find retrieves a data object from the data collection.

- First navigates to the first data object in the data collection range.

- Last navigates to the last data object in the data collection range.

- Next navigates to the next data object in the data collection range. If the current range position is already on the last data object, then no action is performed.

- Next Set moves the viewable range to the first data object after the current range position defined by the bound data collection. For example, when the data collection is a row set, next set navigates to the first row after the current range position. If the current range position is already on the last set, then no action is performed.

  Note: This operation is available only with Oracle ADF Business Components.

- Previous navigates to the previous data object in the data collection range. If the current position is already on the first data object, then no action is performed.

- Previous Set moves the viewable range to the data objects located just before the current range defined by the bound data collection. For example, when the data collection is a row set, previous set navigates to the last row before the current range position. If the current range position is already on the first set, then no action is performed.

  Note: This operation is available only with Oracle ADF Business Components.

- setCurrentRowWithKey(String) passes the row key as a String converted from the value specified by the input field. The row key is used to set the currency of the data object in the bound data collection. When passing the key, the URL for the form will not display the row key value. You may use this operation when the data collection defines a multipart attribute key.

- setCurrentRowWIthKeyValue(String) passes the row key as a String specified by the input field. The row key is used to set the currency of the data object in the bound data collection. Use this operation only when the data collection uses a single key attribute and does not define a multipart attribute key. When passing the key as a value, the URL for the form will display the row key value.

## 4.7 Summary of Oracle ADF Bindings

Oracle ADF provides these types of bindings:

- About the Iterator Binding

- About the Value Bindings

- About the Action Binding

### 4.7.1 About the Iterator Binding

The `oracle.jbo.uicli.binding.JUIteratorBinding` class implements the iterator binding.

The iterator binding is a runtime object that your application creates to access the Oracle ADF binding context. The iterator binding holds references to the bound data collection, accesses it, and iterates over its data objects. The iterator binding notifies value bindings of row currency and row state. Then, value bindings that you define allow UI components to display or update the current data object of the collection being iterated over. In this way, the iterator binding provides uniform access to various collection types from different business services.

In the case of an Oracle ADF Business Components view object, the Oracle ADF bindings for the UI components may be able to display a row currency indicator. In a table, for example, the current row is identified at runtime by an asterisk (*) symbol displayed in the first column of that row. The currency indicator is available through the iterator binding only when the bound view object has a key attribute defined. When no key attribute is defined for the bound view object, each row of the table will display the asterisk. In this case, you can edit the UI component in the visual editor to prevent the asterisks from displaying at runtime.

The `oracle.jbo.uicli.binding.JUIteratorBinding` class abstracts out the most commonly used methods for collection and currency management:

- error returns any exception that was cached while validating the changes made to data through the iterator or through any Oracle ADF data control associated with the iterator.

- estimatedRowCount returns the maximum row count of the rows in the collection with which this iterator binding is associated.

- name returns the name of this iterator binding.

- rangeSize returns the range size of an Oracle ADF Business Components row set iterator. This property is limited to data controls registered with Oracle ADF Business Components.

- rowAtRangeIndex returns the data object at the specified index of the collection. In the case of data controls registered with Oracle ADF Business Components, it returns the row of the index in the current range.

### 4.7.2 About the Value Bindings

#### 4.7.2.1 Attribute Value Binding

The `oracle.jbo.uicli.binding.JUCtrlValueBinding` class implements the attribute value binding.

The attribute value binding permits the databound UI component to obtain the attribute value of the specified collection's data object. Depending on the type of UI component, users may view and, in some cases, edit the value of the attribute.

The `oracle.jbo.uicli.binding.JUCtrlAttrsBinding` class defines no properties of its own.

However, you can work with these properties defined by the class hierarchy of the attribute binding:

- attributeValue returns the value of the first attribute to which the binding is associated.

- attributeValues returns the value of all the attributes to which the binding is associated in an ordered array.

- attributeDef returns the attribute definition for the first attribute to which the binding is associated.

- attributeDefs returns the attribute definitions for all the attributes to which the binding is associated.

- displayHint returns the display hint for the first attribute to which the binding is associated. The hint identifies whether the attribute should be displayed or not.

- inputValue returns the value of the first attribute to which the binding is associated. If the binding was used to set the value on the attribute and the set operation failed, this method returns the invalid value that was being set.

- label returns a map of labels keyed by attribute name for all attributes to which the binding is associated.

- labels returns the label for the first attribute of the binding.

- labelSet returns an ordered set of labels for all the attributes to which the binding is associated.

- mandatory returns whether the first attribute to which the binding is associated is required.

- tooltip returns the tooltip hint for the first attribute to which the binding is associated.

- updateable returns whether the first attribute to which the binding is associated is updateable.

And you can work with the generic properties defined by the root class `DCControlBinding`.

#### 4.7.2.2 Boolean Value Binding

The `oracle.jbo.uicli.binding.JUCtrlBoolBinding` class implements the boolean binding.

The boolean binding obtains the attribute value of the specified collection's data object based on the control's selection state.

The `oracle.jbo.uicli.binding.JUCtrlBoolBinding` class has no properties of its own.

However, you can work with these properties defined by the class hierarchy of the boolean binding:

- attributeValue returns the value of the first attribute to which the binding is associated.

- attributeValues returns the value of all the attributes to which the binding is associated in an ordered array.

- attributeDef returns the attribute definition for the first attribute to which the binding is associated.

- attributeDefs returns the attribute definitions for all the attributes to which the binding is associated.

- displayData returns a list of map elements. Each map entry contains the following elements:

  - `selected` - A boolean `TRUE` if current entry should be selected.

  - `index` - The index value of the current entry.

  - `prompt` - A concatenated string of all display attribute values for the current entry.

  - `displayValues` - The iterator of display attribute values.

  - `selectedIndex` - The index of the selected entry to which the binding is associated.

- displayHint returns the display hint for the first attribute to which the binding is associated. The hint identifies whether the attribute should be displayed or not.

- displayHints returns a list of name-value pairs for UI hints for all display attributes to which the binding is associated. The map contains the following elements:

  - `label` - The label to display for the current attribute.

  - `tooltip` - The tooltip to display for the current attribute.

  - `displayHint` - The display hint for the current attribute.

  - `displayHeight` - The height in lines for the current attribute.

  - `displayWidth` - The width in characters for the current attribute.

  - `controlType` - The control type hint for the current attribute.

  - `format` - The format to be used for the current attribute.

- inputValue returns the value of the first attribute to which the binding is associated. If the binding was used to set the value on the attribute and the set operation failed, this method returns the invalid value that was being set.

- label returns a map of labels keyed by attribute name for all attributes to which the binding is associated.

- labels returns the label for the first attribute of the binding.

- labelSet returns an ordered set of labels for all the attributes to which the binding is associated.

- mandatory returns whether the first attribute to which the binding is associated is required.

- tooltip returns the tooltip hint for the first attribute to which the binding is associated.

- updateable returns whether the first attribute to which the binding is associated is updateable.

And you can work with the generic properties defined by the root class `DCControlBinding`.

#### 4.7.2.3 List Value Binding

The `oracle.jbo.uicli.binding.JUCtrlListBinding` class implements the list binding.

Depending on the type of UI component, the list binding may:

- Update an attribute of a data object in the bound collection

- Traverse the data objects of the bound collection

- Update a target data object in one collection using the value from another collection's data object

The `oracle.jbo.uicli.binding.JUCtrlListBinding` class provides accessor methods for these properties that you can work with:

- displayData returns a list of map elements. Each map entry contains the following elements:

  - `selected` - A boolean `TRUE` if current entry should be selected.

  - `Index` - The index value of the current entry.

  - `Prompt` - A concatenated string of all display attribute values for the current entry.

  - `displayValues` - The iterator of display attribute values.

  - `selectedIndex` - The index of the selected entry to which the binding is associated.

- displayHints returns a list of name-value pairs for UI hints for all display attributes to which the binding is associated. The map contains the following elements:

  - `label` - The label to display for the current attribute.

  - `tooltip` - The tooltip to display for the current attribute.

  - `displayHint` - The display hint for the current attribute.

  - `displayHeight` - The height in lines for the current attribute.

  - `displayWidth` - The width in characters for the current attribute.

  - `controlType` - The control type hint for the current attribute.

  - `format` - The format to be used for the current attribute.

Additionally, you can work with these properties defined by the class hierarchy of the list binding:

- attributeValue returns the value of the first attribute to which the binding is associated.

- attributeValues returns the value of all the attributes to which the binding is associated in an ordered array.

- attributeDef returns the attribute definition for the first attribute to which the binding is associated.

- attributeDefs returns the attribute definitions for all the attributes to which the binding is associated.

- displayHint returns the display hint for the first attribute to which the binding is associated. The hint identifies whether the attribute should be displayed or not.

- inputValue returns the value of the first attribute to which the binding is associated. If the binding was used to set the value on the attribute and the set operation failed, this method returns the invalid value that was being set.

- label returns a map of labels keyed by attribute name for all attributes to which the binding is associated.

- labels returns the label for the first attribute of the binding.

- labelSet returns an ordered set of labels for all the attributes to which the binding is associated.

- mandatory returns whether the first attribute to which the binding is associated is required.

- tooltip returns the tooltip hint for the first attribute to which the binding is associated.

- updateable returns whether the first attribute to which the binding is associated is updateable.

And you can work with the generic properties defined by the root class `DCControlBinding`.

#### 4.7.2.4 Range Value Binding

The `oracle.jbo.uicli.binding.JUCtrlRangeBinding` class implements the range binding.

The range binding permits the databound UI component to obtain a range of attribute values from the specified collection's data objects and to display the position of the current data object relative to that range.

The `oracle.jbo.uicli.binding.JUCtrlRangeBinding` class provides accessor methods for these properties that you can work with:

- estimatedRowCount returns the maximum row count of the rows in the collection with which this iterator binding is associated.

- rangeSet returns a list of map elements over the range of rows from the associated iterator binding. The elements in this list are wrapper objects over the indexed row in the range that restricts access to those attributes to which the binding is bound. The properties returned on the reference object are:

  - `index` - The range index of the row this reference is pointing to.

  - `key` - The key of the row this reference is pointing to.

  - `keyStr` - The String format of the key of the row this reference is pointing to.

  - `currencyString` - The current indexed row as a String. Returns "*" if the current entry belongs to the current row; otherwise, returns " ". This property is useful in JSP applications to display the current row.

  - `attributeValues` - The array of applicable attribute values from the row.

And you may also access an attribute value by name on a range set like `rangeSet.Dname` if `Dname` is a bound attribute in the range binding.

Additionally, you can work with these properties defined by the class hierarchy of the range binding:

- attributeValue returns the value of the first attribute to which the binding is associated.

- attributeValues returns the value of all the attributes to which the binding is associated in an ordered array.

- attributeDef returns the attribute definition for the first attribute to which the binding is associated.

- attributeDefs returns the attribute definitions for all the attributes to which the binding is associated.

- displayHint returns the display hint for the first attribute to which the binding is associated. The hint identifies whether the attribute should be displayed or not.

- inputValue returns the value of the first attribute to which the binding is associated. If the binding was used to set the value on the attribute and the set operation failed, this method returns the invalid value that was being set.

- label returns a map of labels keyed by attribute name for all attributes to which the binding is associated.

- labels returns the label for the first attribute of the binding.

- labelSet returns an ordered set of labels for all the attributes to which the binding is associated.

- mandatory returns whether the first attribute to which the binding is associated is required.

- tooltip returns the tooltip hint for the first attribute to which the binding is associated.

- updateable returns whether the first attribute to which the binding is associated is updateable.

And you can work with the generic properties defined by the root class `DCControlBinding`.

#### 4.7.2.5 Scroll Value Binding

The `oracle.jbo.uicli.binding.JUCtrlScrollBinding` class implements the scroll binding.

The scroll binding permits the databound UI component to display the current position of the data object in the selected collection. When the user scrolls the UI component, the scroll binding maintains the current position in the collection.

The `oracle.jbo.uicli.binding.JUCtrlScrollBinding` class defines no runtime properties of its own.

However, you can work with the generic propertOracle Application Development Framework Development Guidelines Manualies defined by the root class `DCControlBinding`.

### 4.7.3 About the Action Binding

The `oracle.jbo.uicli.binding.JUCtrlActionBinding` class implements the action binding.

The action binding is a type of binding object defined by Oracle ADF that performs actions on the bound data collection's row set iterator. At runtime, when the user initiates the action, using a button control, the action binding accesses the Oracle ADF binding context and initiates the specified action on the data objects of the selected collection. The action binding supports many predefined actions.

The `oracle.jbo.uicli.binding.JUCtrlActionBinding` class provides accessor methods for these properties of method-type action bindings that you can work with:

- params returns a list of parameter values that is passed to the method to which the action is bound.

- paramsMap returns a map of parameter values. The map is converted into an ordered list, where the keys on the map are names of the parameters, specified at design time as metadata.

- result returns the result of the method invocation. The method must return an object.

And you can work with the generic properties defined by the root class `DCControlBinding`.