|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
 Previous |
 Next |
|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
|
Previous |
Next |
Page definition files define the binding objects that populate the data in the UI components at runtime. For every page that has ADF bindings, there must be a corresponding page definition file that defines every binding object referenced by the page. Page definition files provide design time access to all the ADF bindings currently used in a page. At runtime, the binding objects defined by a page definition file are instantiated in a binding container.
The first time you use the Data Control Palette to create a databound component, 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 on 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.
Example 5-7 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, "About the Bindings in the parameters Element")
executables (for more information, see Section 5.5.2.2, "About Bindings in the executables Element")
bindings (for more information, see Section 5.5.2.3, "About the Bindings 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. In Section 5.6, "Using ADF Databinding EL Expressions", you will see how the ADF databinding EL expressions reference the binding object names.
Example 5-7 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 Section A.7, "<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:
An action method binding when invoking the bound method. For information about action method bindings, see Section 5.5.2.3, "About the Bindings in the bindings Element".
An iterator binding to fetch its data set. For information about iterator bindings, see Section 5.5.2.2, "About Bindings 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.2.4, "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.
Example 5-8 shows how parameter binding objects can be defined in a page definition file.
Example 5-8 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 a value 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 a dollar sign ($) as the prefix for EL expressions that appear in the page definition file. However, you can use the hash sign (#) prefix 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 binding objects:
Iterator objects: Iterate over the data objects returned by methods and accessors and expose the current object and range state to the bindings. The range is the current set of objects returned by the iterator. For example, if a method returns a collection of user objects, the range may be the first ten user objects in the collection. Iterator bindings bind to a RowSetIterator object that iterates over the data objects. A RowSetIterator object manages the current object (also known as the row currency) and current range information. There is one iterator for each method return and accessor return used in the page. Most of the other bindings on the page must refer to an iterator.
The executables element shown in Example 5-9, defines two iterators and an invokeAction binding object.
Example 5-9 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>
In the example, the executables element contains two types of iterators: method and variable.
A method iterator iterates the results returned from a method. For example, the findServiceRequestIter method iterator 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 bind attribute of the methodIterator element. The RangeSize attribute defines the number of rows to return at one time. A RangeSize value of -1 causes the iterator to return all the rows. A method iterator is always related to a methodAction defined in the bindings element. The methodAction encapsulates the details about how to invoke the method and what parameters (if any) the method is expecting. In the example, the method iterator is related to the findServiceRequests method action. The NamedData elements define the parameters to be passed to the method. The table binding object defined in the bindings element references the findServiceRequestIter iterator in the IterBinding attribute to populate the data in the table.The invokeAction object, also in the executables element, invokes the findServiceRequests method. 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".)
A variable iterator iterates the variables created within the binding container. These 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 binding container variables. In the example, there is one variable iterator that iterates over the variable called setCurrentRowWithKey_rowKey, which is a parameter required by the setCurrentRowWithKey operation.
If an accessor return from the Data Control Palette had been dropped on the page, the executables element would contain an accessor iterator. An accessor iterator iterates over detail objects returned by accessor methods. Accessor iterators are always related to a master iterator, which is the method iterator for the parent object. The accessor iterator returns the detail objects related to the current object in the master (or method) iterator. For more information about master-detail objects and iterators, see Chapter 8, "Working with Master-Detail Relationships".
At runtime, the bindings in the executables element are executed in the order in which they appear in the page definition file. Before they are executed, the runtime evaluates the Refresh and RefreshCondition attributes specified in the iterator. The Refresh and RefreshCondition attributes determine when or whether the executable should be invoked.
The bindings element of the page definition file defines the following types of binding objects:
Value binding objects: Display data in the UI by referencing an iterator. Each discrete UI component on a page is bound to a value binding object. Value binding objects include:
Table binding objects, which bind an entire table to a data collection
List binding objects, which binds the list items to a data collection or object
Tree binding objects, which bind the root node of a tree to a data collection
Attribute binding objects, which bind text fields to a specific attribute in a data collection or object
Some composite components, such as tables, selection lists, and trees are bound to a single value binding object, which references a single iterator to populate the data. However, each component in a form is individually bound to a value binding object.
methodAction binding objects: Encapsulate the details about how to invoke a method and what parameters (if any) the method is expecting. There is one method action binding for each method iterator used in the page.
Action binding objects: Bind an action component, such as a button or link, to a data control operation or method. In an action binding, a component's actionListener is bound to the operations that perform the required action. Operations for action bindings can be built-in ones supplied by the binding objects (like Create, Delete, Next, Previous, Save, Commit) or custom methods from your data control implementation.
In the bindings element shown in Example 5-10, there is one methodAction binding called findServiceRequest, one value binding for a table called findServiceRequest1 and one action binding called setCurrentRowWithKey.
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 that iterates over the data collection that populates that value. Notice that a table is handled by a single binding object that references the iterator 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. Forms, unlike tables, can contain attributes from multiple data collections. The AttrNames element defines all the attribute values returned by the iterator.
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 and passes it the current row key as a parameter, which is defined in the namedData element.
Example 5-10 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>
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. Then, the binding context instantiates the binding container, which 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 databinding expressions in 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. The values referred to by binding objects are managed by the data control and RowSetIterator objects, both of which also have session scope. By default, the RowSetIterator state and the data caches are maintained between requests. However, 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.
