Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-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 ADF Business Components application module as a service interface to JSF web pages.
In an ADF Business Components application, the data control implementation files are contained within the application. The application module and view object XML component descriptor files provide the references for the data control. These files, in conjunction with the bc4j.xcfg
file (see Section A.4) provide the necessary information for the data control.
A workspace that uses ADF Business Components in one project and a non-ADF Business Components data control in another project, like the SRDemoFAQ data control, may have a DataControls.dcx
file, as well as supporting <sessionbeanname>
.xml
and <beanname>
.xml
files. For more information on the non-ADF Business Components data controls, see the Oracle Application Development Framework Developers Guide 10g for J2EE Developers.
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 ADF application module as a service interface to ADF Business Components. 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 application module 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 bc4j.xcfg
file contains information about application module names and the runtime parameters the user has configured. A sample bc4j.xcfg
from the SRDemo application follows:
Example A-1 bc4j.xcfg
<?xml version = '1.0' encoding = 'UTF-8'?> <BC4JConfig> <AppModuleConfigBag> <AppModuleConfig name="SRServiceLocal"> <DeployPlatform>LOCAL</DeployPlatform> <JDBCDataSource>java:comp/env/jdbc/SRDemoDS</JDBCDataSource> <jbo.project>DataModel</jbo.project> <jbo.locking.mode>optimistic</jbo.locking.mode> <AppModuleJndiName>oracle.srdemo.model.SRService</AppModuleJndiName> <jbo.security.enforce>Must</jbo.security.enforce> <java.naming.factory.initial>oracle.jbo.common.JboInitialContextFactory</java.naming.factory.initial> <ApplicationName>oracle.srdemo.model.SRService</ApplicationName> <jbo.server.internal_connection>java:comp/env/jdbc/SRDemoCoreDS</jbo.server.internal_connection> </AppModuleConfig> <AppModuleConfig name="SRServiceLocalTesting"> <DeployPlatform>LOCAL</DeployPlatform> <JDBCName>SRDemo</JDBCName> <jbo.project>DataModel</jbo.project> <AppModuleJndiName>oracle.srdemo.model.SRService</AppModuleJndiName> <jbo.locking.mode>optimistic</jbo.locking.mode> <jbo.security.enforce>Must</jbo.security.enforce> <java.naming.factory.initial>oracle.jbo.common.JboInitialContextFactory</java.naming.factory.initial> <ApplicationName>oracle.srdemo.model.SRService</ApplicationName> </AppModuleConfig> </AppModuleConfigBag> <ConnectionDefinition name="SRDemo"> <ENTRY name="JDBC_PORT" value="1521"/> <ENTRY name="ConnectionType" value="JDBC"/> <ENTRY name="HOSTNAME" value="bordello.us.oracle.com"/> <ENTRY name="DeployPassword" value="true"/> <ENTRY name="user" value="SRDemo"/> <ENTRY name="ConnectionName" value="SRDemo"/> <ENTRY name="SID" value="bordello"/> <ENTRY name="password"> <![CDATA[{904}05EF4D2067E3477EBE0CF3865966EB7C5F]]> </ENTRY> <ENTRY name="JdbcDriver" value="oracle.jdbc.OracleDriver"/> <ENTRY name="ORACLE_JDBC_TYPE" value="thin"/> <ENTRY name="DeployPassword" value="true"/> </ConnectionDefinition> </BC4JConfig>
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-3 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-1 describes the attributes of the DataBindings.cpx elements.
Table A-1 Attributes of the DataBindings.cpx File Elements
Example A-2 shows the syntax for the DataBindings.cpx file in the SR Demo application. The data controls are named by the id="<name>". The combination of the Package attribute and the Configuration attribute are used to locate the bc4j.xcfg file in the "./common" subdirectory of the indicated package. The configuration contains the information of the application module name and all the runtime parameters the user has configured.
Example A-2 DataBindings.cpx file
<dataControlUsages> <dc id="SRDemoFAQ" path="oracle.srdemo.faq.SRDemoFAQ"/> <BC4JDataControl id="SRService" Package="oracle.srdemo.model" FactoryClass="oracle.adf.model.bc4j.DataControlFactoryImpl" SupportsTransactions="true" SupportsFindMode="true" SupportsRangesize="true" SupportsResetState="true" SupportsSortCollection="true" Configuration="SRServiceLocal" syncMode="Immediate" xmlns="http://xmlns.oracle.com/adfm/datacontrol"/> </dataControlUsages>
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-3 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-3 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 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-2 describes the attributes of the toplevel <pageDefinition> element.
Table A-2 Attributes of the PageDef.xml File <pageDefinition> Element
Table A-3 describes the attributes of the child element of <parameters>.
Table A-3 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-4 describes the attributes of the PageDef.xml <executables> elements.
Table A-4 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-5 describes the attributes of the PageDef.xml <bindings> element.
Table A-5 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. |
|
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. |
|
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 attributes of the LoggedInUser view object from the Data Control Palette, SRService node, into your open JSP page.
Example A-4 PageDef for Attributes of LoggedInUser View Object
<?xml version="1.0" encoding="UTF-8" ?> <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel" version="10.1.3.35.65" id="app_SRCreateConfirmPageDef" Package="oracle.srdemo.view.pageDefs"> <parameters/> <executables> <iterator id="GlobalsIterator" RangeSize="10" Binds="Globals" DataControl="SRService"/> <iterator id="LoggedInUserIterator" RangeSize="10" Binds="LoggedInUser" DataControl="SRService"/> </executables> <bindings> <attributeValues IterBinding="GlobalsIterator" id="ProblemDescription"> <AttrNames> <Item Value="ProblemDescription"/> </AttrNames> </attributeValues> <attributeValues IterBinding="GlobalsIterator" id="ProductId"> <AttrNames> <Item Value="ProductId"/> </AttrNames> </attributeValues> <attributeValues IterBinding="GlobalsIterator" id="ProductName"> <AttrNames> <Item Value="ProductName"/> </AttrNames> </attributeValues> <attributeValues id="FirstName" IterBinding="LoggedInUserIterator"> <AttrNames> <Item Value="FirstName"/> </AttrNames> </attributeValues> <attributeValues id="LastName" IterBinding="LoggedInUserIterator"> <AttrNames> <Item Value="LastName"/> </AttrNames> </attributeValues> ... </bindings> </pageDefinition>
This is the page definition file that's created when you drop the ServiceRequestsByStatus node from the Data Control Palette, SRService node, into your open JSP page. This one produces the entire view object.
Example A-5 PageDef for the Entire View Object
<?xml version="1.0" encoding="UTF-8" ?> <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel" version="10.1.3.35.65" id="app_SRListPageDef" Package="oracle.srdemo.view.pageDefs" EnableTokenValidation="false"> <parameters/> <executables> <iterator id="ServiceRequestsByStatusIterator" RangeSize="10" Binds="ServiceRequestsByStatus" DataControl="SRService"/> </executables> <bindings> <table id="LoggedInUserServiceRequests" IterBinding="ServiceRequestsByStatusIterator"> <AttrNames> <Item Value="SvrId"/> <Item Value="Status"/> <Item Value="RequestDate"/> <Item Value="ProblemDescription"/> <Item Value="ProdId"/> <Item Value="CreatedBy"/> <Item Value="AssignedTo"/> <Item Value="AssignedDate"/> </AttrNames> </table> <action id="setCurrentRowWithKey" IterBinding="ServiceRequestsByStatusIterator" InstanceName="SRService.ServiceRequestsByStatus" DataControl="SRService" RequiresUpdateModel="false" Action="96"> <NamedData NDName="rowKey" NDValue="${row.rowKeyStr}" NDType="java.lang.String"/> </action> <action id="ExecuteWithParams" IterBinding="ServiceRequestsByStatusIterator" InstanceName="SRService.ServiceRequestsByStatus" DataControl="SRService" RequiresUpdateModel="true" Action="95"> <NamedData NDName="StatusCode" NDValue="${userState.listMode}" NDType="java.lang.String"/> </action> </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-6 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-7 shows part of a web.xml
file that contains state-saving parameters.
Example A-7 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-8 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-9 shows part of a web.xml
file that contains debugging parameters.
Example A-9 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-10 shows part of a web.xml
file that contains file upload parameters.
Example A-10 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 19.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 12.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-11 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 12, "Displaying Data on a Page".
Example A-11 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-12). 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.8.1.1.
Redirect the log output to a location, like a file, in addition to the default Log window in JDeveloper. See Section A.8.1.2.
Change the directory path that determines where your log file resides. See Section A.8.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-13). 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 24.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-14). 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-15). 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 11.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.9.1.1, Section A.9.1.3. and Section A.9.1.4.
Page-to-page navigation rules. See Section A.9.1.5.
Custom validators and converters. See Section A.9.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.9.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-16).
Example A-16 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 13.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-17 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 20.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-18). The SRDemo application uses a resource properties file to hold the strings for the UI.
Example A-18 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 22.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-19).
Example A-19 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>
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-20). The corresponding code for the navigation case within the navigation rule for the SRList page is shown in Example A-21.
Example A-20 Action Outcome String Defined on View Button
<af:commandButton text="#{res['srlist.buttonbar.view']}"
action="View"/>
Example A-21 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 16, "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-22). 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-22 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-23). 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-23 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-24 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-24 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-26 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.11.1, "Tasks Supported by adf-faces-skins.xml".
For information about creating custom skins, see Section 22.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-36 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.10.1.6, "Configuring the Skin Family".
For information about creating custom skins, see Section 22.3, "Using Skins to Change the Look and Feel".