| Oracle® Application Development Framework Developer's Guide 10g (10.1.3.1.0) Part Number B28967-01 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide 10g (10.1.3.1.0) Part Number B28967-01 |
|
|
View PDF |
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.
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.
