Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# A.7 <pageName>PageDef.xml

The <pageName>PageDef.xml files are created each time you insert a databound component into a web page using the Data Control Palette or Structure window. These XML files define the Oracle ADF binding container for each web page in the application. The binding container provides access to the bindings within the page. Therefore, you will have one XML file for each databound web page.

Note: You cannot rename the <pageName>PageDef.xml file in JDeveloper, but you can rename the file outside of JDeveloper in your MyWork/ViewController/src/view folder. If you do rename the <pageName>PageDef.xml file, you must also update the DataBindings.cpx file references in the <Containee> id and FullName attributes.

The PageDef.xml file appears in the /src/view directory of the ViewController project folder. The Application Navigator displays the file in the view package of the Application Sources folder. When you double-click the file node, the page description appears in the XML Source Editor. To edit the page description parameters, use the Property Inspector and select the desired parameter in the Structure window.

There are important differences in how the PageDefs are generated for methods that return a single-value and a collection, so these are listed separately below.

## A.7.1 PageDef.xml Syntax

The toplevel element of the PageDef.xml file is <pageDefinition>:

    <<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"                version="10.1.3.35.83" id="<pagename>PageDef"                Package="oracle.srdemo.view.pageDefs">

where the XML namespace attribute (xmlns) specifies the URI to which the ADF binding container binds at runtime. Only the package name is editable; all other attributes should have the values shown.

Example A-7 displays the child element hierarchy of the <pageDefinition> element. Note that each business service for which you have created a data control, will have its own <AdapterDataControl> definition.

Example A-7 PageDef.xml Element Hierarchy

    <?xml version="1.0" encoding="UTF-8" ?>
    <pageDefinition>
        <parameters>
            ...
        </parameters>
        <executables>
            ...
        </executables>
        <bindings>
            ...
        </bindings>
    </pageDefinition>

The child elements have the following usages:

- <parameters> defines page-level parameters that are EL accessible. These parameters store information local to the web page request and may be accessed in the binding expressions.

- <executables> defines the list of items (methods, view objects, and accessors) to execute during the prepareModel phase of the ADF page lifecycle. Methods to be executed are defined by <methodIterator>. The lifecycle performs the execute in the sequence listed in the <executables> section. Whether or not the method or operation is executed depends on it's refresh or refreshCondition attribute value. Built-in operations on the data control are defined by:

  <page> - definition for a nested page definition (binding container)

  <iterator> - definition to a named collection in DataControls

  <accessorIterator> - definition to get an accessor in a data control hierarchy

  <methodIterator> - definition to get to an iterator returned by an invoked method defined by a methodAction in the same file

  <variableIterator> - internal iterator that contains variables declared for the binding container

  <invokeAction> - definition of which mtehod to invoke as an executable

- <bindings> refers to an entry in <executables> to get to the collection from which bindings extract/submit attribute level data.

Table A-4 describes the attributes of the toplevel <pageDefinition> element.

Table A-4 Attributes of the PageDef.xml File <pageDefinition> Element

Element Syntax | Attributes | Attribute Description
--- | --- | ---
`<pageDefinition>` | ControllerClass | Fully qualified classname to create when controller requests a PageController object for this bindingContainer
| EnableTokenValidation | Enables currency validation for this bindingContainer when a postback occurs. This is to confirm that the web tier state matches the state that that particular page was rendered with.
| FindMode | IThis is for legacy (10.1.2) use only and indicates if this bindingContainer should start out in findMode when initially prepared.
| MsgBundleClass | Fully qualified package name. Identifies the class which contains translation strings for any bindings
| Viewable | An EL expression that should resolve at runtime to whether this binding and the associated component should be rendered or not.

Table A-5 describes the attributes of the child element of <parameters>.

Table A-5 Attributes of the PageDef.xml File <parameters> Element

Element Syntax | Attributes | Attribute Description
--- | --- | ---
`<parameter>` | id | Unique identifier. May be referenced by ADF bindings
| option | Indicates the usage of the variable within the binding container: Final indicates that this parameter cannot be passed in by a usage of this binding container, it must use the default value in the definition. Optional indicates the variable value need not be provided. Mandatory indicates the variable value must be provided or a binding container exception will be thrown.
| readonly | Indicates whether the parameter value may be modified or not. Set to true when you do not want the application to modify the parameter value.
| value | A default value, this can be an EL expression.

Table A-6 describes the attributes of the PageDef.xml <executables> elements.

Table A-6 Attributes of the PageDef.xml File <executables> Element

Element Syntax | Attributes | Attribute Description
--- | --- | ---
`<accessorIterator>` | BeanClass | Identifies the Java type of beans in the associated iterator/collection.
| CacheResults | If true, manage the data collection between requests.
| DataControl | The data control which interprets/returns the collection referred to by this iterator binding.
| id | Unique identifier. May be referenced by any ADF value binding.
| MasterBinding | Reference to the methodIterator (or iterator) that binds the data collection that serves as the master to the accessor iterator's detail collection.
| ObjectType | This is used for ADF BC only. A boolean value determines if the collection is an object type or not.
| RangeSize | Specifies the number of data objects in a range to fetch from the bound collection. The range defines a window you can use to access a subset of the data objects in the collection. By default, the range size is set to a range that fetches just ten data objects. Use RangeSize when you want to work with an entire set or when you want to limit the number of data objects to display in the page. Note that the values -1 and 0 have specific meaning: the value -1 returns all available objects from the collection, while the value 0 will return the same number of objects as the collection uses to retrieve from its data source.
| Refresh | Determines when and whether the executable should be invoked. Set one of the following properties as required: always - causes the executable to be invoked each time the binding container is prepared. This will occur when the page is displayed and when the user submits changes, or when the application posts back to the page. deferred - refresh occurs when another binding requires/refers to this executable.Since refreshing an executable may be a performance concern, you can set the refresh to only occur if it's used in a binding that is being rendered. ifNeeded - whenever the framework needs to refresh the executable because it has not been refreshed to this point. For example, when you have an accessor hierarchy such that a detail is listed first in the page definition, the master could be refreshed twice (once for the detail and again for the master's iterator). Using ifNeeded gives the mean to avoid duplicate refreshes. This is the default behavior for executables. never - When the application itself will call refresh on the executable during one of the controller phases and does not want the framework to refresh it at all. prepareModel - causes the executable to be invoked each time the page's binding container is prepared. prepareModelIfNeeded - causes the executable to be invoked during the prepareModel phase if this executable has not been refreshed to this point. See also ifNeeded above. renderModel - causes the executable to be invoked each time the page is rendered. renderModelIfNeeded - causes the executable to be invoked during the page's renderModel phase on the condition that it is needed. See also ifNeeded above.
| RefreshCondition | An EL expression that when resolved, determines when and whether the executable should be invoked. For example, ${!bindings.findAllServiceRequestIter.findMode} resolves the value of the findModel on the iterator in the ADF binding context AllServiceRequest. Hint: Use the Property Inspector to create expressions from the available objects of the binding context (bindings namespace) or binding context (data namespace), JSF managed beans, and JSP objects.
<invokeAction> | Binds | Determines the action to invoke. This may be on any actionBinding. Additionally, in the case, of the EJB session facade data control, you may bind to the finder method exposed by the data control. Built-in actions supported by the EJB session facade data control include: Execute executes the bound action defined by the data collection. Find retreives a data object from a collection. First navigates to the first data object in the data collection range. Last navigates to the first data object in the data collection range. Next navigates to the first data object in the data collection range. If the current range position is already on the last data object, then no action is performed. Previous navigates to the first data object in the data collection range. If the current position is already on the first data object, then no action is performed. setCurrentRowWithKey passes the row key as a String converted from the value specified by the input field. The row key is used to set the currency of the data object in the bound data collection. When passing the key, the URL for the form will not display the row key value. You may use this operation when the data collection defines a multipart attribute key. setCurrentRowWithKeyValue is used as above, but when you want to use a primary key value instead of the stringified key.
| id | Unique identifier. May be referenced by any ADF action binding
| Refresh | see Refresh above.
| RefreshCondition | see RefreshCondition above.
<iterator> and <methodIterator> | BeanClass | Identifies the Java type of beans in the associated iterator/collection
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| Binds | see Binds above.
| CacheResults | see CacheResults above
| DataControl | Name of the DataControl usage in the bindingContext (.cpx) which this iterator is associated with.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF value binding.
| ObjectType | Not used by EJB session facade data control (used by ADF Business Components only).
| RangeSize | see RangeSize above
| Refresh | see Refresh above
| RefreshCondition | see RefreshCondition above
<page> and <variableIterator> | id | Unique identifier. In the case of <page>, refers to nested page/region that is included in this page. In the case of the <variableIterator> executable, the identifier may be referenced by any ADF value binding
| path | Used by <page> executable only. Advanced, a fully qualified path that may reference another page's binding container.
| Refresh | see Refresh above
| RefreshCondition | see RefreshCondition above

Table A-7 describes the attributes of the PageDef.xml <bindings> element.

Table A-7 Attributes of the PageDef.xml File <bindings> Elements

Element Syntax | Attributes | Attribute Description
--- | --- | ---
`<action>` | Action | Fully qualified package name. Identifies the class for which the data control is created. In the case of the EJB session facade, this the session bean
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| DataControl | Name of the DataControl usage in the bindingContext (.cpx) which this iteratorBinding or actionBinding is associated with.
`<attributeValues>` | ApplyValidation | Set to True by default. When true, controlBinding executes validators defined on the binding. You can set to False in the case of ADF BC, when running in local mode and the same validators are already defined on the corresponding attribute.
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| ControlClass | Used internally for testing purposes.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF action binding
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| NullValueId | Refers to the entry in the message bundle for this bindingContainer that contains the String to indicate the null value in a list display.
`<button>` | ApplyValidation | Set to True by default. When true, controlBinding executes validators defined on the binding. You can set to False in the case of ADF BC, when running in local mode and the same validators are already defined on the corresponding attribute.
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| BoolVal | Identifies whether the value at the zero index in the static value list in this boolean list binding represents true or false.
| ControlClass | Used internally for testing purposes.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF action binding
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| ListIter | Refers to the iteratorBinding that is associated with the source list of this listBinding.
| ListOperMode | Determines if this list binding is for navigation, contains a static list of values or is a LOV type list.
| NullValueFlag | Describes whether this list binding has a null value and if so, whether it should be displayed at the beginning of the list or the end.
| NullValueId | Refers to the entry in the message bundle for this bindingContainer that contains the String to indicate the null value in a list display.
<graph> | ApplyValidation | Set to True by default. When true, controlBinding executes validators defined on the binding. You can set to False in the case of ADF BC, when running in local mode and the same validators are already defined on the corresponding attribute.
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| BoolVal | Identifies whether the value at the zero index in the static value list in this boolean list binding represents true or false.
| ChildAccessorName | The name of the accessor to invoke to get the next level of nodes for a given Hierachicahl Node Type in a tree.
| ControlClass | Used internally for testing purposes.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF action binding
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| NullValueId | Refers to the entry in the message bundle for this bindingContainer that contains the String to indicate the null value in a list display.
`<list>` | ApplyValidation | Set to True by default. When true, controlBinding executes validators defined on the binding. You can set to False in the case of ADF BC, when running in local mode and the same validators are already defined on the corresponding attribute.
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| ControlClass | Used internally for testing purposes.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF action binding
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| ListIter | Refers to the iteratorBinding that is associated with the source list of this listBinding.
| ListOperMode | Determines if this list binding is for navigation, contains a static list of values or is a LOV type list.
| NullValueFlag | Describes whether this list binding has a null value and if so, whether it should be displayed at the beginning of the list or the end.
| NullValueId | Refers to the entry in the message bundle for this bindingContainer that contains the String to indicate the null value in a list display.
| StaticList | Defines a static list of values that will be rendered in the bound list component.
`<methodAction>` | Action | Fully qualified package name. Identifies the class for which the data control is created. In the case of the EJB session facade, this the session bean
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| ClassName | This is the class to which the method being invoked belongs.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DataControl | Name of the DataControl usage in the bindingContext (.cpx) which this iteratorBinding or actionBinding is associated with.
| DefClass | Used internally for testing.
| id | Unique identifier. May be referenced by any ADF action binding
| InstanceName | A dot-separated EL path to a Java object instance on which the associated method is to be invoked.
| IsLocalObjectReference | Set to True if the instanceName contains an EL path relative to this bindingContainer.
| IsViewObjectMethod | Set to True if the instanceName contains an instance-path relative to the associated data control's Application Module.
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| MethodName | Indicates the name of the operation on the given instance/class that needs to be invoked for this methodActionBinding.
| RequiresUpdateModel | Whether this action requires that the model be updated before the action is to be invoked.
| ReturnName | The EL path of the result returned by the associated method.
`<table>` and <tree> | ApplyValidation | Set to True by default. When true, controlBinding executes validators defined on the binding. You can set to False in the case of ADF BC, when running in local mode and the same validators are already defined on the corresponding attribute.
| BindingClass | This is for backward compatibility to indicate which class implements the runtime for this binding definition. Ignored in JDeveloper 10.1.3.
| ControlClass | Used internally for testing purposes.
| CustomInputHandler | This is the class name for a oracle.jbo.uicli.binding.JUCtrlValueHandler implementation that is used to process the inputValue for a given value binding.
| DefClass | Used internally for testing.
| DiscrValue | Indicates the discriminator value for a hierarchical type binding (type definition for a tree node). This value is used to determine if a given row in a collection being rendered in a polymorphic tree binding should be rendered using the containing hierarchical type binding.
| id | Unique identifier. May be referenced by any ADF action binding
| IterBinding | Refers to the iteratorBinding instance in this bindingContainer to which this binding is associated.
| NullValueId | Refers to the entry in the message bundle for this bindingContainer that contains the String to indicate the null value in a list display.

## A.7.2 PageDef.xml Sample for a Method That Returns a String

This is the page definition file that's created when you drop the method return User from the method findUserByEmail() in the Data Control Palette, SRPublicFacade.

Example A-8 PageDef for findUserByEmail()

    <?xml version="1.0" encoding="UTF-8" ?>
    <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                    version="10.1.3.36.7" id="untitled1PageDef"
                    Package="project1.pageDefs">
      <parameters/>
      <executables>
        <variableIterator id="variables"/>
        <methodIterator id="findUserByEmailIter" Binds="findUserByEmail.result"
                        DataControl="SRPublicFacade" RangeSize="10"
                        BeanClass="oracle.srdemo.model.entities.User"/>
      </executables>
      <bindings>
        <methodAction id="findUserByEmail"
                      InstanceName="SRPublicFacade.dataProvider"
                      DataControl="SRPublicFacade" MethodName="findUserByEmail"
                      RequiresUpdateModel="true" Action="999"
                      ReturnName="SRPublicFacade.methodResults.SRPublicFacade_dataProvider_findUserByEmail_result">
          <NamedData NDName="emailParam" NDValue="mkorf@oracle.com"
                     NDType="java.lang.String"/>
        </methodAction>
        <table id="findUserByEmail1" IterBinding="findUserByEmailIter">
          <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>
      </bindings>
    </pageDefinition>

## A.7.3 PageDef.xml Sample for a Method that Returns a Collection

This is the page definition file that's created when you drop the User node from the findAllStaff() method in the Data Control Palette, SRPublicFacade. This one is a collection.

Example A-9 PageDef for Method that Returns a Collection

    <?xml version="1.0" encoding="UTF-8" ?>
    <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                    version="10.1.3.36.7" id="untitled2PageDef"
                    Package="project1.pageDefs">
      <parameters/>
      <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"/>
        <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>
      </bindings>
    </pageDefinition>