Action Bindings and Method Bindings in Oracle ADF 11g

PageDef.xml is the page definition XML file. It associates web page UI components with data, or data controls. Oracle JDeveloper creates this file each time you design a new web page using the Data Controls Panel or Structure window. These XML files contain the meta data used to create the bindings that populate the data in the web page’s UI components. For every web page that refers to an ADF binding, there must be a corresponding page definition file with binding definitions.

In the overview editor for any page definition’s Bindings and Executables tab, click the Add icon in the Bindings section. From the Insert Item dialog, you're allowed to choose either action or methodAction binding object to create as shown below:
The description for the action item is "Binding for Action." So, it is named action binding. The description for the methodAction item is "Method binding for the Control." It is also known as method binding. In this article, we'll examine what're the differences and similarities of these two binding objects.

Acronyms

1. ADFm: ADF Model layer
2. ADFc: ADF Controller
3. ADFv: ADF View layer
4. EL: Expression Language

Action Binding

Action binding object can be used to bind command components, such as buttons or links, to built-in data control operations (such as Commit or Rollback) or to built-in collection-level operations (such as Create, Delete, Next, Previous, or ExecuteWithParams).

Action binding is defined in the page definition using the following attributes:

Attributes	Attribute Description
Action	Fully qualified package name. Identifies the class for which the data control is created. In the case of the EJB session facade, this is the session bean.
BindingClass	This is for backward compatibility to indicate which class implements the runtime for this binding definition. This is used by earlier versions of JDeveloper.
DataControl	Name of the DataControl usage in the bindingContext (.cpx) which this iteratorBinding or actionBinding is associated with.
Execute	Used by default when you drop an operation from the Data Controls Panel in the automatically configured ActionListener property. It results in executing the action binding's operation at runtime.
InstanceName	Specifies the instance name for the action.
IterBinding	Specifies the iteratorBinding instance in this bindingContainer to which this binding is associated.
Outcome	Use if you want to use the result of a method action binding (once converted to a String) as a JSF navigation outcome name.

For example, ExecuteWithParams (i.e., a built-in collection-level operation) is defined in a page definition file as:

<bindings>
<action IterBinding="TestTrendIterator" id="ExecuteWithParams"
RequiresUpdateModel="true" Action="executeWithParams">
<NamedData NDName="TSBegin" NDType="java.sql.Date"
NDValue="${bindings.ExecuteWithParams_TSBegin}"/>
<NamedData NDName="TSEnd" NDType="java.sql.Date"
NDValue="${bindings.ExecuteWithParams_TSEnd}"/>
</action>
</bindings>

Note that ExecuteWithParams on our view object (not shown here) takes two parameters:

1. TSBegin
2. TSEnd

These two parameters are defined to be optional (i.e., NDOption="optional") by default. This means that if you didn't provide new values programmatically at runtime, their values will be taken from meta data (i.e., ${bindings.ExecuteWithParams_TSXxx}) as provided in the action binding. See this article, for the descriptions of binding model parameter options (i.e., NDOption).

Method Binding

Method bindings are similar to action bindings. But, they are used to bind to methods defined in an ADF BC application, view object, or view row client interfaces.

Method binding is defined in the page definition using the following attributes:

Attributes	Attribute Description
Action	Fully qualified package name. Identifies the class for which the data control is created. In the case of the EJB session facade, this is the session bean.
BindingClass	This is for backward compatibility to indicate which class implements the runtime for this binding definition. This is used by earlier versions of JDeveloper.
ClassName	This is the class to which the method being invoked belongs.
DataControl	Name of the DataControl usage in the bindingContext (.cpx) which this methodAction is associated with.
DefClass	Used internally by ADF.
id	Unique identifier. May be referenced by any ADF action binding.
InstanceName	A dot-separated EL path to a Java object instance on which the associated method is to be invoked.
IsLocalObjectReference	Set to true if the instanceName contains an EL path relative to this bindingContainer.
IsViewObjectMethod	Set to true if the instanceName contains an instance path relative to the associated data control's application module.
MethodName	Indicates the name of the operation on the given instance or class that needs to be invoked for this methodActionBinding.
RequiresUpdateModel	Whether this action requires that the model be updated before the action is to be invoked.
ReturnName	The EL path of the result returned by the associated method.

For example, myCustomMethod defined in an ADF BC application is defined to be:

<bindings>
<methodAction id="myCustomMethod"
InstanceName="SelTestPortalAMDataControl.dataProvider"
DataControl="SelTestPortalAMDataControl"
RequiresUpdateModel="true" Action="invokeMethod"
MethodName="refreshTotalComments" IsViewObjectMethod="false"/>
</bindings>

How to Access Action/Method Bindings in an Fusion Web Application

When working with Fusion web applications using the ADF Model layer for data binding, JDeveloper configures a servlet filter in your user interface project called the ADFBindingFilter. It orchestrates the automatic acquisition and release of an appropriate application module instance based on declarative binding metadata, and ensures that the service is available to be looked up as a data control using a known action binding or iterator binding, specified by any page definition file in the user interface project.

No matter what a binding object is (i.e., action binding or method binding), they are retrieved and invoked in the same way when accessed from Fusion Web Applications:

• Retrieve them from the DCBindingContainer (i.e., the runtime object that embodies the meta data defined in the page definition) by naming an action binding or method binding.

Method bindings such as myCustomMethod, or action bindings such as Next, Previous or ExectureWithParams, exposed on a view object are instance of JUCtrlActionBinding that can be cast to the OperationBinding interface when accessed from Java:

BindingContext context = BindingContext.getCurrent();
DCBindingContainer bindingContainer = (DCBindingContainer) context.getCurrentBindingsEntry();
OperationBinding oper = bindingContainer.getOperationBinding("openSubTask");
...
oper.execute();

FacesCtrlAttrsBinding

Internally JUCtrlActionBinding is an FacesCtrlActionBinding, which is the class that connects ADFv^[1] command components to ADFc^[2]/ADFm^[3]. Like other ADFv binding classes, this is a sub-class of an ADFm class. And like other ADFm bindings there is an entry in the pageDef.xml file for this binding (i.e., action or method binding). If the method has either parameters or a return, there will be additional attribute bindings corresponding to the parameter and return values. These attribute bindings will correspond to a FacesCtrlAttrsBinding class and be in the pageDef.xml file.

The ADFv command components that use this class are:

• commandLink
• commandButton,
• commandMenuItem
• commandToobarButton
• commandImageLink.

and they are linked to this class via EL^[4] on the component, typically the actionListener attribute.

Learn More

1. Implement Contextual Events
2. Oracle ADF Model In Depth
3. Oracle ADF BindingContext and BindingContainer
4. Open Source sample applications for Oracle Fusion Middleware technology
5. How-To Access ADF application module with ADF faces (see Steve Muench's comments)

Oracle ADF Model In Depth

Oracle ADF Model implements the two concepts in JSR-227 that enable decoupling the user interface technology from the business service implementation:

• data controls
  • A data control abstracts the implementation of a business service, allowing the binding layer to access the data from all services in a consistent way.
  • At runtime, the ADF Model layer reads the information describing the data controls and bindings from appropriate XML files and implements the two-way connection between the user interface and the business service.
• declarative bindings
  • Declarative bindings abstract the details of accessing data from data collections in a data control and of invoking its operations.
  • There are 3 basic kinds of declarative binding objects:
    • Iterator bindings -- to allow scrolling and paging through collections of data and drilling-down from summary to detail information
    • Value bindings -- to display data
    • Action bindings -- to invoke built-in or custom operations on data collections of a data control. They are represented as operations in the Data Controls panel.

The following figure shows how bindings connect UI components to data control collections and methods.

In the following sections, we will see what kind of metadata are needed at design time to bind UI components (or widgets) to their associated data collections or methods declaratively and what kind of objects are generated at runtime to support the gluing.

Design Time

When you begin adding content to your page, you typically use the Component Palette and Data Controls panel of JDeveloper. The Component Palette contains all the ADF Faces components needed to declaratively design your page. Once you have the basic layout components placed on the page, you can then drag and drop items from the Data Controls panel to create ADF Model databound UI components.

From the item (i.e., accessor or attribute) dragged over from the Data Controls panel, JDeveloper first compiles a list of compatible BindingsTypes. From this list, JDeveloper can then determine the set of Creators that are applicable to drop on the page. The user is then presented with this list (organized by BindingsType). When the user selects a Creator to use, the Creator builds the databound UI component (by producing a DOM subtree representing what will be inserted into the page).
For example, If you drop the PrincipalName attribute from the Data Controls panel as an Input Text w/Label widget, JDeveloper creates an inputText component. The following code shows the code generated on the JSF page when you drop the PrincipalName attribute as an Input Text w/Label widget. Notice that the value of the component is bound to the inputValue property of the PrincipalName binding.

           shortDesc="#{bindings.PrincipalName.hints.tooltip}" id="it1">

You can change any of these properties to suit your needs. Reference this appendix for the properties of the ADF bindings.

If you build your application using these databound UI components, JDeveloper will create the following metadata files for you:

• Add a page definition file. The page definition file (pageNamePageDef.xml) defines the group of bindings supporting the UI components on a page.
• Create a DataBindings.cpx file and addes an entry for the page. The DataBindings.cpx file acts as the table of contents to the data controls in use in this application.
• Create the adfm.xml file. This file creates a registry for the DataBindings.cpx file, which allows the application to locate it at runtime so that the binding context can be created.

Runtime

At runtime, multiple objects (i.e., binding context, binding containers, and binding objects) are created in memory to hold binding information. The ADF binding context is a runtime map of all data controls and page definitions within the application. The binding context is the one object that lives in the HttpSession for each end user, accessible using the EL expression #{data}.

The group of bindings supporting the UI components on a page are described in a page definition file. The ADF Model layer uses this file at runtime to instantiate the page's bindings. These bindings are held in a request-scoped map called the binding container, accessible during each page request using the EL expression #{bindings}. This expression always evaluates to the binding container for the current page.

• Binding Context
  • The binding context provides the data environment for your application. It contains all of the data controls and binding containers that your application can access.
  • The ADF lifecycle creates the ADF binding context from the application module, DataBindings.cpx, and page definition files. Binding context contains references that become data control or binding container objects on demand.
  • You can look up ApplicationModule from a managed bean using the BindingContext:

    BindingContext bc = BindingContext.getCurrent();
    DCDataControl dc = bc.findDataControl("AppModuleDataControl");
    ApplicationModule am = (ApplicationModule)dc.getDataProvider();

  • You can retrieve a ControlBinding named "producerMethod" via BindingContext in this way:

    DCBindingContainer bc = (DCBindingContainer)BindingContext.getCurrent().getCurrentBindingsEntry();
    JUCtrlActionBinding actionBnd =
    (JUCtrlActionBinding)bc.getControlBinding("producerMethod");

• Binding Containers
  • A binding container holds value bindings and iterator bindings (or binding objects) for a page. It provides runtime access to all the ADF binding objects for a page.

At runtime, a web request for http://yourserver/yourapp/faces/some.jsp arrives from the client to the application server. The ADFBindingFilter (defined in web.xml) object looks for the ADF binding context in the HTTP session, and if it is not yet present, initializes it for the first time. If the appropriate binding container for the page has never been used before during the user's session, it is created. Also, if it is the first time an application module data control is referenced during the request, it acquires an instance of the application module from the application module pool. Then the control is forwarded to the page to be rendered. The UI components on the page access value bindings and iterator bindings in the page's binding container and render the formatted output to appear in the browser. Finally, the user sees the resulting page in the browser.

References

1. Using Oracle ADF Model in a Fusion Web Application
2. Understanding the Fusion Page Lifecycle
3. Oracle Fusion Middleware Online Documentation Library 11g Release (11.1.1.2)
4. Oracle ADF BindingContext and BindingContainer