| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
This chapter describes how to use the Data Control Palette to create databound UI components that display data on a page. It also describes how to work with all the objects that are created when you use the Data Control Palette.
This chapter includes the following sections:
The remaining chapters in this part of this guide describe how to create specific types of pages using databound components.
The ADF data controls, which are described in Section 3.10, "Exposing Services with ADF Data Controls", provide an abstraction of an application's business services, giving the ADF binding layer access to the service data. Data controls define the data model returned by the business service. You can bind UI components to data controls to populate a page with data from your data model at runtime.
The JDeveloper Data Control Palette exposes an application's data controls in the IDE and enables you to use drag and drop to create a variety of UI components on a JSF page. The UI components created by the Data Control Palette use declarative data binding, which means that the data binding expressions are automatically configured and that, in most cases, you do not have to write any additional code.
The advantages of binding to ADF data controls, instead of binding to the JavaServer Faces standard managed beans, include:
Declarative data binding using drag and drop from the Data Control Palette that requires little to no additional coding.
A uniform (standards-based) approach to UI data binding for multiple UI technologies
Read this chapter to understand:
How to use the Data Control Palette to create databound UI components
The items that appear on the Data Control Palette
The objects that JDeveloper creates for you when you use the Data Control Palette
How to construct an ADF data binding EL expression
The content of the page definition file and its relationship to EL expressions
You can design a databound user interface by dragging an item from the Data Control Palette and dropping it on a page as a specific UI component. When you use the Data Control Palette to create a UI component, JDeveloper automatically creates the various code and objects needed to bind the component to the data control you selected.
To display the Data Control Palette, open a JSF page in the Design page of the visual editor and choose View > Data Control Palette. By default, JDeveloper displays the Data Control Palette in the same window as the Component Palette.
Figure 5-1 shows the Data Control Palette for the SRDemo application, which uses TopLink as the business service and data controls created from EJB session facades.
Note:
If no data controls have been created for the application's business services, the Data Control Palette will be empty. For information about creating data controls, see Chapter 3, "Building and Using Application Services".The Data Control Palette shows all the data controls that have been created for the application's business services and exposes all the data objects, data collections, methods, and built-in operations that are available for binding to UI components. A data collection represents a set of data objects (also known as a rowset) in the data model. Each object in a data collection represents a specific structured data item (also known as a row) in the data model.
Each root node in the Data Control Palette represents a specific data control. Under each data control is a hierarchical list of objects, collections, methods, and operations. How this hierarchy appears on the Data Control Palette depends on the type of business service represented by the data control and how the business services were defined.
In the Data Control Palette, each data control object is represented by a specific icon. Table 5-1 describes what each icon represents, where it appears in the Data Control Palette hierarchy, and what components it can be used to create.
Table 5-1 The Data Control Palette Icons and Object Hierarchy
| Icon | Name | Description | Used to Create... |
|---|---|---|---|
|
|
Data Control |
Represents a data control. You cannot use the data control itself to create UI components, but you can use any of the child objects listed under it. Depending on how your business services were defined, there may be more than one data control, each representing a logical grouping of data functions. |
Not used to create anything. Serves as a container for the other objects. |
|
|
Represents a built-in method that creates a new instance of an object in a data collection. Create method icons are located in a folder named after the data collection to which they belong. These data collection folders are located in the Constructors folder under the data control. The Attributes folder, which appears as a child under a create method, contains all the attributes of the data collection in which the object will be created. If the objects in a collection contain an attribute from another collection (called a foreign key in relational databases), that attribute is represented by an accessor return icon. I this case, the accessor returns a single value and has no children. For more information about using constructors, see Section 10.7, "Creating an Input Form for a New Record". |
Creation forms |
|
|
|
Method |
Represents a custom method on the data control that may accept parameters, perform some action or business logic, and return single values or data collections. If the method is a |
Command components For methods that accept parameters: command components and parameterized forms |
|
|
Represents an object that is returned by a custom method. The returned object may be a single value or a collection. A method return appears as a child under the method that returns it. The objects that appear as children under a method return may be attributes of the collection, accessor returns that represent collections related to the parent collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection. |
For collections: forms, tables, trees, and range navigation components For single values: text fields and selection lists |
|
|
|
Represents an object returned by an accessor method on the business service. An accessor method is used when the objects returned are JavaBeans. Accessor returns appear as children under method returns, other accessor returns, or in the Attributes folder under built-in create methods. Accessor returns are objects that are related to the current object in the parent collection. This relationship is usually based on a common unique attribute in both objects. For example, if a method returns a collection of users, an accessor return that is a child of that collection might be a collection of service requests that are assigned to a particular user. In ADF, the relationship between parent and child collections is called a master-detail relationship. For more information about accessor returns and master-detail objects, see Chapter 8, "Displaying Master-Detail Data". The children under an accessor return may be attributes of the object, other accessor returns, custom methods that return a value from the accessor return, and operations that can be performed on the accessor return. |
For collections: forms, tables, trees, range navigation components, and master-detail widgets For single objects: forms, master-detail widgets, and selection lists For single objects under a constructor: selection lists only |
|
|
|
Represents a discrete data element in an object. Attributes appear as children under the method returns or accessor returns to which they belong. |
Label, text field, and selection list components. |
|
|
|
Represents a built-in data control operation that performs actions on the parent object. Data control operations are located in an Operations folder under method returns or accessor returns and under the root data control node. The operations that are children of a particular method or accessor return operate on that return object only, while operations under the data control node operate on all the objects represented by the data control. If an operation requires one or more parameters, they are listed in a Parameters folder under the operation. |
UI actions such as buttons or links. |
|
|
|
Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in the Parameters folder under a method or operation. |
Label, text, and selection list components. |
To create a databound UI component, drag an item from the Data Control Palette and drop it on a JSF page.
When you drag an item from the Data Control Palette and drop it on a page, JDeveloper displays a context menu of all the default UI components available for the item you dropped. From the context menu, select the component you want to create.
Note:
When you drag and drop a built-in create method from the Data Control Palette, the context menu does not appear. This is because create methods can be used to create only one type of component—creation forms.Figure 5-2 shows the context menu displayed when a method return from the Data Control Palette is dropped on a page.
Tip:
By default, the Data Control Palette context menu displays only ADF Faces components. However, you can use equivalent JSF components instead. To have JSF components appear in the Data Control Palette context menu, select the Include JSF HTML Widgets for JSF Databinding option in the ADF View Settings page of the project properties. However, using ADF Faces components, especially with ADF bindings, provide greater functionality than JSF components.Depending on the component you select from the context menu, JDeveloper may display a dialog that enables you to define how you want the component to look. For example, if you select ADF Read-only Table from the context menu, the Edit Table Columns dialog appears. This dialog enables you to define which attributes you want to display in the table columns, the column labels, what types of text fields you want use for each column, and what functionality you want to include, such as selection facets or column sorting. (For more information about creating tables, see Chapter 7, "Adding Tables".)
The resulting UI component appears in the JDeveloper visual editor. For example, if you drag a method return from the Data Control Palette, and choose ADF Read-only Table from the context menu, a read-only table appears in the visual editor, as shown in Figure 5-3.
Notice that the column labels in the sample table contain binding expressions, which bind each column label to an attribute in the data collection. The default table includes a selection facet, which is bound to a data collection iterator through an iterator binding. The selection facet was included by selecting the Enable Selection option in the Edit Table Columns dialog, which appears after you drop the table component. (Binding expressions are discussed later in Section 5.6, "Creating ADF Data Binding EL Expressions".)
By default, the UI components created when you use the Data Control Palette use ADF Faces components, are bound to collections and collection attributes in the ADF data control, and may have one or more built-in features including:
Databound labels
Tooltips
Formatting
Basic navigation buttons
Validation (if validation rules are attached to a particular attribute; see Chapter 12, "Using Validation and Conversion" for information about validation)
The default components are fully functional without any further modifications. However, you can modify them to suit your particular needs. Each component and its various features are discussed further in the remaining chapters in this part of this guide.
Tip:
If you want to change the type of ADF databound component used on a page, the easiest method is to delete the component and drag and drop a new one from the Data Control Palette. When you delete a databound component from a page, if the related binding objects in the page definition file are not referenced by any other component, JDeveloper automatically deletes those binding objects for you.While an ADF web application is built using the JSF framework, it requires a few additional application object definitions to render and process a page containing ADF databound UI components. If you do not use the Data Control Palette, you will have to manually configure these various files yourself. However, when you use the Data Control Palette, JDeveloper does all the required steps for you, which are:
Create a DataBindings.cpx file in the view package in the Application Sources directory (if one does not already exist), and add an entry for the page.
The DataBindings.cpx file defines the binding context for the application. It maps individual pages to their corresponding page definition files and registers the data controls used by those pages. The data controls are defined in the DataControls.dcx file. For more information, see Section 5.3, "Working with the DataBindings.cpx File".
Register the ADF binding filter in the web.xml file.
The ADF binding filter preprocesses any HTTP requests that may require access to the binding context. For more information about the binding filter configuration, see Section 5.4, "Configuring the ADF Binding Filter".
Register the ADF phase listener in the faces-config.xml file, as shown in Example 5-1.
Example 5-1 ADF Phase Listener Entry in the faces-config.xml File
<lifecycle> <phase-listener>oracle.adf.controller.faces.lifecycle.ADFPhaseListener </phase-listener> </lifecycle>
The ADF phase listener is used to execute the ADF page lifecycle. It listens for all the JSF phases before which and after which it needs to execute its own phases, which are concerned with preparing the model, validating model updates, and preparing pages to be rendered. For more information about the ADF lifecycle, see Section 6.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".
Add the following ADF runtime libraries to the project properties of the view project:
Add a page definition file (if one does not already exist for the page) to the page definition subpackage, the name of which is defined in the ADFm settings of the project properties. The default subpackage is view.pageDefs in the Application Sources directory.
The page definition file (<pageName>PageDef.xml) defines the ADF binding container for each page in an application's view layer. The binding container provides runtime access to all the ADF binding objects. In later chapters, you will see how the page definition files are used to define and edit the binding object definitions for specific UI components. For more information about the page definition file, see Section 5.5, "Working with Page Definition Files".
Configure the page definition file, which includes adding definitions of the binding objects referenced by the page.
Add prebuilt components to the JSF page.
These prebuilt components include ADF data binding expression language (EL) expressions that reference the binding objects in the page definition file. For more information, see Section 5.6, "Creating ADF Data Binding EL Expressions".
Add all the libraries, files, and configuration elements required by ADF Faces components, if ADF Faces components are used. For more information, see Section 4.4.2, "What Happens When You First Insert an ADF Faces Component".
When a page contains ADF bindings, 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 binding context. The ADF binding context is a container object that contains a list of data controls and data binding objects derived from the Oracle ADF Model layer.
The ADF lifecycle creates the Oracle ADF binding context from the DataControls.dcx, DataBindings.cpx, and page definition files, as shown in Figure 5-4. The DataControls.dcx file defines all the data controls available to the application. The DataBindings.cpx file references the data controls that are currently being used by pages in the application and maps the binding containers, which contain the binding objects defined in the page definition files, to web page URLs. The page definition files define the binding objects used the application pages. There is one page definition for each page. For information about the ADF lifecycle, see Section 6.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".
The DataBindings.cpx file maps individual pages to page definition files and declares which data controls defined in the DataControls.dcx file are being used by the application. (For information about the DataControls.dcx file, see Section 3.10.2, "Understanding the Data Control Files".) The DataBindings.cpx file defines the Oracle ADF binding context for the entire application and provides the metadata from which the Oracle ADF binding objects are created at runtime.
The first time you use the Data Control Palette to add a component to a page in an application, JDeveloper automatically creates the DataBindings.cpx file in the view package of the Application Sources directory of the view project. Once the DataBindings.cpx file is created, JDeveloper adds an entry for the first page. Each subsequent time you use the Data Control Palette to add a component to a page, JDeveloper adds an entry to the DataBindings.cpx for that page, if one does not already exist.
Example 5-2 shows the DataBindings.cpx file for the SRDemo application. The pageMap element maps each JSF page to its corresponding page definition file. The pageDefintionUsages element identifies each page definition file in the application. The dataControlUsages element identifies the data controls being used by the binding objects defined in the page definition files. For more information about the elements and attributes in the DataBindings.cpx file, see Appendix A, "Reference ADF XML Files".
Example 5-2 DataBindings.cpx File
<?xml version="1.0" encoding="UTF-8" ?>
<Application xmlns="http://xmlns.oracle.com/adfm/application"
version="10.1.3.35.65" id="DataBindings" SeparateXMLFiles="false"
Package="oracle.srdemo.view" ClientType="Generic">
<pageMap>
<page path="/app/SRList.jspx" usageId="SRListPageDef"/>
<page path="/app/SRCreate.jspx" usageId="SRCreatePageDef"/>
<page path="/app/SRCreateConfirm.jspx" usageId="SRCreateConfirmPageDef"/>
...
</pageMap>
<pageDefinitionUsages>
<page id="SRListPageDef"
path="oracle.srdemo.view.pageDefs.app_SRListPageDef"/>
<page id="UserInfoPageDef"
path="oracle.srdemo.view.pageDefs.headless_UserInfoPageDef"/>
<page id="SRCreatePageDef"
path="oracle.srdemo.view.pageDefs.app_SRCreatePageDef"/>
<page id="SRCreateConfirmPageDef"
path="oracle.srdemo.view.pageDefs.app_SRCreateConfirmPageDef"/>
...
</pageDefinitionUsages>
<dataControlUsages>
<dc id="EmailService" path="oracle.srdemo.emailService.EmailService"/>
<dc id="SRDemoFAQ" path="oracle.srdemo.faq.SRDemoFAQ"/>
<dc id="SRAdminFacade" path="oracle.srdemo.model.SRAdminFacade"/>
<dc id="SRPublicFacade"
path="oracle.srdemo.model.SRPublicFacade"/>
</dataControlUsages>
</Application>
The ADF binding filter is a servlet filter that is an instance of the oracle.adf.model.servlet.ADFBindingFilter class. ADF web applications use the ADF binding filter to preprocess any HTTP requests that may require access to the binding context.
The first time you add a databound component to a page using the Data Control Palette, JDeveloper automatically configures the filter for you in the application's web.xml file.
To configure the binding filter, JDeveloper adds the following elements to the web.xml file:
A Servlet context parameter: Specifies which DataBindings.cpx file the binding filter reads at runtime to define the application binding context.
The servlet context parameter is defined in the web.xml file, as shown in Example 5-3. The param-name element must contain the value CpxFileName, and the param-value element must contain the fully qualified name of the application's DataBindings.cpx file without the .cpx extension.
An ADF binding filter class: Specifies the name of the binding filter object, which implements the javax.servlet.Filter interface.
The ADF binding filter is defined in the web.xml file, as shown in Example 5-4. The filter-name element must contain the value adfBindings, and the filter-class element must contain the fully qualified name of the binding filter class, which is oracle.adf.model.servlet.ADFBindingFilter.
Filter mappings: Link filters to static resources or servlets in the web application.
At runtime, when a mapped resource is requested, a filter is invoked. Filter mappings are defined in the web.xml file, as shown in Example 5-5. The filter-name element must contain the value adfBindings. Notice that in the example there is a filter mapping for both types of page formats: jsp and jspx.
Example 5-5 Filter Mapping Defined in the web.xml File
<filter-mapping>
<filter-name>adfBindings</filter-name>
<url-pattern>*.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>adfBindings</filter-name>
<url-pattern>*.jspx</url-pattern>
</filter-mapping>
Tip:
If you have multiple filters defined in theweb.xml file, be sure to list them in the order in which you want them to run. At runtime, the filters are executed in the sequence they appear in the web.xml file.At runtime, the ADF binding filter performs the following functions:
Overrides the character encoding when the filter is initialized with the name specified as a filter parameter in the web.xml file. The parameter name of the filter init-param element is encoding.
Instantiates the ADFContext object, which is the execution context for an ADF application and contains context information about ADF, including the security context and the environment class that contains the request and response object.
Serializes incoming HTTP requests from the same browser (for example, from framesets) to prevent multithreading problems.
Notifies data control instances that they are about to receive a request, allowing them to do any necessary per-request setup.
Notifies data control instances after the response has been sent to the client, allowing them to do any necessary per-request cleanup.
Page definition files define the binding objects that populate the data in UI components at runtime. For every page that has ADF bindings, there must be a corresponding page definition file that defines the binding object used by that page. Page definition files provide design time access to all the ADF bindings. At runtime, the binding objects defined by a page definition file are instantiated in a binding container, which is the runtime instance of the page definition file.
The first time you use the Data Control Palette, JDeveloper automatically creates a page definition file for that page and adds definitions for each binding object referenced by the component. For each subsequent databound component you add to the page, JDeveloper automatically adds the necessary binding object definitions to the page definition file.
By default, the page definition files are located in the view.PageDefs package in the Application Sources directory of the view project. You can change the location of the page definition files using the ADFm Settings page of the project properties.
JDeveloper names the page definition files using the following convention:
<pageName>PageDef.xml
where <pageName> is the name of the JSF page. For example, if the JSF page is named SRList.jsp, the default page definition filename is SRListPageDef.xml. If you organize your pages into subdirectories, JDeveloper prefixes the directory name to the page definition filename using the following convention:
<directoryName>_<pageName>PageDef.xml
For example, in the SRDemo application, the name of the page definition file for the SRMain page, which is in the app subdirectory of the Web Content folder is app_SRMainPageDef.xml.
Caution:
TheDataBindings.cpx file maps JSF pages to their corresponding page definition files. If you change the name of a page definition file or a JSF page, JDeveloper does not automatically refactor the DataBindings.cpx file. You must manually update the page mapping in the DataBindings.cpx file.To open a page definition file, right-click on the page in the visual editor or in the Application Navigator, and choose Go to Page Definition.
Example 5-6 shows a sample page definition file that was created for the SRList page in the SRDemo application. Notice that the page definition file groups the binding object definitions under the following wrapper elements:
parameters (for more information, see Section 5.5.2.1, "Binding Objects Defined in the parameters Element")
executables (for more information, see Section 5.5.2.2, "Binding Objects Defined in the executables Element")
bindings (for more information, see Section 5.5.2.3, "Binding Objects Defined in the bindings Element")
Each wrapper element contains specific types of binding object definitions. The id attribute of each binding object definition specifies the name of the binding object. Each binding object name must be unique within the page definition file. By default, the binding objects are named after the data control object that was used to create it. If a data control object is used more than once on a page, JDeveloper adds a number to the default binding object names to keep them unique. In Section 5.6, "Creating ADF Data Binding EL Expressions", you will see how the ADF data binding EL expressions reference the binding object names.
Example 5-6 Page Definition File
<?xml version="1.0" encoding="UTF-8" ?>
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
version="10.1.3.35.65" id="SRListPageDef"
Package="oracle.srdemo.view.pageDefs">
<parameters/>
<executables>
<methodIterator id="findServiceRequestsIter"
Binds="findServiceRequests.result"
DataControl="SRPublicFacade" RangeSize="10"
BeanClass="oracle.srdemo.model.entities.ServiceRequest"/>
<invokeAction Binds="findServiceRequests" id="tableRefresh"
Refresh="ifNeeded"
RefreshCondition="${(userState.refresh) and
(!adfFacesContext.postback)}"/>
<variableIterator id="variables">
<variable Type="java.lang.String" Name="setCurrentRowWithKey_rowKey"
IsQueriable="false"/>
</variableIterator>
</executables>
<bindings>
<methodAction id="findServiceRequests"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade"
MethodName="findServiceRequests" RequiresUpdateModel="true"
Action="999"
ReturnName="SRPublicFacade.methodResults.
SRPublicFacade_dataProvider_findServiceRequests_result">
<NamedData NDName="userIdParam" NDValue="#{userInfo.userId}"
NDType="java.lang.Integer"/>
<NamedData NDName="statusParam" NDValue="#{userState.listMode}"
NDType="java.lang.String"/>
</methodAction>
<table id="findServiceRequests1" IterBinding="findServiceRequestsIter">
<AttrNames>
<Item Value="assignedDate"/>
<Item Value="problemDescription"/>
<Item Value="requestDate"/>
<Item Value="status"/>
<Item Value="svrId"/>
</AttrNames>
</table>
<action id="setCurrentRowWithKey" IterBinding="findServiceRequestsIter"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" RequiresUpdateModel="false"
Action="96">
<NamedData NDName="rowKey" NDValue="${row.rowKeyStr}"
NDType="java.lang.String"/>
</action>
</bindings>
</pageDefinition>
In later chapters, you will see how the page definition file is used to define and edit the bindings for specific UI components. For a description of all the possible elements and attributes in the page definition file, see Appendix A, "<pageName>PageDef.xml".
The parameters element of the page definition file defines the parameters for the page. Parameter binding objects are argument values used by:
A method action binding when invoking a bound method. For information about method action bindings, see Section 5.5.2.3, "Binding Objects Defined in the bindings Element".
An iterator binding to fetch its data set. For information about iterator bindings, see Section 5.5.2.2, "Binding Objects Defined in the executables Element".
The parameter binding objects declare the parameters that the page evaluates at the beginning of a request (in the Prepare Model phase of the ADF lifecycle). In a web application, the page parameters are evaluated once during the Prepare Model phase. (For more information about the ADF lifecycle, see Section 6.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".) You can define the value of a parameter in the page definition file using static values, binding expressions, or EL expressions that assign a static value.
The SRDemo application does not use parameter bindings. However, Example 5-7 shows how parameter binding objects can be defined in a page definition file.
Example 5-7 The parameters Element of a Page Definition File
<parameters>
<parameter id="filedBy"
value="${bindings.userId}"/>
<parameter id="status"
value="${param.status != null ? param.status : 'Open'}"/>
</parameters>
The value of the filedBy parameter is defined by a binding on the userID data attribute, which would be an attribute binding defined later in the bindings wrapper element. The value of the status parameter is defined by an EL expression, which assigns a static value.
Tip:
By default, JDeveloper uses the dollar sign ($), which is a JSP EL syntax standard, as the prefix for EL expressions that appear in the page definition file. However, you can use the hash sign (#) prefix, which is a JSF EL syntax standard, as well.For more information about passing parameters to methods, see Chapter 10, "Creating More Complex Pages".
The executables element of the page definition file defines the following types of executable binding objects:
methodIterator: Binds to an iterator that iterates over the collections returned by custom methods in the data control.
A method iterator binding is always related to a methodAction binding defined in the bindings element. The methodAction binding encapsulates the details about how to invoke the method and what parameters (if any) the method is expecting. For more information about methodAction bindings, see Section 5.5.2.3, "Binding Objects Defined in the bindings Element".
accessorIterator: Binds to an iterator that iterates over the detail objects returned by accessors on the data control. When you drop an accessor return or an attribute of an accessor return on a page, an accessorIterator is added to the executables element.
Accessor iterators are always related to a method iterator that iterates over the master objects. The MasterBinding attribute of the accessor iterator binding defines the method iterator to which the accessor iterator is related. For more information about master-detail objects and iterators, see Chapter 8, "Displaying Master-Detail Data".
variableIterator: Binds to an iterator that exposes all the variables in the binding container to the other bindings.
Page variables are local to the binding container and exist only while the binding container object exists. When you use a data control method or operation that requires a parameter that is to be collected from the page, JDeveloper automatically defines a variable for the parameter in the page definition file. Attribute bindings can reference the page variables.
invokeAction: Binds to a method that invokes the operations or methods defined in action or methodAction bindings during any phase of the page lifecycle.
Action and method action bindings are defined in the bindings element. For more information about methodAction objects, see Section 5.5.2.3, "Binding Objects Defined in the bindings Element".
Iterator binding objects bind to an underlying ADF RowSetIterator object, which manages the current object and current range information. The iterator binding exposes the current object and range state to the other binding objects used by the page. The iterator range represents the current set of objects to be displayed on the page. The maximum number of objects in the current range is defined in the rangeSize attribute of the iterator. For example, if a collection in the data control contains service requests and the iterator range size is 10, the first ten service requests in the collection are displayed on the page. If the user scrolls down, the next set of 10 service requests are displayed, and so on. If the user scrolls up, the previous set of 10 are displayed.
There is one iterator binding for each collection used on the page, but there is only one variablesIterator binding for all variables used on the page. (The variables iterator is like an iterator pointing to a collection that contains only one object whose attributes are the binding container variables.) All of the value bindings on the page must refer to an iterator binding to have the component values populated with data at runtime. (For information about value bindings, see Section 5.5.2.3, "Binding Objects Defined in the bindings Element".)
At runtime, the bindings in the executables element are refreshed in the order in which they appear in the page definition file. Refreshing an iterator binding reconnects it with its underlying RowSetIterator object. Refreshing an invokeAction binding invokes the action. However, before refreshing any bindings, the ADF runtime evaluates any Refresh and RefreshCondition attributes specified in the iterator and invokeAction elements. The Refresh attribute specifies the ADF lifecycle phase within which the executable should be invoked. The RefreshCondition attribute specifies the conditions under which the executable should be invoked. You can specify the RefreshCondition value using a boolean EL expression. If you leave the RefreshCondition attribute blank, it evaluates to true.
Tip:
Use the Structure window to re-order bindings in theexecutables element using drag and drop.Example 5-8 shows an example of an executables element, which defines two types of iterators, method and variable, and an invokeAction object.
Example 5-8 The executables Element in a Page Definition File
<executables>
<methodIterator id="findServiceRequestsIter"
Binds="findServiceRequests.result"
DataControl="SRPublicFacade" RangeSize="10"
BeanClass="oracle.srdemo.model.entities.ServiceRequest"/>
<invokeAction Binds="findServiceRequests" id="tableRefresh"
Refresh="ifNeeded"
RefreshCondition="${(userState.refresh) and
(!adfFacesContext.postback)}"/>
<variableIterator id="variables">
<variable Type="java.lang.String" Name="setCurrentRowWithKey_rowKey"
IsQueriable="false"/>
</variableIterator>
</executables>
<bindings>
<methodAction id="findServiceRequests"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade"
MethodName="findServiceRequests" RequiresUpdateModel="true"
Action="999"
ReturnName="SRPublicFacade.methodResults.
SRPublicFacade_dataProvider_findServiceRequests_result">
<NamedData NDName="userIdParam" NDValue="#{userInfo.userId}"
NDType="java.lang.Integer"/>
<NamedData NDName="statusParam" NDValue="#{userState.listMode}"
NDType="java.lang.String"/>
</methodAction>
<table id="findServiceRequests1" IterBinding="findServiceRequestsIter">
...
</bindings>
The findServiceRequestIter method iterator binding was created by dragging the findServiceRequest method return from the Data Control Palette onto the page. It iterates over the collection returned by the findServiceRequest method, which is defined in the Binds attribute. The RangeSize attribute defines the number of objects to fetch at one time. A RangeSize value of -1 causes the iterator binding to display all the objects from the collection. In the bindings wrapper element, notice that the IterBinding attribute of the table binding object references the findServiceRequestsIter iterator binding, which populates the table with data.
In the example, the method iterator binding is related to the findServiceRequests method action binding, which is defined in the bindings element. The NamedData elements define the parameters to be passed to the method. The table binding in the bindings element references the findServiceRequestIter iterator binding in the IterBinding attribute to populate the data in the table.
The invokeAction object invokes the findServiceRequests method defined in the method action. The Refresh attribute determines when in the ADF lifecycle the method is executed, while the RefreshCondition attribute provides a condition for invoking the action. (For more information about the Refresh and RefreshCondition attributes, see Section A.7, "<pageName>PageDef.xml". For examples of using the Refresh and RefreshCondition attributes, see Section 10.8, "Creating Search Pages".)
The variable iterator iterates over the variable called setCurrentRowWithKey_rowKey, which is a parameter required by the setCurrentRowWithKey operation.
The bindings element of the page definition file defines the following types of binding objects:
Value: Display data in UI components by referencing an iterator binding. Each discrete UI component on a page that will display data from the data control is bound to a value binding object. Value binding objects include:
methodAction: Bind command components, such as buttons or links, to custom methods on the data control. A methodAction binding object encapsulates the details about how to invoke a method and what parameters (if any) the method is expecting.
Method iterator bindings are bound to methodAction binding objects. There is one method action binding for each method iterator binding used in the page.
action: 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 Save).
Collectively, the binding objects defined in the bindings element are referred to as control bindings, because each databound control on a page is bound to one of these objects, which in turn is bound to an object defined in the executables element.
Example 5-9 shows a sample bindings element, which defines one methodAction binding called findServiceRequest, one value binding for a table called findServiceRequest1 and one action binding called setCurrentRowWithKey.
Example 5-9 The bindings Element of a Page Definition File
<bindings>
<methodAction id="findServiceRequests"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade"
MethodName="findServiceRequests" RequiresUpdateModel="true"
Action="999"
ReturnName="SRPublicFacade.methodResults.
SRPublicFacade_dataProvider_findServiceRequests_
result">
<NamedData NDName="userIdParam" NDValue="#{userInfo.userId}"
NDType="java.lang.Integer"/>
<NamedData NDName="statusParam" NDValue="#{userState.listMode}"
NDType="java.lang.String"/>
</methodAction>
<table id="findServiceRequests1" IterBinding="findServiceRequestsIter">
<AttrNames>
<Item Value="assignedDate"/>
<Item Value="problemDescription"/>
<Item Value="requestDate"/>
<Item Value="status"/>
<Item Value="svrId"/>
</AttrNames>
</table>
<action id="setCurrentRowWithKey" IterBinding="findServiceRequestsIter"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" RequiresUpdateModel="false"
Action="96">
<NamedData NDName="rowKey" NDValue="${row.rowKeyStr}"
NDType="java.lang.String"/>
</action>
</bindings>
Because the findServiceRequests method used in the sample accepts parameters, the method action binding contains NamedData elements that define the parameters expected by this method. For more information about passing parameters to methods, see Chapter 10, "Creating More Complex Pages".
In the table binding object, the IterBinding attribute references the appropriate iterator binding that displays the data in the component. Notice that a table is handled by a single binding object that references the iterator binding once for all the attributes displayed in the table. This means that the table can only display data from a single data collection. However, for container components like forms, each individual attribute has a binding object, which references an iterator binding. Forms, unlike tables, can contain attributes from multiple data collections. The AttrNames element defines all the attribute values in the collection.
The action binding is bound to a command link that returns a specific service request when the user clicks the link. It references the findServiceRequestsIter iterator binding and passes it the current row key as a parameter, which is defined in the namedData element.
At runtime, the ADF page lifecycle passes the page URL to the ADF binding context, which matches the URL to a page definition file using the information in the DataBindings.cpx file. Next, the binding context instantiates the binding container if it does not already exist in the current session. The binding container is the runtime instance object that contains all of the binding objects defined in the page definition file. All the data that is displayed by a page's UI components is provided by the binding objects in the binding container. The ADF data binding expressions used by components on a page are evaluated at runtime and are replaced by values supplied by the binding objects when the page is rendered.
By default, the binding container and the binding objects it contains are defined in session scope. However, the values referenced by value bindings and iterator bindings are undefined between requests and for scalability reasons do not remain in session scope. Therefore, the values that binding objects refer to are only valid during a request in which that binding container has been prepared by the ADF lifecycle. What stays in session scope are only the binding container and binding objects themselves.
Upon each request, the iterator bindings are refreshed to rebind them to the underlying RowSetIterator objects. By default, the rowset iterator state and the data caches are maintained between requests.
In the previous section, you saw how the page definition is used to define the binding objects that are created in the binding container at runtime. To display data from the data model, web page UI components, are bound to binding objects using JSF Expression Language (EL) expressions. These EL expressions reference a specific binding object in a binding container. At runtime, the JSF runtime evaluates EL expression and pulls the value from the binding object to populate the component with data when the page is displayed. If the user updates data in the UI component, the JSF runtime pushes the value back into the corresponding binding object based on the same EL expression.
When you use the Data Control Palette to create a component, the ADF data binding expressions are created for you. The expressions are added to every component attribute that will either display data from or reference properties of a binding object. Each prebuilt expression references the appropriate binding objects defined in the page definition file.
You can edit these binding expressions or create your own, as long as you adhere to the basic ADF binding expression syntax. ADF data binding expressions can be added to any component attribute that you want to populate with data from a binding object.
In JSF pages, a typical ADF data binding EL expression uses the following syntax to reference any of the different types of binding objects in the binding container:
#{bindingVariable.BindingObject.propertyName}
where:
bindingVariable is a variable that identifies where to find the binding object being referenced by the expression. The bindings variable is the most common variable used in ADF binding expressions. It references the binding container of the current page. By default, all components created from the Data Control Palette use the bindings variable in the binding expressions.
BindingObject is the name of the binding object as it is defined in the page definition file. The binding object name appears in the id attribute of the binding object definition in the page definition and is unique to that page definition. An EL expression can reference any binding object in the page definition file, including parameters, executables, or value bindings. When you use the Data Control Palette to create a component, JDeveloper assigns the names to the binding objects based on the names of the items in the data control.
propertyName is a variable that determines the default display characteristics of each databound UI component and sets properties for the binding object at runtime. There are different binding properties for each type of binding object. For more information about binding properties, see Section 5.6.4, "What You May Need to Know About ADF Binding Properties".
For example, in the following expression:
#{bindings.SvrId.inputValue}
the bindings variable references a bound value in the current page's binding container. The binding object being referenced is SvrId, which is an attribute binding object. The binding property is inputValue, which returns the value of the first SvrId attribute.
Tip:
While the binding expressions in the page definition file can use either a dollar sign ($) or hash sign (#) prefix, the EL expressions in JSF pages can use only the hash sign (#) prefix.For more examples of various types of ADF data binding expressions, see Section 5.6.3, "What Happens When You Create ADF Data Binding Expressions".
To create or edit an ADF Data Binding EL Expression
You can create or edit an expression in JDeveloper using any of the following techniques:
Double-click the UI component in the Structure window, and edit the value field in the displayed editor. (Click the Bind button to go to the Expression Builder, where you can select from available binding objects and properties. For more information, see Section 5.6.2, "How to Use the Expression Builder".)
View the web page using the source view of the visual editor and edit the expression directly in the source. JDeveloper provides Code Insight for EL expressions in the source editor. Code Insight is also available in the Property Inspector and the Tag Editor. To invoke Code Insight, type the leading characters of an EL expression (for example, #{). Code Insight displays a list of valid items for each segment of the expression from which you can select the one you want.
Select a UI component in the visual editor or the Structure window and open the Property Inspector (View > Property Inspector). You can edit the expression directly in the Property Inspector, or click the ellipses next the expression to open the Expression Builder.
The JDeveloper Expression Builder is a dialog that helps you build EL expressions by providing lists of binding objects defined in the page definition files, as well as lists of managed beans and binding properties. It is particularly useful when creating or editing ADF databound expressions because it provides a hierarchical list of ADF binding objects and their most commonly used properties from which you can select the ones you want to use in an expression. For information about binding properties, see Section 5.6.4, "What You May Need to Know About ADF Binding Properties".
You can open the Expression Builder from either the Structure window or the Property Inspector.
To open the Expression Builder from the Structure window:
Double-click an ADF databound UI component in the Structure window.
In the ensuing dialog, click the Bind button next to a component property to display the Expression Builder.
To open the Expression Builder from the Property Inspector:
Select a UI component in the Structure window or the visual editor and open the Property Inspector.
In the Property Inspector, take one of the following actions to display the Expression Builder:
Click the ellipses next to an existing binding expression.
OR
Select a property to which you want to add a binding, and click the Bind to data button, as shown in Figure 5-5.
(JDeveloper activates the Bind to data button only if it is valid to add a binding expression to the selected property.)
To use the Expression Builder:
In the Expression Builder, open the ADF Bindings > bindings node to display the ADF binding objects for the current page, as shown in Figure 5-6.
For information about using the ADF Bindings > data node, see Section 5.6.5, "What You May Need to Know About Binding to Values in Other Pages".
Use the Expression Builder to edit or create ADF binding expressions using the following features:
Use the Variables tree to select items that you want to include in the binding expression. The tree contains a hierarchical representation of the binding objects. Each icon in the tree represents various types of binding objects that you can use in an expression (see Table 5-2 for a description of each icon). Select an item in the tree and click the shuttle button to move it to the Expression box.
If you are creating a new expression, begin typing the expression in the Expression box. JDeveloper provides Code Insight in the Expression Builder. To invoke Code Insight, type the leading characters of an EL expression (for example, #{) or a period separator. Code Insight displays a list of valid items for each segment of the expression from which you can select the one you want.
Use the operator buttons under the expression to add logical or mathematical operators to the expression.
Table 5-2 Icons Under the ADF Bindings Node of the Expression Builder
| Icon | Description |
|---|---|
|
|
Represents the |
|
|
Represents the Before using the objects under this node, see Section 5.6.5, "What You May Need to Know About Binding to Values in Other Pages" for more information and cautions. |
|
|
Represents a binding container. Each binding container node is named after the page definition file that defines it. These nodes appear only under the data node. Opening a binding container node exposes the binding objects defined for that page. Before using the object under this node, see Section 5.6.5, "What You May Need to Know About Binding to Values in Other Pages" for more information and cautions. |
|
|
Represents an action binding object. Opening a node that uses this icon exposes a list of valid action binding properties. |
|
|
Represents an iterator binding object. Opening a node that uses this icon exposes a list of valid iterator binding properties. |
|
|
Represents an attribute binding object. Opening a node that uses this icon exposes a list of valid attribute binding properties. |
|
|
Represents a list binding object. Opening a node that uses this icon exposes a list of valid list binding properties are displayed. |
|
|
Represents a table binding object. Opening a node that uses this icon exposes a list of valid table binding properties. |
|
|
Represents a tree binding object. Opening a node that uses this icon exposes a list of valid tree binding properties. |
|
|
Represents an ADF binding object property. For more information about ADF properties, see Section 5.6.4, "What You May Need to Know About ADF Binding Properties". |
|
|
Represents a parameter binding object. |
As was previously mentioned, when you create a component using the Data Control Palette, the ADF data binding expressions are added for you. Each expression is slightly different depending on the type of binding object being referenced.
Example 5-10 shows a text field that was created when a data collection was dropped on a page as an ADF Read-only Form. Each UI component in the form, including the text field shown in the example, contains an EL expression that references an attribute binding object on a specific attribute in the data collection.
Example 5-10 EL Expressions That Reference an Attribute Binding Object
<af:inputText value="#{bindings.SvrId.inputValue}"
label="#{bindings.SvrId.label}"/>
In this example, the UI component is bound to the SvrId binding object, which is a specific attribute in a data collection. The inputValue binding property returns the value of the first attribute to which the binding is associated, which in this case is SvrId. In the label attribute, the EL expression references the label binding property, which returns the label currently assigned to the data attribute.
The value binding object, SvrId, referenced by the EL expressions is defined in the page definition file, as shown in Example 5-11. The name of the binding object, which is referenced by the EL expression, is defined in the id attribute of the binding object definition.
Example 5-11 Attribute Binding Object Defined In the Page Definition File
<attributeValues id="SvrId" IterBinding="FindAllServiceRequestsIter"
isDynamic="true">
<AttrNames>
<Item Value="SvrId"/>
</AttrNames>
</attributeValues>
Tip:
For a value binding that was created by dragging an attribute from an accessor return from the Data Control Palette, JDeveloper prefixes the accessor method name to the attribute name. For example, in the expression#{bindings.ServiceRequestsvrId.label}, the binding object name is a combination of the accessor method name, ServiceRequest, and the attribute name, svrId.When you drag a data collection from the Data Control Palette and drop it on a JSF page as an ADF Read-only Table, the resulting table tag typically contains a set of EL expressions that bind the table to a table value-binding object, as shown in Example 5-12.
Example 5-12 EL Expression That References a Table Binding Object
<af:table value="#{bindings.findAllStaff1.collectionModel}" var="row"
rows="#{bindings.findAllStaff1.rangeSize}"
first="#{bindings.findAllStaff1.rangeStart}"
emptyText="#{bindings.findAllStaff1.viewable ?
\'No rows yet.\' : \'Access Denied.\'}"
Each attribute of the table tag contains a binding expression that references the table binding object and an appropriate binding property for that tag attribute. The binding expression in the rows attribute references the iterator binding rangeSize property (which defines the number of rows in each page of the iterator) so that the number of rows rendered in the table matches the number of rows per page defined by the iterator binding.
The table is bound to the findAllStaff1 table binding object, which is defined in the page definition file as shown in Example 5-13.
Example 5-13 Table Binding Object Defined in the Page Definition File
<table id="findAllStaff1" IterBinding="findAllStaffIter">
<AttrNames>
<Item Value="city"/>
<Item Value="countryId"/>
<Item Value="email"/>
<Item Value="firstName"/>
<Item Value="lastName"/>
<Item Value="postalCode"/>
<Item Value="stateProvince"/>
<Item Value="streetAddress"/>
<Item Value="userId"/>
<Item Value="userRole"/>
</AttrNames>
</table>
The IterBinding attribute in the table binding object refers to the iterator binding that will display data in the table.
Example 5-14 shows a command button that was created by dragging a built-in operation from the Data Control Palette and dropping it on the page. The button contains an EL expression that binds to a built-in operation, First, which displays the first data object in the data collection to which the operation belongs.
Example 5-14 EL Expression That References an Action Binding Object for an Operation
<af:commandButton actionListener="#{bindings.First.execute}"
text="First"
disabled="#{!bindings.First.enabled}"/>
The button's action listener is bound to the execute() method on the action binding named First in the binding container. When the user clicks the button, the action listener mechanism resolves the binding expression and then invokes the execute() method, which executes the operation. By default, the button label contains the name of the operation being called. You can change the label as needed. The disabled attribute determines if the button should be disabled on the page. Because of the not operator (!) at the beginning of the expression, the disabled attribute evaluates to the negation of the value of the enabled property of the action binding.
In other words, if the enabled property evaluates to false, the disabled attribute evaluates to true. For example, in an action binding that is bound to the First operation, if the current data object is the first one, the enabled property evaluates to false, which causes the disabled attribute to evaluate to true, thus disabling the button. However, if the current data object is not the first one, the enabled property evaluates to true, which causes the disabled attribute to evaluate to false, thus enabling the button.
Example 5-15 shows the action binding object defined in the page definition for the command button.
Example 5-15 Action Binding Object Defined in the Page Definition File for an Operation
<executables>
<methodIterator id="findAllStaffIter" Binds="findAllStaff.result"
DataControl="SRPublicFacade" RangeSize="10"
BeanClass="oracle.srdemo.model.entities.User"/>
</executables>
<bindings>
<methodAction id="findAllStaff" InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" MethodName="findAllStaff"
RequiresUpdateModel="true" Action="999"
ReturnName="SRPublicFacade.methodResults.
SRPublicFacade_dataProvider_findAllStaff_result"/>
<action id="First" IterBinding="findAllStaffIter"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" RequiresUpdateModel="true"
Action="12"/>
</bindings>
The action element, First, defines the action binding that is directly referenced by the EL expression in the command button. The IterBinding attribute of the action binding references the method iterator binding, findAllStaffIter, which iterates over the data collection being operated on by the action. The findAllStaffIter is bound to the methodAction, findAllStaff, which encapsulates the information required to invoke the findAllStaff method.
Tip:
The numerical value of theAction attribute of the action element references the number constants in the OperationDefinition interface in the oracle.adf.model.meta package.Example 5-16 shows a command button that was created by dragging a method from the Data Control Palette and dropping it on a JSF page. In this example, the command button is bound to the removeServiceHistory method, which removes an object from the data collection. Parameters passed to the method when it is invoked identify which object to remove. The execute binding property in the EL expression in the actionListener attribute invokes the method when the user clicks the button
Example 5-16 EL Expression That References an Action Binding Object for a Method
<af:commandButton actionListener="#{bindings.removeServiceHistory.execute}"
text="removeServiceHistory"
disabled="#{!bindings.removeServiceHistory.enabled}"/
Example 5-17 shows the binding object created in the page definition file for the command button. When a command component is bound to a method, only one binding object is created in the page definition file—a methodAction. The methodAction binding defines the information needed to invoke the method, including any parameters, which are defined in the NamedData element.
Example 5-17 Method Action Binding Defined in the Page Definition File
<bindings>
<methodAction id="removeServiceHistory"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" MethodName="removeServiceHistory"
RequiresUpdateModel="true" Action="999">
<NamedData NDName="serviceRequest"
NDType="oracle.srdemo.model.entities.ServiceRequest"/>
<NamedData NDName="serviceHistory"
NDType="oracle.srdemo.model.entities.ServiceHistory"/>
</methodAction>
</bindings>
When you create a databound component using the Data Control Palette, the EL expression references specific ADF binding properties. At runtime, these binding properties can define such things as the default display characteristics of a databound UI component or specific parameters for iterator bindings. The ADF binding properties are defined by Oracle APIs. For a full list of the available properties for each binding type, see Appendix B, "Reference ADF Binding Properties".
Values assigned to certain properties are defined in the page definition file. For example, iterators can reference a property called RangeSize, which specifies the number of rows the iterator should display at one time. The value assigned to RangeSize is specified in the page definition file, as shown in Example 5-18
Example 5-18 Iterator Binding Object with the RangeSize Property
<accessorIterator id="serviceHistoryCollectionIterator" RangeSize="10"
Binds="serviceHistoryCollection"
DataControl="SRDemoSessionDataControl"
BeanClass="oracle.srdemo.model.ServiceHistory"
MasterBinding="findAllServiceRequestIter"/>
Use the JDeveloper Expression Builder to display a list of valid binding properties for each binding object. For information about how to use the Expression builder, see Section 5.6.2, "How to Use the Expression Builder".
While Oracle does not recommend this approach, you can access the bound values in another page's binding container from the current page using the data binding variable in an EL expression. The data binding variable references the binding context itself, which provides access to all the binding containers that are available. Use this variable when you want to bind to an object in the binding container of another page. The data variable must be immediately followed by the name of a page definition file that defines the binding container being referenced. For example:
#{data.mypagePageDef.BindingObject.propertyName}
At runtime, only the current incoming page's (or if the rendered page is different from the incoming, the rendered page's) binding container is automatically prepared by the framework during the current request. Therefore, to successfully access a bound value in another page from the current page, you must programmatically prepare that page's binding container in the current request (for example, using a backing bean). Otherwise, the bound values in that page may not be available or valid in the current request.
You may find cases, where you need to use the data variable to bind to values across binding containers. However, Oracle recommends that instead you use a backing bean to store page values and make them available to other pages. For more information about storing values in backing beans, see Section 10.2, "Using a Managed Bean to Store Information".
Caution:
As was mentioned in Section 5.5.4, "What You May Need to Know About Binding Container Scope", the binding container, the binding objects it contains are defined in session scope, but the values referenced by the binding objects are not. By default, theRowSetIterator state and the data caches are maintained between requests, which makes the bound value referenced by a binding object available across pages.
However, when referring to binding objects across pages, you cannot rely on the bound values at session scope. The lifecycle of bound values is managed by the data control. The availability of a bound value during a given request depends on whether the data control itself is available and whether the referenced binding container has been prepared in the lifecycle. So, before referencing a bound value in one binding container from another page, be sure that the binding container being referenced is prepared during a given request.
Also, your application can, programmatically or through the use of the CacheResults or Refresh attributes on an iterator binding, re-execute or clear an iterator during a request. In this case, the binding object values would no longer be available to other pages. For more information about the iterator binding attributes that clear (CacheResults) or refresh (Refresh) the iterator, see Section A.7, "<pageName>PageDef.xml".
