| 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 appendix provides reference for the Oracle ADF metadata files that you create in your data model and user interface projects. You may use this information when you want to edit the contents of the metadata these files define.
This appendix includes the following sections:
Metadata files in the Oracle ADF application are structured XML files used by the application to:
Specify the parameters, methods, and return values available to your application's Oracle ADF data control usages.
Create objects in the Oracle ADF binding context and to define the runtime behavior of those objects.
Define configuration information about the UI components in JSF and Oracle ADF Faces.
Define application configuration information for the J2EE application server.
In the case of ADF bindings, you can use the binding-specific editors to customize the runtime properties of the binding objects. You can open a binding's editor when you display the Structure window for a page definition file and choose Properties from the context menu.
Additionally, you can view and edit the contents of any metadata file in JDeveloper's XML editor. The easiest way to work with these file is through the Structure window and Property Inspector. In the Structure window, you can select an element and in the Property Inspector, you can define attribute values for the element, often by choosing among dropdown menu choices. Use this reference to learn the choices you can select in the case of the Oracle ADF-specific elements.
The relationship between the Oracle ADF metadata files defines dependencies between the model data and the user interface projects. The dependencies are defined as file references within XML elements of the files.
Figure A-1 illustrates the hierarchical relationship of the XML metadata files that you may work with in the Oracle ADF application that uses an EJB session bean as a service interface to JavaBeans and JSF web pages.
These XML configuration files required in an Oracle ADF application appear in the data model project:
DataControls.dcx is the registry for the data controls in the application. It contains information about the type of data control needed to work with a particular service (e.g. EJB, JavaBean, XML, web service, etc.) and how to construct the data control at runtime.
For details about what you can configure in the DataControls.dcx file, see Section A.4.
Structure definition files are the structure definition XML files for each business service type in the application. It contains information about the type of data control needed to work with a particular service (e.g. EJB, JavaBean, XML, web service, etc.) and how to construct the data control at runtime. For example, in the SRDemo application, which uses an EJB session bean as a service interface to JavaBeans, these files appear in the data model project:
<sessionbeanname>.xml—This is the structure definition XML file for each data type involved in the service interface. The name matches the name of that data type. For an EJB service interface, there is one structure definition file for the service class itself.
<beanname>.xml—This is the structure definition XML file for each JavaBean that appears as method return values or method arguments in the service interface.
For details about what you can configure in the structure definition files, see Section A.5.
adfm.xml is the registry for the data controls in the JDeveloper design time. The Data Control Palette uses the file to locate the DataControls.dcx file that appears in the data model project. For a sample of the adfm.xml file, see Section A.4.3.
These standard XML configuration files for an Oracle ADF application appear in your user interface project:
DataBindings.cpx— This file contains the pageMap, page definitions references, and data control references. The file is created the first time you create a data binding for a UI component (either from the Structure window or from the Data Control Palette). The DataBindings.cpx file defines the Oracle ADF binding context for the entire application. The binding context provides access to the bindings across the entire application. The DataBindings.cpx file also contains references to the <pagename>PageDef.xml files that define the metadata for the Oracle ADF bindings in each web page.
See Appendix A, "DataBindings.cpx" for details about what you can configure in the DataBindings.cpx file.
<pagename>PageDef.xml—This is the page definition XML file. This file is created each time you design a new web page using the Data Control Palette or Structure window. These XML files contain the metadata used to create the bindings that populate the data in the web page's UI components. For every web page that refers to an ADF binding, there must be a corresponding page definition file with binding definitions.
See Appendix A, "<pageName>PageDef.xml" for details about what you can configure in the <pagename>PageDef.xml file.
These XML configuration files required in a JSF application appear in your user interface project:
web.xml—Part of the application's configuration is determined by the contents of its J2EE application deployment descriptor, web.xml. The web.xml file defines everything about your application that a server needs to know. The file plays a role in configuring the Oracle ADF data binding by setting up the ADFBindingFilter. Additional runtime settings include servlet runtime and initialization parameters, custom tag library location, and security settings.
For details about ADF data binding and JSF configuration options, see Appendix A, "web.xml".
faces-config.xml—This JSF configuration file lets you register a JSF application's resources, such as validators, converters, managed beans, and navigation rules. While an application can have more than one configuration resource file, and that file can have any name, typically the filename is faces-config.xml.
For details about JSF configuration options, see Appendix A, "faces-config.xml".
adf-faces-config.xml—This ADF Faces configuration file lets you configure ADF Faces-specific user interface features such as accessibility levels, custom skins, enhanced debugging, and right-to-left page rendering.
For details about ADF Faces configuration options, see Appendix A, "adf-faces-config.xml".
Figure A-2 illustrates the hierarchical relationship of the XML metadata files that you may work with in the web application that uses an EJB session bean as a service interface to JavaBeans. At runtime, the objects created from these files interact in this sequence:
When the first request for an ADF databound web page occurs, the servlet registers the Oracle ADF servlet filter ADFBindingFilter named in the web.xml file.
The binding filter creates a binding context by reading the CpxFileName init param from the web.xml file.
The binding context creates the binding container by loading the <pagename>PageDef.xml file as referenced by the <pagemap> element from the DataBindings.cpx file.
The binding container's prepareModel phase prepares/refreshes all the executables.
An iterator binding gets executed by referencing the named method on the session bean facade specified by the data control factory named in the DataControls.dcx file.
The binding container also creates the bindings defined in the <bindings> section of the <pagename>PageDef.xml file for the mapped web page.
The web page references to ADF bindings through EL using the expression #{bindings} get resolved by accessing the binding container of the page.
The page pulls the available data from the bindings on the binding container.
The DataControls.dcx file is created in the /src/package directory of the data model project folder when you create data controls on the business services. There can be one .dcx file for each model project. The .dcx file identifies the Oracle ADF model layer data control classes that facilitate the interaction between the client and the available business service. There will be one data control definition for each data control type used in the project.
The JDeveloper design time maintains path information for the DataControls.dcx file in the adfm.xml registry file located in the model project's META-INF folder. When you create a data control, JDeveloper will automatically update this file.
In the case of EJB, web services, and bean-based data controls, you can edit this file in the Property Inspector to alter data control settings. For example, you can use the .dcx file to customize the global properties of each data control, such as whether to turn on/off sorting. See Table A-1 for details about the attributes.
The Application Navigator displays the .dcx file in the default package of the Application Sources folder. When you double-click the file node, the data control description appears in the XML Source Editor. To edit the data control attributes, use the Property Inspector and select the desired attribute in the Structure window.
The toplevel element of the DataControls.dcx file is <DataControlConfigs>:
<DataControlConfigs xmlns="http://xmlns.oracle.com/adfm/configuration"
version="10.1.3.35.65" Package="oracle.srdemo.model"
id="DataControls">
where the XML namespace attribute (xmlns) specifies the URI to which the data controls bind at runtime. Only the package name is editable; all other attributes should have the values shown.
Figure A-3 displays the toplevel <DataControlConfigs> element. Note that the BaseDataControl element is a placeholder for the concrete data control types. In the SRDemo application, the data control type is the AdapterDataControl.
Figure A-4 displays the <AdapterDataControl> element that substitutes for the placeholder <BaseDataControlType> element. Note that each business service for which you have created a data control, will have its own <AdapterDataControl> definition.
The child elements have the following usages:
<AdapterDataControl> created by the Adapter Data Control to define properties of the data control. The properties of the data control definition varies with the business service for which the data control is created.
<CreatableTypes> defines types from which a constructor method may be called. For example, a type may be an EJB, TopLink object, JavaBean, or web service. Contains one or more child elements <TypeInfo>.
<Source> defines the service for which the data control is created. Used only in the case of adapter-based data controls, such as EJB session facade data controls. In the case of the EJB session facade, contains the child element <ejb-definition>.
Table A-1 describes the attributes of the DataControls.dcx elements.
Table A-1 DataControls.dcx File Metadata
| Element Syntax | Attributes | Attribute Description |
|---|---|---|
|
BeanClass |
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 |
|
|
Definition |
Identifies the class for which the data control is created. This is used for backward compatibility. |
|
|
FactoryClass |
Fully qualified package name. Identifies the ADF runtime factory class that creates an instance of the data control. |
|
|
id |
Unique identifier. Referenced by the DataBindings.cpx file. |
|
|
ImplDef |
Internal. |
|
|
SupportsFindMode |
Determines whether the data control supports preparing queries with user supplied criteria when preparing ADF iterator binding objects. Default is false for EJB session facade beans. Set to false if you want to globally prevent all iterator-bound web pages in the application from operating in find mode. |
|
|
SupportsRangeSize |
Determines whether the data control supports returning a user-defined number of data objects when preparing ADF iterator binding objects. Default is false for EJB session facade beans. |
|
|
SupportsResetState |
This attribute is deprecated. Determines whether the data control supports resetting the state. Default is false for EJB session facade beans; not supported. |
|
|
SupportsSortCollection |
Determines whether the data control supports data object sorting on the service collection. Default is false for EJB session facade beans; not supported for collections exposed by EJB session facade finder methods. |
|
|
SupportsTransaction |
Determines whether the data control supports create, edit, and delete operations on the business service. Default is false for EJB session facade beans. |
|
|
SupportsUpdates |
Determines whether the data control supports write operations. Default is true for EJB session facade beans. |
|
|
xmlns |
URI used to identify the data control configuration namespace. At runtime, the data control object locates the runtime factory responsible for creating the definition objects for elements in its namespace. |
|
|
FullName |
Identifies the full type name of the Createable type. This element is defined only for those types that have constructors that appear in the Constructors folder of the Data Control Palette |
|
|
ejb-business-interface |
The Remote or Local interface that will be used to communicate with this Session bean |
|
|
ejb-interface-type |
Either local or remote. |
|
|
ejb-name |
The EJB's name. |
|
|
ejb-type |
The EJB's type, currently only Session is supported. |
|
|
ejb-version |
Either 3.0, 2.1, or 2.0. |
|
|
xmlns |
This is for internal use only and refers to the schema namespace; this cannot be updated. |
Example A-1 shows the syntax for a sample data control definition file. Notice that there are two session beans identified by the AdapterDataControl: SRPublicFacade and SRAdminFacade.
Example A-1 DataControls.dcx Sample File
<?xml version="1.0" encoding="UTF-8" ?>
<DataControlConfigs xmlns="http://xmlns.oracle.com/adfm/configuration"
version="10.1.3.35.65" Package="oracle.srdemo.model"
id="DataControls">
<AdapterDataControl id="SRPublicFacade"
FactoryClass="oracle.adf.model.adapter.DataControlFactoryImpl"
ImplDef="oracle.adfinternal.model.adapter.ejb.EjbDefinition"
SupportsTransactions="true" SupportsSortCollection="false"
SupportsResetState="false" SupportsRangesize="false"
SupportsFindMode="true"
Definition="oracle.srdemo.model.SRPublicFacade"
BeanClass="oracle.srdemo.model.SRPublicFacade"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"
SupportsUpdates="true">
<CreatableTypes>
<TypeInfo FullName="oracle.srdemo.model.entities.Product"/>
<TypeInfo FullName="oracle.srdemo.model.entities.ExpertiseArea"/>
<TypeInfo FullName="oracle.srdemo.model.entities.ServiceHistory"/>
<TypeInfo FullName="oracle.srdemo.model.entities.User"/>
<TypeInfo FullName="oracle.srdemo.model.entities.ServiceRequest"/>
</CreatableTypes>
<Source>
<ejb-definition ejb-version="3.0" ejb-name="SRPublicFacade"
ejb-type="Session" ejb-interface-type="local"
ejb-business-interface="oracle.srdemo.model.SRPublicFacade"
xmlns="http://xmlns.oracle.com/adfm/adapter/ejb"/>
</Source>
</AdapterDataControl>
<AdapterDataControl id="SRAdminFacade"
FactoryClass="oracle.adf.model.adapter.DataControlFactoryImpl"
ImplDef="oracle.adfinternal.model.adapter.ejb.EjbDefinition"
SupportsTransactions="true" SupportsSortCollection="false"
SupportsResetState="false" SupportsRangesize="false"
SupportsFindMode="true"
Definition="oracle.srdemo.model.SRAdminFacade"
BeanClass="oracle.srdemo.model.SRAdminFacade"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"
SupportsUpdates="true">
<CreatableTypes>
<TypeInfo FullName="oracle.srdemo.model.entities.ServiceHistory"/>
<TypeInfo FullName="oracle.srdemo.model.entities.User"/>
<TypeInfo FullName="oracle.srdemo.model.entities.ServiceRequest"/>
<TypeInfo FullName="oracle.srdemo.model.entities.Product"/>
<TypeInfo FullName="oracle.srdemo.model.entities.ExpertiseArea"/>
</CreatableTypes>
<Source>
<ejb-definition ejb-version="3.0" ejb-name="SRAdminFacade"
ejb-type="Session" ejb-interface-type="local"
ejb-business-interface="oracle.srdemo.model.SRAdminFacade"
xmlns="http://xmlns.oracle.com/adfm/adapter/ejb"/>
</Source>
</AdapterDataControl>
</DataControlConfigs>
The adfm.xml file is the registry for the data controls in the JDeveloper design time. For instance, the Data Control Palette uses the supplied path to facilitate locating the data controls used in the model project. When you create a data control, JDeveloper will automatically update this file located in the META-INF folder of the data model project.
Example A-2 shows the data control registry syntax.
Structure definition files are created to support a data control's structure, and the structure of read-only and updateable attributes and collections.
When you register a session bean as an Oracle ADF data control, an XML definition file is created in the Model project for every session bean. The structure definition file has the same name as the session bean, but has a .xml extension. A structure definition is also created for each EJB entity and TopLink POJO.
Figure A-5 shows the toplevel definition for the JavaBean structure definition.
The toplevel element of the structure definition is <JavaBean>:
<JavaBean xmlns="http://xmlns.oracle.com/adfm/beanmodel" version="10.1.3.35.83"
id="<beanname>" BeanClass="oracle.srdemo.model.entities.<beanname>"
Package="oracle.srdemo.model.entities" isJavaBased="true">
where the XML namespace attribute (xmlns) specifies the URI to which the structure definition binds at runtime. Only the package name is editable; all other attributes should have the values shown.
Figure A-6 displays the <Attribute> child element of the <JavaBean> element. It defines the structure definition of a bean attribute.
Figure A-7 displays the <AccessorMethod> child element of the <JavaBean> element. It defines the structure information for an attribute that returns an object.
Figure A-8 displays the <MethodAccessor> child element of the <JavaBean> element. It defines the structure information for a method that returns an object or collection. Note that unlike attribute accessors, method accessors can define parameters.
Table A-2 describes the attributes of the structure definition of the bean. Note that each attribute or method specified by the bean, will have its own <Attribute>, <AccessorAttribute>, and <MethodAccessor> definition and each method parameter will have its own <ParameterInfo> definition.
Table A-2 Attributes of the Structure Definition for a Bean
| Element Syntax | Attributes | Attribute Description |
|---|---|---|
|
AttrLoad |
Internal |
|
|
DefaultValue |
This field is used only in case of variables and ADF Business Components datacontrol. For beans, since the beans themselves create a new bean instance, it is assumed that all properties are appropriately defaulted in the new instance. |
|
|
DiscrColumn |
Internal. |
|
|
IsNotNull |
Determines if the attribute is mandatory. |
|
|
IsPersistent |
Determines if an attribute is persistent or transient |
|
|
IsQueriable |
Determines if this attribute can participate in a WHERE clause |
|
|
IsUnique |
Determines if the attribute is unique, and will have a UNIQUE constraint generated in the database. |
|
|
IsUpdateable |
Determines if the attribute is always updateable, only updateable while new, or never updateable. |
|
|
IsVisible |
.Determines if the attribute is visible or hidden. |
|
|
Name |
The attributes name. |
|
|
PrecisionRule |
Determines whether precision should be applied. If true, the precision rule is applied. |
|
|
PrimaryKey |
.Determines the attributes that participate in a primary key. |
|
|
ArrayElementType |
This is only used for ADF Business Components domains, to define the array type. |
|
|
BeanClass |
Fully qualified package name. Identifies the full path to the type's structure definition. |
|
|
CollectionBeanClass |
Fully qualified package name. Identifies the full path to the method accessor's structure definition. In the case of a session bean that accesses an entity that is a collection, this value will be either ReadOnlyCollection or UpdateableCollection. |
|
|
id |
Unique identifier. Same as the method name that appears in the bean class. |
|
|
IsCollection |
Identifies whether the method accessor returns a collection. Set to true when the entity accessed is a collection and specify the CollectionBeanClass attribute value. |
|
|
SourceName |
The name of the property on the source of this bean. |
|
|
BeanClass |
Fully qualified package name. Identifies the full path to the type's structure definition. |
|
|
CollectionBeanClass |
Fully qualified package name. Identifies the full path to the method accessor's structure definition. In the case of a session bean that accesses an entity that is a collection, this value will be either ReadOnlyCollection or UpdateableCollection. |
|
|
id |
Unique identifier. Same as the method name that appears in the bean class. |
|
|
IsCollection |
Identifies whether the method accessor returns a collection. Set to true when the entity accessed is a collection and specify the CollectionBeanClass attribute value. |
|
|
ReturnNodeName |
Unique identifier. Name used in the Data Control Palette to display the return node. |
|
|
id |
Unique identifier. Same as the method parameter name that appears in the method signature of the session bean class |
|
|
Type |
Specifies the data type of the parameter |
Example A-3 shows the sample SRAdminFacade.xml file from the SRDemo application. Notice that the SRAdminFacade.xml file lists attributes, accessors, and operations. Notice that operations may have parameters which reference other structure definitions (which are in turn composed of attributes, accessors, and operations).
Example A-3 Structure Definition of SRAdminFacade.xml
<?xml version="1.0" encoding="UTF-8" ?>
<JavaBean xmlns="http://xmlns.oracle.com/adfm/beanmodel" version="10.1.3.35.83"
id="SRAdminFacade" BeanClass="oracle.srdemo.model.SRAdminFacade"
Package="oracle.srdemo.model" isJavaBased="true">
<MethodAccessor IsCollection="false"
Type="oracle.srdemo.model.entities.ExpertiseArea"
BeanClass="oracle.srdemo.model.entities.ExpertiseArea"
id="createExpertiseArea"
ReturnNodeName="oracle.srdemo.model.entities.ExpertiseArea">
<ParameterInfo id="product" Type="oracle.srdemo.model.entities.Product"
isStructured="true"/>
<ParameterInfo id="user" Type="oracle.srdemo.model.entities.User"
isStructured="true"/>
<ParameterInfo id="prodId" Type="java.lang.Integer" isStructured="false"/>
<ParameterInfo id="userId" Type="java.lang.Integer" isStructured="false"/>
<ParameterInfo id="expertiseLevel" Type="java.lang.String"
isStructured="false"/>
<ParameterInfo id="notes" Type="java.lang.String" isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false"
Type="oracle.srdemo.model.entities.Product"
BeanClass="oracle.srdemo.model.entities.Product"
id="createProduct"
ReturnNodeName="oracle.srdemo.model.entities.Product">
<ParameterInfo id="prodId" Type="java.lang.Integer" isStructured="false"/>
<ParameterInfo id="name" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="image" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="description" Type="java.lang.String"
isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="oracle.srdemo.model.entities.User"
BeanClass="oracle.srdemo.model.entities.User" id="createUser"
ReturnNodeName="oracle.srdemo.model.entities.User">
<ParameterInfo id="userId" Type="java.lang.Integer" isStructured="false"/>
<ParameterInfo id="userRole" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="email" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="firstName" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="lastName" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="streetAddress" Type="java.lang.String"
isStructured="false"/>
<ParameterInfo id="city" Type="java.lang.String" isStructured="false"/>
<ParameterInfo id="stateProvince" Type="java.lang.String"
isStructured="false"/>
<ParameterInfo id="postalCode" Type="java.lang.String"
isStructured="false"/>
<ParameterInfo id="countryId" Type="java.lang.String" isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="true" Type="oracle.srdemo.model.entities.User"
BeanClass="oracle.srdemo.model.entities.User"
id="findAllStaffWithOpenAssignments"
ReturnNodeName="oracle.srdemo.model.entities.User"
CollectionBeanClass="UpdateableCollection"/>
<MethodAccessor IsCollection="true"
Type="oracle.srdemo.model.entities.ExpertiseArea"
BeanClass="oracle.srdemo.model.entities.ExpertiseArea"
id="findExpertiseByUserId"
ReturnNodeName="oracle.srdemo.model.entities.ExpertiseArea"
CollectionBeanClass="UpdateableCollection">
<ParameterInfo id="userIdParam" Type="java.lang.Integer"
isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="java.lang.Object" id="mergeEntity"
ReturnNodeName="Return">
<ParameterInfo id="entity" Type="java.lang.Object" isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="java.lang.Object"
id="persistEntity" ReturnNodeName="Return">
<ParameterInfo id="entity" Type="java.lang.Object" isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="java.lang.Object"
id="refreshEntity" ReturnNodeName="Return">
<ParameterInfo id="entity" Type="java.lang.Object" isStructured="false"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="removeEntity"
ReturnNodeName="Return">
<ParameterInfo id="entity" Type="java.lang.Object" isStructured="false"/>
</MethodAccessor>
</JavaBean>
The XML files that get created for a TopLink POJO, EJB entity or a Java bean are very similar, as the constructs listed in each case are generic ADF metadata. The following syntax shows a TopLink entity XML file.
Example A-4 shows the sample Product.xml file from the SRDemo application. Notice the structure of the file, that it is broken up into attributes, accessors, and operations (methods).
Example A-4 Structure Definition of Product.xml
<?xml version="1.0" encoding="UTF-8" ?>
<JavaBean xmlns="http://xmlns.oracle.com/adfm/beanmodel" version="10.1.3.35.65"
id="Product" BeanClass="oracle.srdemo.model.entities.Product"
Package="oracle.srdemo.model.entities" isJavaBased="true">
<Attribute Name="description" Type="java.lang.String"/>
<Attribute Name="image" Type="java.lang.String"/>
<Attribute Name="name" Type="java.lang.String"/>
<Attribute Name="prodId" Type="java.lang.Integer"/>
<AccessorAttribute id="expertiseAreaCollection" IsCollection="true"
BeanClass="oracle.srdemo.model.entities.ExpertiseArea"
CollectionBeanClass="UpdateableCollection"/>
<AccessorAttribute id="serviceRequestCollection" IsCollection="true"
BeanClass="oracle.srdemo.model.entities.ServiceRequest"
CollectionBeanClass="UpdateableCollection"/>
<MethodAccessor IsCollection="false" Type="void" id="addExpertiseArea"
ReturnNodeName="Return">
<ParameterInfo id="anExpertiseArea"
Type="oracle.srdemo.model.entities.ExpertiseArea"
isStructured="true"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="addExpertiseArea"
ReturnNodeName="Return">
<ParameterInfo id="index" Type="int" isStructured="false"/>
<ParameterInfo id="anExpertiseArea"
Type="oracle.srdemo.model.entities.ExpertiseArea"
isStructured="true"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="addServiceRequest"
ReturnNodeName="Return">
<ParameterInfo id="aServiceRequest"
Type="oracle.srdemo.model.entities.ServiceRequest"
isStructured="true"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="addServiceRequest"
ReturnNodeName="Return">
<ParameterInfo id="index" Type="int" isStructured="false"/>
<ParameterInfo id="aServiceRequest"
Type="oracle.srdemo.model.entities.ServiceRequest"
isStructured="true"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="removeExpertiseArea"
ReturnNodeName="Return">
<ParameterInfo id="anExpertiseArea"
Type="oracle.srdemo.model.entities.ExpertiseArea"
isStructured="true"/>
</MethodAccessor>
<MethodAccessor IsCollection="false" Type="void" id="removeServiceRequest"
ReturnNodeName="Return">
<ParameterInfo id="aServiceRequest"
Type="oracle.srdemo.model.entities.ServiceRequest"
isStructured="true"/>
</MethodAccessor>
<ConstructorMethod IsCollection="false" Type="void" id="Product"/>
</JavaBean>
Four additional files are also generated:
These files support the Data Control Palette in JDeveloper. The files are used only at design time to specify the list of operations that the Data Control Palette may display for a given accessor. These files are referenced by the accessor's CollectionBeanClass attribute. Typically you do not edit these files, but if you wanted to remove an operation from the Palette, you could remove an item on this list.
Example A-2 shows a read-only collection. The syntax for all four design-time XML files is similar.
Example A-5 Read-only Collection Syntax
<?xml version="1.0" encoding="UTF-8" ?>
<JavaBean xmlns="http://xmlns.oracle.com/adfm/beanmodel" version="10.1.3.35.65"
id="ReadOnlyCollection" BeanClass="ReadOnlyCollection"
isJavaBased="false">
<BuiltinOperation id="IteratorExecute"/>
<BuiltinOperation id="Find"/>
<BuiltinOperation id="First"/>
<BuiltinOperation id="Last"/>
<BuiltinOperation id="Next"/>
<BuiltinOperation id="Previous"/>
<BuiltinOperation id="NextSet"/>
<BuiltinOperation id="PreviousSet"/>
<BuiltinOperation id="setCurrentRowWithKey"/>
<BuiltinOperation id="setCurrentRowWithKeyValue"/>
</JavaBean>
The DataBindings.cpx file is created in the user interface project the first time you drop a data control usage onto a web page in the HTML Visual Editor. The .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. When you insert a databound UI component into your document, the page will contain binding expressions that access the Oracle ADF binding objects at runtime.
If you are familiar with building ADF applications in earlier releases of JDeveloper, you'll notice that the .cpx file no longer contains all the information copied from the DataControls.dcx file, but only a reference to it. Therefore, if you need to make changes to the .cpx file, you must edit the DataControls.dcx file.
The DataBindings.cpx file appears in the /src directory of the user interface project folder. When you double-click the file node, the binding context description appears in the XML Source Editor. (To edit the binding context parameters, use the Property Inspector and select the desired parameter in the Structure window.)
The toplevel element of the DataBindings.cpx file is <DataControlConfigs>:
<DataControlConfigs xmlns="http://xmlns.oracle.com/adfm/configuration"
version="10.1.3.35.65" Package="oracle.srdemo.model"
id="DataControls">
where the XML namespace attribute (xmlns) specifies the URI to which the data controls bind at runtime. Only the package name is editable; all other attributes should have the values shown.
Figure A-9 displays the child element hierarchy of the <DataControlConfigs> element. Note that each business service for which you have created a data control, will have its own <dataControlUsages> definition.
The child elements have the following usages:
<pageMap> element maps all user interface URLs and the corresponding pageDefinitionUsage name. This map is used at runtime to map an URL to its pageDefinition.
<pageDefinitionUsages> element maps a PageDefinition Usage (BindingContainer instance) name to the corresponding pageDefinition definition. The id attribute represents the usage id. The path attribute represents the full path to the page definition.
<dataControlUsages> element declares a list of datacontrol (shortnames) and corresponding path to the datacontrol definition entries in the dcx or xcfg file.
Table A-3 describes the attributes of the DataBindings.cpx elements.
Table A-3 Attributes of the DataBindings.cpx File Elements
Example A-6 shows the syntax for the DataBindings.cpx file in the SR Demo application. It uses two session facades data controls and a URL data control. In the following code, notice the references to the data controls within the DCX. For example, <dc id="SRDemoFAQ" path="oracle.srdemo.faq.SRDemoFAQ"/> finds "SRDemoFAQ" via the data control id within DataControls.dcx.
Example A-6 DataBindings.cpx Sample
<?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"/>
<page path="/app/staff/SREdit.jspx" usageId="SREditPageDef"/>
<page path="/app/staff/SRStaffSearch.jspx" usageId="SRStaffSearchPageDef"/>
<page path="/app/staff/SRSearch.jspx" usageId="SRSearchPageDef"/>
<page path="/app/SRMain.jspx" usageId="SRMainPageDef"/>
<page path="/app/management/SRManage.jspx" usageId="SRManagePageDef"/>
<page path="/app/SRFaq.jspx" usageId="SRFaqPageDef"/>
</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"/>
<page id="SREditPageDef"
path="oracle.srdemo.view.pageDefs.app_staff_SREditPageDef"/>
<page id="SRStaffSearchPageDef"
path="oracle.srdemo.view.pageDefs.app_staff_SRStaffSearchPageDef"/>
<page id="SRSearchPageDef"
path="oracle.srdemo.view.pageDefs.app_staff_SRSearchPageDef"/>
<page id="SRMainPageDef"
path="oracle.srdemo.view.pageDefs.app_SRMainPageDef"/>
<page id="SRManagePageDef"
path="oracle.srdemo.view.pageDefs.app_management_SRManagePageDef"/>
<page id="SRFaqPageDef"
path="oracle.srdemo.view.pageDefs.app_SRFaqPageDef"/>
</pageDefinitionUsages>
<dataControlUsages>
<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 <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 for the id and path attributes in the <pageDefinitionUsages> element.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.
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 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 method 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
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 |
|---|---|---|
|
id |
Unique identifier. May be referenced by ADF bindings |
|
|
option |
Indicates the usage of the variable within the binding container:
|
|
|
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 |
|---|---|---|
|
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 Business Components 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:
|
|
|
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 findMode 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. |
|
|
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:
|
|
|
id |
Unique identifier. May be referenced by any ADF action binding |
|
|
Refresh |
see Refresh above. |
|
|
RefreshCondition |
see RefreshCondition above. |
|
|
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 |
|
|
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 |
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. |
|
|
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 Business Components, 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. |
|
|
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 Business Components, 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. |
|
|
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 Business Components, 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 Hierarchical 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. |
|
|
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 Business Components, 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. |
|
|
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. |
|
|
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. |
|
|
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 Business Components, 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. |
This is the page definition file that's created when you drop the method return User from the method findUserByEmail() from the Data Control Palette, SRPublicFacade node, into your open JSP page.
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>
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 node, into your open JSP page. 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>
This section describes Oracle ADF configuration settings specific to the standard web.xml deployment descriptor file.
In JDeveloper when you create a project that uses JSF technology, a starter web.xml file with default settings is created for you in /WEB-INF. To edit the file, double-click web.xml in the Application Navigator to open it in the XML editor.
The following must be configured in web.xml for all applications that use JSF and ADF Faces:
JSF servlet and mapping—The servlet javax.faces.webapp.FacesServlet that manages the request processing lifecycle for web applications utilizing JSF to construct the user interface.
ADF Faces filter and mapping—A servlet filter to ensure that ADF Faces is properly initialized by establishing a AdfFacesContext object. This filter also processes file uploads.
ADF resource servlet and mapping—A servlet to serve up web application resources (images, style sheets, JavaScript libraries) by delegating to a ResourceLoader.
The JSF servlet and mapping configuration settings are automatically added to the starter web.xml file when you first create a JSF project. When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the configuration settings for ADF Faces filter and mapping, and resource servlet and mapping.
Example A-10 Configuring web.xml for ADF Faces and JSF
<?xml version = '1.0' encoding = 'windows-1252'?> <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"> <description>Empty web.xml file for Web Application</description> <!-- Installs the ADF Faces Filter -- > <filter> <filter-name>adfFaces</filter-name> <filter-class>oracle.adf.view.faces.webapp.AdfFacesFilter</filter-class> </filter> <!-- Adds the mapping to ADF Faces Filter -- > <filter-mapping> <filter-name>adfFaces</filter-name> <servlet-name>Faces Servlet</servlet-name> </filter-mapping> <!-- Maps the JSF servlet to a symbolic name --> <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <!-- Maps ADF Faces ResourceServlet to a symbolic name -- > <servlet> <servlet-name>resources</servlet-name> <servlet-class>oracle.adf.view.faces.webapp.ResourceServlet</servlet-class> </servlet> <!-- Maps URL pattern to the JSF servlet's symbolic name --> <!-- You can use either a path prefix or extension suffix pattern --> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/faces/*</url-pattern> </servlet-mapping> <!-- Maps URL pattern to the ResourceServlet's symbolic name --> <servlet-mapping> <servlet-name>resources</servlet-name> <url-pattern>/adf/*</url-pattern> </servlet-mapping> ... </web-app>
Appendix A, "Configuring for State Saving" through Appendix A, "What You May Need to Know" detail the context parameters you could use in web.xml when you work with JSF and ADF Faces.
The following JSF and ADF Faces tasks are supported by the web.xml file.
You can specify the following state-saving context parameters:
javax.faces.STATE_SAVING_METHOD—Specifies where to store the application's view state. By default this value is server, which stores the application's view state on the server. If you wish to store the view state on the browser client, set this value to client. JDeveloper then automatically uses token-based client-side state saving (see oracle.adf.view.faces.CLIENT_STATE_METHOD below). You can specify the number of tokens to use instead of using the default number of 15 (see oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS below).
oracle.adf.view.faces.CLIENT_STATE_METHOD—Specifies the type of client-side state saving to be used when client-side state saving is enabled. The values are:
token—(Default) Stores the page state in the session, but persists a token to the client. The simple token, which identifies a block of state stored back on the HttpSession, is stored on the client. This enables ADF Faces to disambiguate multiple appearances of the same page. Failover HttpSession is supported. This matches the default server-side behavior that will be provided in JSF 1.2.
all—Stores all state on the client in a (potentially large) hidden form field. This matches the client-side state saving behavior in JSF 1.1, but it is useful for developers who do not want to use HttpSession.
oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS—Specifies how many tokens should be stored at any one time per user. The default is 15. When this value is exceeded, the state is lost for the least recently viewed pages, which affects users who actively use the Back button or who have multiple windows opened at the same time. If you're building HTML applications that rely heavily on frames, you would want to increase this value.
Example A-11 shows part of a web.xml file that contains state-saving parameters.
Example A-11 Context Parameters for State Saving in web.xml
<context-param> <param-name>javax.faces.STATE_SAVING_METHOD</param-name> <param-value>client</param-value> </context-param> <context-param> <param-name>oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS</param-name> <param-value>20</param-value> </context-param>
You can specify the following application view caching context parameter:
oracle.adf.view.faces.USE_APPLICATION_VIEW_CACHE—Specifies whether to enable the application view caching feature. When application view caching is enabled, the first time a page is viewed by any user, ADF Faces caches the initial page state at an application level. Subsequently, all users can reuse the page's cached state coming and going, significantly improving application performance. Default is false.
Example A-12 shows part of a web.xml file that contains the application view caching parameter.
You can specify the following debugging context parameters:
oracle.adf.view.faces.DEBUG_JAVASCRIPT—ADF Faces by default obfuscates the JavaScript it delivers to the client, as well as strip comments and whitespace. This dramatically reduces the size of the ADF Faces JavaScript download, but also makes it tricky to debug the JavaScript. Set to true to turn off the obfuscation during application development. Set to false for application deployment.
oracle.adf.view.faces.CHECK_FILE_MODIFICATION—By default this parameter is false. If it is set to true, ADF Faces will automatically check the modification date of your JSPs, and discard saved state when they change. When set to true, this makes development easier, but adds overhead that should be avoided when your application is deployed. Set to false for application deployment.
For testing and debugging in JDeveloper's embedded OC4J, you don't need to explicitly set this parameter to true because ADF Faces automatically detects the embedded OC4J and runs with the file modification checks enabled.
Example A-13 shows part of a web.xml file that contains debugging parameters.
Example A-13 Context Parameters for Debugging in web.xml
<context-param> <param-name>oracle.adf.view.faces.DEBUG_JAVASCRIPT</param-name> <param-value>true</param-value> </context-param> <context-param> <param-name>oracle.adf.view.faces.CHECK_FILE_MODIFICATION</param-name> <param-value>true</param-value> </context-param>
You can specify the following file upload context parameters:
oracle.adf.view.faces.UPLOAD_TEMP_DIR—Specifies the directory where temporary files are to be stored during file uploading. The default is the user's temporary directory.
oracle.adf.view.faces.UPLOAD_MAX_DISK_SPACE—Specifies the maximum amount of disk space that can be used in a single request to store uploaded files. The default is 2000K.
oracle.adf.view.faces.UPLOAD_MAX_MEMORY—Specifies the maximum amount of memory that can be used in a single request to store uploaded files. The default is 100K.
Example A-14 shows part of a web.xml file that contains file upload parameters.
Example A-14 Context Parameters for File Uploading in web.xml
<context-param> <param-name>oracle.adf.view.faces.UPLOAD_TEMP_DIR</param-name> <param-value>/tmp/Adfuploads</param-value> </context-param> <context-param> <param-name>oracle.adf.view.faces.UPLOAD_MAX_DISK_SPACE</param-name> <param-value>5120000</param-value> </context-param> <context-param> <param-name>oracle.adf.view.faces.UPLOAD_MAX_MEMORY</param-name> <param-value>512000</param-value> </context-param>
Note:
The file upload initialization parameters are processed by the defaultUploadedFileProcessor only. If you replace the default processor with a custom UploadedFileProcessor implementation, the parameters are not processed.For information about file uploading, see Section 11.6, "Providing File Upload Capability".
When you use ADF data controls to build web pages, the following must be configured in web.xml:
ADF binding filter—A servlet filter to create the ADFContext, which contains context information about ADF, including the security context and the environment class that contains the request and response object. ADF applications use this filter to preprocess any HTTP requests that may require access to the binding context.
Servlet context parameter for the application binding container—Specifies which CPX file the filter reads at runtime to define the application binding context. For information about CPX files, see Section 5.3, "Working with the DataBindings.cpx File".
In JDeveloper when you first use the Data Control Palette to build your databound JSF page, the ADF data binding configuration settings are automatically added to the web.xml file.
Example A-15 shows part of a web.xml file that contains ADF Model binding settings. For more information about the Data Control Palette and binding objects, see Chapter 5, "Displaying Data on a Page".
Example A-15 ADF Model Binding Configuration Settings in web.xml
<context-param> <param-name>CpxFileName</param-name> <param-value>view.DataBindings</param-value> </context-param> <filter> <filter-name>adfBindings</filter-name> <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class> </filter> <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>
Other optional, application-wide parameters for JSF are:
javax.faces.CONFIG_FILES—Specifies paths to JSF application configuration resource files. Use a comma-separated list of application-context relative paths for the value (see Example A-16). You need to set this parameter if you use more than one JSF configuration file in your application, as described in Appendix A, "Tasks Supported by the faces-config.xml".
javax.faces.DEFAULT_SUFFIX—Specifies a file extension (suffix) for JSP pages that contain JSF components. The default value is .jsp.
javax.faces.LIFECYCLE_ID—Specifies a lifecycle identifier other than the default set by the javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE constant.
If you have multiple filters for your application, make sure they are listed in web.xml in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.
ADF Faces leverages the Java Logging API (java.util.logging.Logger) to provide logging functionality when you run a debugging session. Java Logging is a standard API that is available in the Java Platform, starting with JDK 1.4. For the key elements, see the section "Java Logging Overview" at http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.
Typically you would want to configure the following in j2ee-logging.xml:
Change the logging level for Oracle ADF packages. See Section A.9.1.1.
Redirect the log output to a location, like a file, in addition to the default Log window in JDeveloper. See Section A.9.1.2.
Change the directory path that determines where your log file resides. See Section A.9.1.3.
The following JSF tasks are supported by the j2ee-logging.xml file.
When you want to change the logging level of individual Oracle ADF packages, edit <logger> in the <loggers> element of j2ee-logging.xml (see Example A-17). The default level of logging is INFO. Oracle recommends level="FINE" for detailed log messages. Note that package names are hierarchically inclusive. For instance, if you change the level of oracle.adf, the level specified will also apply to all classes that begin with the path oracle.adf. To change the level of specific classes, supply the full path; for instance, a level set for the package name oracle.adf.controller will not apply to other branches of the oracle.adf package.
For details about setting logging when debugging ADF applications, see Section 16.4.2, "Creating an Oracle ADF Debugging Configuration".
The default logger (name="oracle") is associated with two handlers: one for file output and another for console output (JDeveloper Log window). By default log messages are output to both locations at the same time. When you want to redirect the output for the log messages, edit <handler> in the <logger> element of j2ee-logging.xml (see Example A-18). For example, you can comment out the <handler name="oc4j-handler"/> when you want the output to only go to the JDeveloper Log window.
When you want to change where the log files reside, edit <log_handler> in the <log_handlers> element of j2ee-logging.xml (see Example A-19). The default directory for the log file is ../log/oc4j.
You register a JSF application's resources—such as validators, converters, managed beans, and the application navigation rules—in the application's configuration file. Typically you have one configuration file named faces-config.xml.
Note:
A JSF application can have more than one JSF configuration file. For example if you need individual JSF configuration files for separate areas of your application, or if you choose to package libraries containing custom components or renderers, you can create a separate JSF configuration file for each area or library. For details see, Section 4.2.3, "What You May Need to Know About Multiple JSF Configuration Files".In JDeveloper, when you create a project that uses JSF technology, an empty faces-config.xml file is created for you in /WEB-INF.
Typically you would want to configure the following in faces-config.xml:
Application resources such as default render kit, message bundles, and supported locales. Refer to Section A.10.1.1, Section A.10.1.3. and Section A.10.1.4.
Page-to-page navigation rules. See Section A.10.1.5.
Custom validators and converters. See Section A.10.1.6.
Managed beans for holding and processing data, handling UI events, and performing business logic.
If you use ADF data controls to build databound web pages, you also need to register the ADF phase listener in faces-config.xml. Refer to Section A.10.1.2.
The following JSF tasks are supported by the faces-config.xml file.
When you use ADF Faces components in your application, you must add the ADF default render kit in the <application> element of faces-config.xml. As mentioned earlier, JDeveloper creates one empty faces-config.xml file for you when you create a new project that uses JSF technology. When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the default render kit for ADF components into faces-config.xml (see Example A-20).
Example A-20 Configuring faces-config.xml for ADF Faces Components
<?xml version="1.0" encoding="windows-1252"?>
<!DOCTYPE faces-config PUBLIC
"-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
"http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<!-- Default render kit for ADF components -->
<application>
<default-render-kit-id>oracle.adf.core</default-render-kit-id>
</application>
...
</faces-config>
The ADF phase listener is used to execute the ADF page lifecycle. When you use ADF data binding, you need to specify a phase listener for ADF lifecycle phases. In JDeveloper when an ADF data control is inserted into a JSF page for the first time, a standard ADF phase listener is added to faces-config.xml in the <lifecycle> element.
The ADF phase listener listens for all the JSF phases before which and after which it needs to execute its own phases concerned with preparing the model, validating model updates, and preparing pages to be rendered. See Section 6.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles", for more information about how the ADF lifecycle phases integrate with the JSF lifecycle phases. Example A-21 shows part of a faces-config.xml that contains the ADF phase listener.
You may want to subclass the standard ADF phase listener when custom behavior, such as error handling, is desired. See Section 12.8, "Handling and Displaying Exceptions in an ADF Application" for details about subclassing the ADF phase listener. JDeveloper will not read the standard phase listener to faces-config.xml if it detects a subclass.
When you use a resource bundle for localized labels and messages, add the resource as a <message-bundle> in the <application> element of faces-config.xml (see Example A-22). The SRDemo application uses a resource properties file to hold the strings for the UI.
Example A-22 Registering a Message Bundle in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<application>
...
<message-bundle>oracle.srdemo.view.resources.UIResources</message-bundle>
...
</application>
...
</faces-config>
To reference a message bundle in a page, see Section 14.4, "Internationalizing Your Application".
Register the default and all supported locales for your application in the <application> element of faces-config.xml (see Example A-23).
Example A-23 Registering Default and Supported Locales in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<application>
...
<locale-config>
<default-locale>en</default-locale>
<supported-locale>en-US</supported-locale>
<supported-locale>es</supported-locale>
<supported-locale>fr</supported-locale>
</locale-config>
</application>
...
</faces-config>
JSF allows more than one <application> element in a single faces-config.xml file. The JSF Configuration Editor only allows you to edit the first instance in the file. You'll need to edit the file directly using the XML editor for any other <application> elements.
While you can enter navigation rules and cases directly in the faces-config.xml file, Oracle recommends you use the JSF Navigation Modeler. The Navigation Modeler enables you to lay out the pages in your JSF application and add navigation between the pages in the form of a diagram. To open the Navigation Modeler, double-click the faces-config.xml file in the Application Navigator. In the visual editor, activate the Diagram tab to display the Navigation Modeler.
When JDeveloper first creates an empty faces-config.xml, it also creates a diagram file to hold diagram details such as layout and annotations. JDeveloper always maintains this diagram file alongside the faces-config.xml file, which holds all the settings needed by your application. This means that if you are using versioning or source control, the diagram file is included along with the faces-config.xml file it represents.
The navigation cases you add to the diagram are reflected in faces-config.xml, without your needing to edit the file directly.
A navigation rule defines one or more cases that specify an outcome value. A navigation component in a web page specifies an outcome value in its action attribute, which triggers a specific navigation case when a user clicks that component. For example, in the SRList page of the sample application, when the user clicks the View button, the application displays the SRMain page. The action attribute on the View button has the string value View (see Example A-24). The corresponding code for the navigation case within the navigation rule for the SRList page is shown in Example A-25.
Example A-24 Action Outcome String Defined on View Button
<af:commandButton text="#{res['srlist.buttonbar.view']}"
action="View"/>
Example A-25 Creating Static Navigation Cases in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<navigation-rule>
<from-view-id>/SRList.jspx</from-view-id>
<navigation-case>
<from-outcome>Edit</from-outcome>
<to-view-id>/SREdit.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>View</from-outcome>
<to-view-id>/SRMain.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>Search</from-outcome>
<to-view-id>/SRSearch.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>Create</from-outcome>
<to-view-id>/SRCreate.jspx</to-view-id>
</navigation-case>
</navigation-rule>
...
</faces-config>
For information about creating JSF navigation rules and cases, as well as creating navigation components, see Chapter 9, "Adding Page Navigation".
JSF and ADF Faces standard validators and converters provide common validation checks for numeric ranges and string lengths, and the most common datatype conversions. If you need more complex validation rules and checks, or if you need to convert a component's data to a type other than a standard type, you can create your own custom validator or converter.
The custom validator or converter must implement the javax.faces.validator.Validator or javax.faces.convert.Converter interface, respectively. To make use of your custom validator or converter in an application, you have to register it in faces-config.xml using the <validator> or <converter> element (see Example A-26). For a custom validator, you can register it under an identifier (ID); for a custom converter you can register it under an ID or a fully qualified class name for a specific datatype.
Example A-26 Registering Custom Validators and Converters in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<validator>
<validator-id>oracle.srdemo.core.CreditCard</validator-id>
<validator-class>oracle.srdemo.core.CreditCardValidator</validator-class>
</validator>
<converter>
<converter-id>oracle.srdemo.core.CreditCard</validator-id>
<converter-class>oracle.srdemo.core.CreditCardConverter</converter-class>
</converter>
...
</faces-config>
In JSF, managed beans are the JavaBeans used to manage data between the web tier and the business tier of the application (similar to a data transfer object). At runtime, whenever the bean is referenced in a page through a value or method binding expression, the JSF implementation instantiates a bean, populates it with any declared, default values, and places it in the managed bean scope as defined in the faces-config.xml.
To register a managed bean in faces-config.xml, use the <managed-bean> element (see Example A-27). You have to specify the following for a managed bean:
Name—Determines how the bean will be referred to within the application using EL expressions, instead of using the bean's fully qualified class name.
Class—This is the JavaBean that contains the properties that hold the data, along with the corresponding accessor methods and/or any other methods (such as navigation or validation) used by the bean. This can be an existing class (such as a data transfer class), or it can be a class specific to the page (such as a backing bean).
Scope—This determines the scope within which the bean is stored. The valid scopes are:
application—The bean is available for the duration of the web application. This is helpful for global beans such as LDAP directories.
request—The bean is available from the time it is instantiated until a response is sent back to the client. This is usually the life of the current page.
session—The bean is available to the client throughout the client's session.
none—The bean is instantiated each time it is referenced.
Managed properties are any properties of the bean that you would like populated with a value when the bean is instantiated. The set method for each declared property is run once the bean is constructed. To initialize a managed bean's properties with set values, including those for a bean's map or list property, use the <managed-property> element. When you configure a managed property for a managed bean, you declare the property name, its class type, and its default value.
Managed beans and managed bean properties can be initialized as lists or maps, provided that the bean or property type is a List or Map, or implements java.util.Map or java.util.List. The default for the values within a list or map is java.lang.String.
Example A-27 Registering Managed Beans in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<!-- This managed bean uses application scope -->
<managed-bean>
<managed-bean-name>resources</managed-bean-name>
<managed-bean-class>
oracle.srdemo.view.resources.ResourceAdapter
</managed-bean-class>
<managed-bean-scope>application</managed-bean-scope>
</managed-bean>
<!-- Page backing beans typically use request scope-->
<managed-bean>
<managed-bean-name>backing_SRCreate</managed-bean-name>
<managed-bean-class>oracle.srdemo.view.backing.SRCreate</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<!--oracle-jdev-comment:managed-bean-jsp-link:1app/SRCreate.jspx-->
<managed-property>
<property-name>bindings</property-name>
<value>#{bindings}</value>
</managed-property>
</managed-bean>
<managed-bean>
<managed-bean-name>backing_SRManage</managed-bean-name>
<managed-bean-class>
oracle.srdemo.view.backing.management.SRManage
</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<!--oracle-jdev-comment:managed-bean-jsp-link:1app/management/SRManage.jspx-->
<managed-property>
<property-name>bindings</property-name>
<value>#{bindings}</value>
</managed-property>
</managed-bean>
<!-- This managed bean uses session scope -->
<managed-bean>
<managed-bean-name>userState</managed-bean-name>
<managed-bean-class>oracle.srdemo.view.UserSystemState</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>
...
</faces-config>
When you create a JSF application using ADF Faces components, besides configuring elements in faces-config.xml you can configure ADF Faces-specific features in the adf-faces-config.xml file. The adf-faces-config.xml file has a simple XML structure that enables you to define element properties using the JSF expression language (EL) or static values.
In JDeveloper when you insert an ADF Faces component into a JSF page for the first time, a starter adf-faces-config.xml file is automatically created for you in the /WEB-INF directory of your ViewController project. Example A-28 shows the starter adf-faces-config.xml file.
Typically you would want to configure the following in adf-faces-config.xml:
Page accessibility levels
Skin family
Time zone
Enhanced debugging
Oracle Help for the Web (OHW) URL
Example A-28 Starter adf-faces-config.xml Created by JDeveloper
<?xml version="1.0" encoding="windows-1252"?> <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config"> <skin-family>oracle</skin-family> </adf-faces-config>
The following JSF tasks are supported by the adf-faces-config.xml file.
To define the level of accessibility support in an application, use <accessibility-mode>. The supported values are:
default—Output supports accessibility features.
inaccessible—Accessibility-specific constructs are removed to optimize output size.
screenReader—Accessibility-specific constructs are added to improve behavior under a screen reader (but may have a negative affect on other users. For example access keys are not displayed if the accessibility mode is set to screen reader mode).
To set the currency code to use for formatting currency fields, and define the separator to use for groups of numbers and the decimal point, use the following elements:
<currency-code>—Defines the default ISO 4217 currency code used by oracle.adf.view.faces.converter.NumberConverter to format currency fields that do not specify a currency code in their own converter.
<number-grouping-separator>—Defines the separator used for groups of numbers (for example, a comma). ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while parsing and formatting.
<decimal-separator>—Defines the separator (e.g., a period or a comma) used for the decimal point. ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while parsing and formatting.
Example A-30 Configuring Currency Code and Separators For Numbers and Decimal Point
<!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>
<!-- Set the number grouping separator to period for German -->
<!-- and comma for all other languages -->
<number-grouping-separator>
#{view.locale.language=='de' ? '.' : ','}
</number-grouping-separator>
<!-- Set the decimal separator to comma for German -->
<!-- and period for all other languages -->
<decimal-separator>
#{view.locale.language=='de' ? ',' : '.'}
</decimal-separator>
ADF Faces enhances debugging output when you set <debug-output> to "true". The following features are then added to debug output:
Automatic indenting.
Comments identifying which component was responsible for a block of HTML.
Detection of unbalanced elements, repeated use of the same attribute in a single element, or other malformed markup problems.
Detection of common HTML errors (for example, <form> tags inside other <form> tags or <tr> or <td> tags used in illegal locations).
ADF Faces validators and converters support client-side validation and conversion as well as server-side validation and conversion. ADF Faces client-side validators and converters work the same way as the server-side validators and converters, except that JavaScript is used on the client. ADF Faces JavaScript-enabled validators and converters run on the client when the form is submitted; thus errors can be caught without a server round trip. You can, however, turn off client-side conversion and validation in your ADF Faces application by setting <client-validation-disabled> to "true".
By default, ADF Faces page rendering direction is based on the language being used by the browser. However, you can explicitly set the default page rendering direction in the <right-to-left> element by using "true" or "false".
By default, ADF Faces uses the Oracle <skin-family> for all pages. You can change this to specify a custom <skin-family>. See also Section A.12.1, "Tasks Supported by adf-faces-skins.xml".
For information about creating custom skins, see Section 14.3, "Using Skins to Change the Look and Feel".
To change the output mode ADF Faces uses, set the <output-mode> element, using one of these values:
default—The default page output mode (usually display).
printable—An output mode suitable for printable pages.
email—An output mode suitable for e-mailing a page's content.
By default ADF Faces sets the maximum number of active processScope instances at 15. Use the <process-scope-lifetime> element to change the number. A static value must be used.
To set the time zone used for processing and displaying dates, and the year offset that should be used for parsing years with only two digits, use the following elements:
<time-zone>—ADF Faces defaults to the time zone used by the client browser. This value is used by oracle.adf.view.faces.converter.DateTimeConverter while converting strings to Date.
<two-digit-year-start>—Defaults to the year 1950 if no value is set. This value is used by oracle.adf.view.faces.converter.DateTimeConverter to convert strings to Date.
Most applications don't need to replace the default UploadedFileProcessor instance provided by ADF Faces, but if your application needs to support uploading of very large files or rely heavily on file uploads, you may wish to replace the default processor with a custom UploadedFileProcessor implementation. For example you could improve performance by using an implementation that immediately stores files in their final destination, instead of requiring ADF Faces to handle temporary storage during the request. To replace the default processor, specify a custom implementation using the <uploaded-file-processor> element.
If you use Oracle Help for the Web (OHW) to provide help in your application, you can attach help content to any JSF tag that accepts a URL. Before you can do this, you must configure your help site URL by using the <oracle-help-servlet-url> element. ADF Faces supports OHW Version 2.0 as well as earlier versions
Use the adfFacesContext.helpTopic EL object to attach help content to the JSF tag. For example:
<h:outputLink value="#{adfFacesContext.helpTopic.someTopicID}">
<h:outputText value="Help!"/>
</h:outputLink>
Once you have configured elements in the adf-faces-config.xml file, you can retrieve property values using one of the following approaches:
Programmatically using the AdfFacesContext class.
The AdfFacesContext class is a context class for all per-request and per-webapp information required by ADF Faces. One instance of the AdfFacesContext class exists per request. Although it is similar to the JSF FacesContext class, the AdfFacesContext class does not extend FacesContext.
To retrieve an ADF Faces configuration property programmatically, first call the static getCurrentInstance() method to get an instance of the AdfFacesContext object, then call the method that retrieves the desired property, as shown in the following example:
// Get an instance of the AdfFacesContext object
AdfFacesContext context = AdfFacesContext.getCurrentInstance();
// Get the time-zone property
TimeZone zone = context.getTimeZone();
// Get the right-to-left property
if (context.isRightToLeft())
{
...
}
For the list of methods to retrieve ADF Faces configuration properties, refer to the Javadoc for oracle.adf.view.faces.context.AdfFacesContext.
Using a JSF EL expression to bind a component attribute value to one of the properties of the ADF Faces implicit object (adfFacesContext).
The AdfFacesContext class contains an EL implicit variable, called adfFacesContext, that exposes the context object properties for use in JSF EL expressions. Using a JSF EL expression, you can bind a component attribute value to one of the properties of the adfFacesContext object. For example in the EL expression below, the <currency-code> property is bound to the currencyCode attribute value of the JSF ConvertNumber component:
<af:outputText>
<f:convertNumber currencyCode="#{adfFacesContext.currencyCode}"/>
</af:outputText>
The adf-faces-skins.xml file is optional; you need this file only if you are using a custom skin for your application. To create the file, simply use a text editor; store the file in /WEB-INF.
You can specify one or more custom skins in adf-faces-skins.xml.
Example A-40 Adf-faces-skins.xml
<?xml version="1.0" encoding="windows-1252"?>
<skins xmlns="http://xmlns.oracle.com/adf/view/faces/skin">
<skin>
<id>purple.desktop</id>
<family>purple</family>
<render-kit-id>oracle.adf.desktop</render-kit-id>
<style-sheet-name>skins/purple/purpleSkin.css</style-sheet-name>
<bundle-name>oracle.adfdemo.view.faces.resource.SkinBundle</bundle-name>
</skin>
</skins>
The value of <family> is what you would specify in adf-faces-config.xml for the <skin-family> element when you wish to configure your application to use a custom skin. See Section A.11.1.6, "Configuring the Skin Family".
For information about creating custom skins, see Section 14.3, "Using Skins to Change the Look and Feel".
