A ADF Faces Configuration

This appendix describes how to configure JSF and ADF Faces features in various XML configuration files, as well as how to retrieve ADF Faces configuration values using the RequestContext API and how to use JavaScript partitioning.

This chapter includes the following sections:

A.1 Introduction to Configuring ADF Faces

A JSF web application requires a specific set of configuration files, namely, web.xml and faces-config.xml. ADF applications also store configuration information in the adf-config.xml and adf-settings.xml files. Because ADF Faces shares the same code base with MyFaces Trinidad, a JSF application that uses ADF Faces components for the UI also must include a trinidad-config.xml file, and optionally a trinidad-skins.xml file. For more information about the relationship between Trinidad and ADF Faces, see Chapter 1, "Introduction to ADF Faces Rich Client."

A.2 Configuration in web.xml

Part of a JSF application's configuration is determined by the contents of its Java EE application deployment descriptor, web.xml. The web.xml file, which is located in the /WEB-INF directory, defines everything about your application that a server needs to know (except the root context path, which is automatically assigned for you in JDeveloper, or assigned by the system administrator when the application is deployed). Typical runtime settings in the web.xmlfile include initialization parameters, custom tag library location, and security settings.

The following is configured in the web.xmlfile for all applications that use ADF Faces:

  • Context parameter javax.faces.STATE_SAVING_METHOD set to client

  • MyFaces Trinidad filter and mapping

  • MyFacesTrinidad resource servlet and mapping

  • JSF servlet and mapping

Note:

JDeveloper automatically adds the necessary ADF Faces configurations to the web.xml file for you the first time you use an ADF Faces component in an application.

For more information about the required elements, see Section A.2.2, "What You May Need to Know About Required Elements in web.xml."

For information about optional configuration elements in web.xml related to ADF Faces, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml."

For information about configuring web.xml outside of ADF Faces, see Developing Web Applications, Servlets, and JSPs for Oracle.

A.2.1 How to Configure for JSF and ADF Faces in web.xml

In JDeveloper, when you create a project that uses JSF technology, a starter web.xml file with default servlet and mapping elements is created for you in the /WEB-INF directory.

When you use ADF Faces components in a project (that is, a component tag is used on a page rather than just importing the library), in addition to default JSF configuration elements, JDeveloper also automatically adds the following to the web.xml file for you:

  • Configuration elements that are related to MyFaces Trinidad filter and MyFaces Trinidad resource servlet

  • Context parameter javax.faces.STATE_SAVING_METHOD with the value of client

When you elect to use JSP fragments in the application, JDeveloper automatically adds a JSP configuration element for recognizing and interpreting .jsff files in the application.

Example A-1 shows the web.xml file with the default elements that JDeveloper adds for you when you use JSF and ADF Faces and .jsff files.

For information about the web.xml configuration elements needed for working with JSF and ADF Faces, see Section A.2.2, "What You May Need to Know About Required Elements in web.xml."

Example A-1 Generated web.xml File

<?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/javaee
         http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5"
         xmlns="http://java.sun.com/xml/ns/javaee">
  <description>Empty web.xml file for Web Application</description>
  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>35</session-timeout>
  </session-config>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>txt</extension>
    <mime-type>text/plain</mime-type>
  </mime-mapping>
</web-app>

Note:

When you use ADF data controls to build databound web pages, the ADF binding filter and a servlet context parameter for the application binding container are added to the web.xml file.

Configuration options for ADF Faces are set in the web.xml file using <context-param> elements.

To add ADF Faces configuration elements in web.xml:

  1. In the Application Navigator, double-click web.xml to open the file.

    By default, JDeveloper opens the web.xml file in the overview editor, as indicated by the active Overview tab at the bottom of the editor window.

    When you use the overview editor to add or edit entries declaratively, JDeveloper automatically updates the web.xml file for you.

  2. To edit the XML code directly in the web.xml file, click Source at the bottom of the editor window.

    When you edit elements in the XML editor, JDeveloper automatically reflects the changes in the overview editor.

For a list of context parameters you can add, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml."

A.2.2 What You May Need to Know About Required Elements in web.xml

The required, application-wide configuration elements for JSF and ADF Faces in the web.xml file are:

  • Context parameter javax.faces.STATE_SAVING_METHOD: Specifies where to store the application's view state. By default this value is client, which stores the application's view state on the browser client. When set to client, ADF Faces then automatically uses token-based, client-side state saving. You can specify the number of tokens to use instead of using the default number of 15. For more information about state-saving context parameters, see Section A.2.3, "What You May Need to Know About ADF Faces Context Parameters in web.xml."

  • MyFaces Trinidad filter and mapping: Installs the MyFaces Trinidad filter org.apache.myfaces.trinidad.webapp.TrinidadFilter, which is a servlet filter that ensures ADF Faces is properly initialized, in part by establishing a RequestContext object. TrinidadFilter also processes file uploads. The filter mapping maps the JSF servlet's symbolic name to the MyFaces Trinidad filter. The forward and request dispatchers are needed for any other filter that is forwarding to the MyFaces Trinidad filter.

    Tip:

    If you use multiple filters in your application, ensure that they are listed in the web.xml file in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.

  • MyFaces Trinidad resource servlet and mapping: Installs the MyFaces Trinidad resource servlet org.apache.myfaces.trinidad.webapp.ResourceServlet, which serves up web application resources (images, style sheets, JavaScript libraries) by delegating to a resource loader. The servlet mapping maps the MyFaces Trinidad resource servlet's symbolic name to the URL pattern. By default, JDeveloper uses /adf/* for MyFaces Trinidad Core, and /afr/* for ADF Faces.

  • JSF servlet and mapping (added when creating a JSF page or using a template with ADF Faces components): The JSF servlet javax.faces.webapp.FacesServlet manages the request processing lifecycle for web applications that utilize JSF to construct the user interface. The mapping maps the JSF servlet's symbolic name to the URL pattern, which can use either a path prefix or an extension suffix pattern.

    By default JDeveloper uses the path prefix /faces/*, as shown in the following code:

    <servlet-mapping>
  <servlet-name>Faces Servlet</servlet-name>
  <url-pattern>/faces/*</url-pattern>
</servlet-mapping>

    For example, if your web page is index.jspx, this means that when the URL http://localhost:8080/MyDemo/faces/index.jspx is issued, the URL activates the JSF servlet, which strips off the faces prefix and loads the file /MyDemo/index.jspx.

A.2.3 What You May Need to Know About ADF Faces Context Parameters in web.xml

ADF Faces configuration options are defined in the web.xml file using <context-param> elements. For example:

<context-param>
  <param-name>oracle.adf.view.rich.LOGGER_LEVEL</param-name>
  <param-value>ALL</param-value>
</context-param>

The following context parameters are supported for ADF Faces.

A.2.3.1 State Saving

You can specify the following state-saving context parameters:

  • org.apache.myfaces.trinidad.CLIENT_STATE_METHOD: Specifies the type of client-side state saving to use when client-side state saving is enabled by using javax.faces.STATE_SAVING_METHOD. The values for CLIENT_STATE_METHOD 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 object, is stored on the client. This enables ADF Faces to disambiguate the same page appearing multiple times. Failover is supported.

    • all: Stores all state information on the client in a (potentially large) hidden form field. It is useful for developers who do not want to use HttpSession.

    Performance Tip:

    Because of the potential size of storing all state information, it is recommended that you set client-state saving to token.

  • org.apache.myfaces.trinidad.CLIENT_STATE_MAX_TOKENS: Specifies how many tokens should be stored at any one time per user, when token-based client-side state saving is enabled. The default is 15. When the number of tokens 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 are building HTML applications that rely heavily on frames, you would want to increase this value.

  • org.apache.myfaces.trinidad.COMPRESS_VIEW_STATE: Specifies whether or not to globally compress state saving on the session. Each user session can have multiple pageState objects that heavily consume live memory and thereby impact performance. This overhead can become a much bigger issue in clustering when session replication occurs. The default is off.

  • org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE: Enables the Application View Cache (AVC), which can improve scalability by caching the state for the initial renders of the page's UI at an application scope. However, every page in the application must by analyzed for support in the AVC to avoid potential problems with debugging in an unexpected state and information leakage between users. Additionally, development is more difficult since page updates are not noticed until the server is restarted, and although initial render performance is enhanced, session size is not.

    CAUTION:

    The Application View Cache is not supported for this release. The feature does not work for any page where the rendering of the component tree causes the structure of the component tree to change temporarily. Since this is often the case, USE_APPLICATION_VIEW_CACHE should not be used.

A.2.3.2 Debugging

You can specify the following debugging context parameters:

  • org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT: ADF Faces, by default, obfuscates the JavaScript it delivers to the client, stripping comments and whitespace at the same time. This dramatically reduces the size of the ADF Faces JavaScript download, but it 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.

  • org.apache.myfaces.trinidad.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 CSS files, and discard the saved state when the files change.

    Performance Tip:

    When set to true, this CHECK_FILE_MODIFICATION parameter adds overhead that should be avoided when your application is deployed. Set to false when deploying your application to a runtime environment.

  • oracle.adf.view.rich.LOGGER_LEVEL: This parameter enables JavaScript logging when the default render kit is oracle.adf.rich. The default is OFF. If you wish to turn on JavaScript logging, use one of the following levels: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, and ALL.

    Performance Tip:

    JavaScript logging will affect performance. Set this value to OFF in a runtime environment.

A.2.3.3 File Uploading

You can specify the following file upload context parameters:

  • org.apache.myfaces.trinidad.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.

  • org.apache.myfaces.trinidad.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.

  • org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR: Specifies the directory where temporary files are to be stored during file uploading. The default is the user's temporary directory.

Note:

The file upload initialization parameters are processed by the default UploadedFileProcessor only. If you replace the default processor with a custom UploadedFileProcessor implementation, the parameters are not processed.

A.2.3.4 Resource Debug Mode

You can specify the following:

  • org.apache.myfaces.trinidad.resource.DEBUG: Specifies whether or not resource debug mode is enabled. The default is false. Set to true if you want to enable resource debug mode. When enabled, ADF Faces sets HTTP response headers to let the browser know that resources (such as JavaScript libraries, images, and CSS) cannot be cached.

    Tip:

    After turning on resource debug mode, clear your browser cache to force the browser to load the latest versions of the resources.

    Performance Tip:

    In a production environment, this parameter should be removed or set to false.

A.2.3.5 Assertions

You can specify whether or not assertions are used within ADF Faces using the oracle.adf.view.rich.ASSERT_ENABLED parameter. The default is false. Set to true to turn on assertions.

Performance Tip:

Assertions will affect performance. Set this value to false in a runtime environment.

A.2.3.6 Enabling the Application for Real User Experience Insight

Real User Experience Insight (RUEI) is a web-based utility to report on real-user traffic requested by, and generated from, your network. It measures the response times of pages and transactions at the most critical points in the network infrastructure. Session diagnostics allow you to perform root-cause analysis.

RUEI enables you to view server and network times based on the real-user experience, to monitor your Key Performance Indicators (KPIs) and Service Level Agreements (SLAs), and to trigger alert notifications on incidents that violate their defined targets. You can implement checks on page content, site errors, and the functional requirements of transactions. Using this information, you can verify your business and technical operations. You can also set custom alerts on the availability, throughput, and traffic of all items identified in RUEI.

Specify whether or not RUEI is enabled for oracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDER by adding the parameter to the web.xml file and setting the value to true. By default this parameter is not set or is set to false.

For more information about RUEI, see "Enabling the Application for Real User Experience Insight" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

A.2.3.7 Facelets Support

Specify the following if you intend to use Facelets with ADF Faces:

  • org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER: Install FaceletsViewHandler by setting the parameter value to com.sun.facelets.FaceletViewHandler

  • javax.faces.DEFAULT_SUFFIX: Use .xhtml as the file extension for documents that use Facelets by setting the parameter value to .xhtml.

A.2.3.8 Dialog Prefix

To change the prefix for launching dialogs, set the org.apache.myfaces.trinidad.DIALOG_NAVIGATION_PREFIX parameter.

The default is dialog:, which is used in the beginning of the outcome of a JSF navigation rule that launches a dialog (for example, dialog:error).

A.2.3.9 Compression for CSS Class Names

You can set the org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION parameter to determine compression of the CSS class names for skinning keys.

The default is false. Set to true if you want to disable the compression.

Performance Tip:

Compression will affect performance. In a production environment, set this parameter to false.

A.2.3.10 Test Automation

When you set the oracle.adf.view.rich.automation.ENABLED parameter to true and when the component ID attribute is null, the component testId attribute is used during automated testing to ensure that the ID is not null. The testId is an attribute only on the tag. It is not part of the Java component API. Note this context parameter only enables the infrastructure for test automation; it does not initiate testing itself, which requires a tool such as the open source Selenium IDE.

Caution:

When the test automation context parameter is set to true, the oracle.adf.view.rich.security.FRAME_BUSTING context parameter behaves as though it were set to never. The security consequence of disabling framebusting is that pages of your application will become vulnerable to clickjacking from malicious web sites. For this reason, restrict the use of the test automation to development or staging environments and never enable test automation in a production environment. For more information, see Section A.2.3.15, "Framebusting."

Enabling test automation also enables assertions in the running application. If your application exhibits unexpected component behavior and you begin to see new assertion failed errors, you will need to examine the implementation details of your application components. For example, it is not uncommon to discover issues related to popup dialogs, such as user actions that are no longer responded to.

Here are known coding errors that will produce assertion failed errors only after test automation is enabled:

  • Your component references an ADF iterator binding that no longer exists in the page definition file. When assertions are not enabled, this error is silent and the component referencing the missing iterator simply does not render.

  • Your component is a partial trigger component that is defined not to render (has the attribute setting rendered="false"). For example, this use of the rendered attribute causes an assertion failed error:

    <af:commandButton  id="hiddenBtn" rendered="false" text="Test"/>
<af:table var="row" id="t1"  partialTriggers="::hiddenBtn">

    The workaround for this error is to use the attribute setting visible="false" and not rendered="false".

  • Your components were formed with a nesting hierarchy that prevents events from reaching the proper component handlers. For example, this nesting is incorrect:

    <af:commandLink
    <af:showPopupBehavior
        <af:image
        <af:clientListener

    and should be rewritten as:

    <af:commandLink
    <af:image
       <af:showPopupBehavior
       <af:clientListener

Note that system administrators can enable test automation at the level of standalone Oracle WebLogic Server by starting the server with the command line flag -Doracle.adf.view.rich.automation.ENABLED=true. Running your application in an application server instance with test automation enabled overrides the web.xml file context parameter setting of the deployed application.

A.2.3.11 UIViewRoot Caching

Use the org.apache.myfaces.trinidad.CACHE_VIEW_ROOT parameter to enable or disable UIViewRoot caching. When token client-side state saving is enabled, MyFaces Trinidad can apply an additional optimization by caching an entire UIViewRoot tree with each token. (Note that this does not affect thread safety or session failover.) This is a major optimization for AJAX-intensive systems, as postbacks can be processed far more rapidly without the need to reinstantiate the UIViewRoot tree.

You set the org.apache.myfaces.trinidad.CACHE_VIEW_ROOT parameter to true to enable caching. This is the default. Set the parameter to false to disable caching.

Note:

This type of caching is known to interfere with some other JSF technologies. In particular, the Apache MyFaces Tomahawk saveState component does not work, and template text in Facelets may appear in duplicate.

A.2.3.12 Themes and Tonal Styles

Use the oracle.adf.view.rich.tonalstyles.ENABLED parameter to turn the use of tonal styles off or on. While the tonal style classes .AFDarkTone, .AFMediumTone, .AFLightTone and .AFDefaultTone are still available for the purpose of backward compatibility, themes are provided as a replacement style. Themes are easier to author than tonal styles; they rely on fewer selectors, and they avoid CSS containment selectors. For this reason they are less prone to bugs. Due to the limitation on the number of selectors in one CSS file, both tonal styles and themes cannot be supported in the same application. Set to false to disable tonal styles.

A.2.3.13 Partial Page Navigation

Use the oracle.adf.view.rich.pprNavigation.OPTIONS parameter to turn partial page navigation on and off. By default, the value is off. Partial page navigation uses the same base page throughout the application, and simply replaces the body content of the page with each navigation. This processing results in better performance because JavaScript libraries and style sheets do not need to be reloaded with each new page. For more information, see Section 7.4, "Using Partial Page Navigation."

Valid values are:

  • on: PPR navigation is turned on for the application.

    Note:

    If you set the parameter to on, then you need to set the partialSubmit attribute to true for any command components involved in navigation. For more information about partialSubmit, see Section 5.1.1, "Events and Partial Page Rendering."

  • off: PPR navigation is turned off for the application.

  • onWithForcePPR: When an action on a command component results in navigation, the action will always be delivered using PPR, as if the component had partialSubmit set to true. For more information about partialSubmit, see Section 5.1.1, "Events and Partial Page Rendering." If the component already has partialSubmit set to true, the framework does nothing. If partialSubmit is not set to true, the entire document is refreshed to ensure that old page refresh behavior is preserved. The entire document is also refreshed if the action component does not contain navigation.

A.2.3.14 JavaScript Partitioning

Use the oracle.adf.view.rich.libraryPartitioning.ENABLED parameter to turn JavaScript partitioning on and off. By default, the value is true (enabled). JavaScript partitioning allows a page to download only the JavaScript needed by client components for that page.

Valid values are:

  • true: JavaScript partitioning is enabled (the default).

  • false: JavaScript partitioning is disabled.

For more information about using and configuring JavaScript partitioning, see Section A.9, "Using JavaScript Library Partitioning."

A.2.3.15 Framebusting

Use the org.apache.myfaces.trinidad.security.FRAME_BUSTING context parameter to use framebusting in your application. Framebusting is a way to prevent clickjacking, which occurs when a malicious web site pulls a page originating from another domain into a frame and overlays it with a counterfeit page, allowing only portions of the original, or clickjacked, page (for example, a button) to display. When users click the button, they in fact are clicking a button on the clickjacked page, causing unexpected results.

For example, say your application is a web-based email application that resides in DomainA, and a web site in DomainB clickjacks your page by creating a page with an IFrame that points to a page in your email application at DomainA. When the two pages are combined, the page from DomainB covers most of your page in the IFrame, and exposes only a button on your page that deletes all email for the account. Users, not realizing they are actually in the email application, may click the button and inadvertently delete all their email.

Framebusting prevents clickjacking by using the following JavaScript to block the application's pages from running in frames:

top.location.href = location.href;

If you configure your application to use framebusting by setting the parameter to always, then whenever a page tries to run in a frame, an alert is shown to the user that the page is being redirected, the JavaScript code is run to define the page as topmost, and the page is disallowed to run in the frame.

If your application needs to use frames, you can set the parameter value to differentOrigin. This setting causes framebusting to occur only if the frame has the same origin as the parent page. This is the default setting.

Note:

The origin of a page is defined using the domain name, application layer protocol, and in most browsers, TCP port of the HTML document running the script. Pages are considered to originate from the same domain if and only if all these values are exactly the same.

For example, say you have a page named DomainApage1 in your application that uses a frame to include the page DomainApage2. Say the external DomainBpage1 tries to clickjack the page DomainApage1. The result would be the following window hierarchy:

  • DomainBpage1

    • DomainApage1

      • DomainApage2

If the application has framebusting set to be differentOrigin, then the framework walks the parent window hierarchy to determine whether any ancestor windows originate from a different domain. Because DoaminBpage1 originates from a different domain, the framebusting JavaScript code will run for the DomainApage1 page, causing it to become the top-level window. And because DomainApage2 originates from the same domain as DomainApage1, it will be allowed to run in the frame.

Valid values are:

  • always: The page will show an error and redirect whenever it attempts to run in a frame.

  • differentOrigin: The page will show an error and redirect only when it attempts to run in a frame on a page that originates in a different domain (the default).

  • never: The page can run in any frame on any originating domain.

    Note:

    This context parameter is ignored and will behave as if it were set to never when either of the following context parameters is set to true:

    • org.apache.myfaces.trinidad.util.
      ExternalContextUtils.isPortlet

    • oracle.adf.view.rich.automation.ENABLED

A.2.3.16 Version Number Information

Use the oracle.adf.view.rich.versionString.HIDDEN parameter to determine whether or not to display version information an a page's HTML. When the parameter is set to false, the HTML of an ADF Faces page contains information about the version of ADF Faces and other components used to create the page as shown in Example A-2.

Example A-2 Version Information in the HTML

</body><!--Created by Oracle ADF (ADF Faces API -
11.1.1.4.0/ADF Faces Implementation - 11.1.1.4.0, RCF-revision: 39851 (branch:
faces-1003-11.1.1.4.0, plugins: 1.2.3), Trinidad-revision: 1051544 (branch:
1.2.12.3-branch, plugins: 1.2.10), build: adf-faces-rt_101221_0830, libNum:
0355 powered by JavaServer Faces API 1.2 Sun Sep 26 03:21:43 EDT 2010 
(1.2)), accessibility (mode:null, contrast:standard, size:medium),
skin:customSkin.desktop (CustomSkin)--></html>

When you create a new application, the parameter is set to true. It should also be set to true in a production environment. Set the parameter to false to display this version information for debugging information.

Note:

In a production environment, set this parameter to true to avoid security issues. It should be set to false only in a development environment for debugging purposes.

A.2.3.17 Suppressing Auto-Generated Component IDs

Use the oracle.adf.view.rich.SUPPRESS_IDS context parameter set to auto when programmatically adding an af:outputText or af:outputFormatted component as a partial target, that is, through a call to addPartialTarget().

By default, this parameter is set to explicit, thereby reducing content size by suppressing both auto-generated and explicitly set component IDs except when either of the following is true:

  • The component partialTriggers attribute is set

  • The clientComponent attribute is set to true

In the case of a call to addPartialTarget(), the partialTriggers attribute is not set and the partial page render will not succeed. You can set the parameter to auto to suppress only auto-generated component IDs for these components.

A.2.3.18 ADF Faces Caching Filter

The ADF Faces Caching Filter (ACF) is a Java EE Servlet filter that can be used to accelerate web application performance by enabling the caching (and/or compression) of static application objects such as images, style sheets, and documents like .pdf and .zip files. These objects are cached in an external web cache such as Oracle Web Cache, Oracle Traffic Director, or in the browser cache. The cacheability of content is largely determined through URL-based rules defined by the web cache administrator. Using ACF, the ADF application administrator or author can define caching rules directly in the adf-config.xml file. For more information about defining caching rules, see Section A.4.2, "Defining Caching Rules for ADF Faces Caching Filter."

ADF Faces tag library JARs include default caching rules for common resource types, such as .js, .css, and image file types. These fixed rules are defined in the adf-settings.xml file, and cannot be changed during or after application deployment. In the case of conflicting rules, caching rules defined by the application developer in adf-config.xml will take precedence. For more information about settings in adf-settings.xml, see Section A.5.2, "What You May Need to Know About Elements in adf-settings.xml."

Oracle Web Cache and Oracle Traffic Director must be configured by the web cache administrator to route all traffic to the web application through the web cache. In the absence of the installation of Oracle Web Cache or Oracle Traffic Director, the caching rules defined in adf-config.xml will be applied for caching in the browser if the <agent-caching> child element is set to true. To configure the ACF to be in the URL request path, add the following servlet filter definitions in the web.xml file:

  • ACF filter class: Specify the class to perform URL matching to rules defined in adf-config.xml

  • ACF filter mapping: Define the URL patterns to match with the caching rules defined in adf-config.xml

Example A-3 shows a sample ACF servlet definition.

Example A-3 ACF Servlet Definition

<!- Servlet Filter definition ->x
<filter>
  <filter-name>ACF</filter-name>
  <filter-class>oracle.adf.view.rich.webapp.AdfFacesCachingFilter</filter-class>
</filter>
<!- servlet filter mapping definition ->
<filter-mapping>
  <filter-name>ACF</filter-name>
  <url-pattern>*</url-pattern>
</filter-mapping>

Note:

The ACF servlet filter must be the first filter in the chain of filters defined for the application.

A.2.3.19 Configuring Native Browser Context Menus for Command Links

Use the oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSION parameter to enable or disable the end user´s browser to supply a context menu for ADF Faces command components that render a link. The context menu may present menu options that invoke a different action (for example, open a link in a new window) to that specified by the command component.

By default, this parameter is set to yes, thereby suppressing the rendering of a context menu for ADF Faces command components. By setting the parameter to no, you can disable this suppression and allow the native browser context menu to appear. For information about the ADF Faces command components for which you can configure this functionality, see Chapter 18, "Configuring a Browser's Context Menu for Command Links."

A.2.3.20 Internet Explorer Compatibility View Mode

Running ADF Faces applications in the compatibility mode of Microsoft Internet Explorer can cause unpredictable behavior. By default, when a user accesses an ADF Faces application and has their Internet Explorer browser set to compatibility mode, ADF Faces displays an alert asking the user to disable that mode.

Set the oracle.adf.view.rich.HIDE_UNSUPPORTED_BROWSER_ALERTS context parameter to IECompatibilityModes to hide these messages from the user.

Note:

Even when these messages are hidden, a warning-level log message is still reported to the JavaScript log, when the oracle.adf.view.rich.LOGGER_LEVEL parameter is set to WARNING or more verbose. For more information, see Section A.2.3.2, "Debugging."

A.2.3.21 Session Timeout Warning

When a request is sent to the server, a session timeout value is written to the page and the session timeout warning interval is defined by the context parameter oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_TIMEOUT. The user is given the opportunity to extend the session in a warning dialog, and a notification is sent when the session has expired and the page is refreshed. Depending on the application security configuration, the user may be redirected to the log in page when the session expires.

Use the oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_TIMEOUT context parameter to set the number of seconds prior to the session time out when a warning dialog is displayed. If the value of WARNING_BEFORE_TIMEOUT is less than 120 seconds, if client state saving is used for the page, or if the session has been invalidated, the feature is disabled. The session time-out value it taken directly from the session.

Example A-4 shows configuration of the warning dialog to display at 120 seconds before the time-out of the session.

Example A-4 Configuration of Session Time-out Warning

<context-param>
    <param-name>oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_
        TIMEOUT</param-name>
    <param-value>120</param-value>
</context-param>

The default value of this parameter is 120 seconds. To prevent notification of the user too frequently when the session time-out is set too short, the actual value of WARNING_BEFORE_TIMEOUT is determined dynamically, where the session time-out must be more than 2 minutes or the feature is disabled.

A.2.3.22 JSP Tag Execution in HTTP Streaming

Use the oracle.adf.view.rich.tag.SKIP_EXECUTION parameter to enable or disable JSP tag execution in HTTP streaming requests during the processing of JSP pages. Processing of facelets is not included.

By default, this parameter is set to streaming, where JSP tag execution is skipped during streaming requests. You can set the parameter to off to execute JSP tags per each request in cases where tag execution is needed by streaming requests.

A.2.3.23 Splash Screen

Use the oracle.adf.view.rich.SPLASH_SCREEN parameter to enable or disable the splash screen that by default, displays as the page is loading, as shown in Figure A-1.

Figure A-1

spinning O splash screen

By default, this parameter is set to on. You can set it to off, so that the splash screen will not display.

A.2.3.24 Graph and Gauge Image Format

Add the oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT parameter to change the default output format to HTML5 for graph and gauge components.

<context-param>
  <param-name>oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT</param-name>
  <param-value>HTML5</param-value>
</context-param>

By default, this parameter is absent. Valid values are HTML5 and FLASH.

A.2.3.25 Geometry Management for Layout and Table Components

Add the oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS parameter when you want to globally control how certain layout components and tables handle being stretched.

Whether or not certain layout components (af:decorativeBox, af:panelAccordion, af:panelDashboard, af:panelStretchLayout, af:panelSplitter, af:panelTabbed) can be stretched is based on the value of the dimensionsFrom attribute. The default setting for these components is parent, which means the size of the component is determined in the following order:

  • From the inlineStyle attribute.

  • If no value exists for inlineStyle, then the size is determined by the parent container (that is, the component will stretch).

  • If the parent container is not configured or not able to stretch its children, the size will be determined by the skin.

However, if you always want these components to use auto as the value for the dimensionsFrom attribute (that is, the component stretches if the parent component allows stretching of its child, otherwise the size of the component is based on its child components), you can set the oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS parameter to auto. You can then use the dimensionsFrom attribute on an individual component to override this setting.

Similarly for tables, the autoHeightRows attribute determines whether or not the table will stretch. By default it is set to -1, which means the table size is based on the number of rows fetched. However, if the oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS parameter is set to auto, the table will stretch when the parent component allows stretching, and otherwise will be the number of rows determined by the table's fetchSize attribute.

By default, the oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS parameter is set to legacy, which means the components will use their standard default values.

Set oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS parameter to auto when you want both layout components and tables to always stretch when the parent component allows stretching.

A.2.4 What You May Need to Know About Other Context Parameters in web.xml

Other optional, application-wide context parameters are:

  • javax.faces.CONFIG_FILE: Specifies paths to JSF application configuration resource files. Use a comma-separated list of application-context relative paths for the value, as shown in the following code. Set this parameter if you use more than one JSF configuration file in your application.

    <context-param>
  <param-name>javax.faces.CONFIG_FILES</param-name>
  <param-value>
   /WEB-INF/faces-config1.xml,/WEB-INF/faces-config2.xml
  </param-value>
</context-param>

  • javax.faces.DEFAULT_SUFFIX: Specifies a file extension (suffix) for JSP pages that contain JSF components. The default value is .jsp.

    Note:

    This parameter value is ignored when you use prefix mapping for the JSF servlet (for example, /faces), which is done by default for you.

  • javax.faces.LIFECYCLE_ID: Specifies a lifecycle identifier other than the default set by the javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE constant.

    Caution:

    Setting LIFECYCLE_ID to any other value will break ADF Faces.

  • org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION: Specifies whether JSP and CSS files require a restart in order to see changes at runtime. By default, set to false. Set to true if you want to be able to view changes without restarting the server.

A.3 Configuration in faces-config.xml

The JSF configuration file is where you register a JSF application's resources such as custom validators and managed beans, and define all the page-to-page navigation rules. While an application can have any JSF configuration file name, typically the file name is the faces-config.xml file. Small applications usually have one faces-config.xml file.

When you use ADF Faces components in your application, JDeveloper automatically adds the necessary configuration elements for you into faces-config.xml. For more information about the faces-config.xml file, see the Java EE 5 tutorial on Sun's web site (http://java.sun.com).

A.3.1 How to Configure for ADF Faces in faces-config.xml

In JDeveloper, when you create a project that uses JSF technology, an empty faces-config.xml file is created for you in the /WEB-INF directory. An empty faces-config.xml file is also automatically added for you when you create a new application workspace based on an application template that uses JSF technology (for example, the Java EE Web Application template. For more information, see Section 2.2, "Creating an Application Workspace."

When you use ADF Faces components in your application, the ADF default render kit ID must be set to oracle.adf.rich. When you insert an ADF Faces component into a JSF page for the first time, or when you add the first JSF page to an application workspace that was created using the Fusion template, JDeveloper automatically inserts the default render kit for ADF components into the faces-config.xml file, as shown in Example A-5.

Example A-5 ADF Default Render Kit Configuration in faces-config.xml

<?xml version="1.0" encoding="windows-1252"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">
  <application>
    <default-render-kit-id>oracle.adf.rich</default-render-kit-id>
  </application>
</faces-config>

Typically, you would configure the following in the faces-config.xml file:

  • Application resources such as message bundles and supported locales

  • Page-to-page navigation rules

  • Custom validators and converters

  • Managed beans for holding and processing data, handling UI events, and performing business logic

Note:

If your application uses ADF Controller, these items are configured in the adfc-config.xml file. For more information, see the "Getting Started With ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

In JDeveloper, you can use the declarative overview editor to modify the faces-config.xml file. If you are familiar with the JSF configuration elements, you can use the XML editor to edit the code directly.

To edit faces-config.xml:

  1. In the Application Navigator, double-click faces-config.xml to open the file.

    By default, JDeveloper opens the faces-config.xml file in the overview editor, as indicated by the active Overview tab at the bottom of the editor window.

    When you use the overview editor to add for example, managed beans and validators declaratively, JDeveloper automatically updates the faces-config.xml file for you.

  2. To edit the XML code directly in the faces-config.xml file, click Source at the bottom of the editor window.

    When you edit elements in the XML editor, JDeveloper automatically reflects the changes in the overview editor.

Tip:

JSF allows more than one <application> element in a single faces-config.xml file. The Overview mode of the JSF Configuration Editor allows you to edit only the first <application> instance in the file. For any other <application> elements, you will need to edit the file directly using the XML editor.

A.4 Configuration in adf-config.xml

The adf-config.xml file is used to configure application-wide features, like security, caching, and change persistence. Other Oracle components also configure properties in this file.

A.4.1 How to Configure ADF Faces in adf-config.xml

Before you can provide configuration for your application, you must first create the adf-config.xml file. Then you can add configuration for any application-wide ADF features that your application will use.

To create and edit adf-config.xml:

  1. If not already created, create a META-INF directory for your project.

  2. Right-click the META-INF directory, and choose New.

  3. In the New Gallery, expand General, select XML and then XML Document, and click OK.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.

  4. Enter adf-config.xml as the file name and save it in the META-INF directory.

  5. In the source editor, replace the generated code with the code shown in Example A-6.

    Example A-6 XML for adf-config.xml File

    <?xml version="1.0" encoding="utf-8" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
            xmlns:ads="http://xmlns.oracle.com/adf/activedata/config">
 
</adf-config>

  6. You can now add the elements needed for the configuration of features you wish to use.

A.4.2 Defining Caching Rules for ADF Faces Caching Filter

Caching rules for the ADF Faces Caching Filter (ACF) are defined in the adf-config.xml file, located in the web-application's .adf/META-INF directory. You must configure ACF to be in the request path for these URL matching rules. For information about adding the ACF servlet filter definition, see Section A.2.3.18, "ADF Faces Caching Filter."

The single root element for one or more caching rules is <caching-rules>, configured as a child of the <adf-faces-config> element in the namespace http://xmlns.oracle.com/adf/faces/config.

A <caching-rule> element defines each caching rule, evaluated in the order listed in the configuration file. Example A-7 shows the syntax for defining caching rules in adf-config.xml.

Example A-7 ACF Caching Rule Syntax

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
    <caching-rules xmlns="http://xmlns.oracle.com/adf/faces/rich/acf">
      <caching-rule id="cache-rule1">
        <cache>true|false</cache>
        <duration>3600</duration>
        <agent-caching>true|false</agent-caching>
        <agent-duration>4800</agent-duration>
        <compress>true|false</compress>
        <cache-key-pattern>....</cache-key-pattern>
        <search-key>
          <key>key1</key>
          <key>key2</key>
        </search-key>
        <varyBy>
          <vary-element>
            <vary-name><cookieName>|<headerName></vary-name>
            <vary-type>cookie|header</vary-type>
          </vary-element>
        </varyBy>
      </caching-rule>
    </caching-rules>
  </adf-faces-config>
</adf-config>

Each caching rule is defined in a <caching-rule> element. An optional id attribute can be defined to support rule location. Table A-1 describes the <caching-rule> child elements used to define the parameters for caching or compressing the objects in the application.

Table A-1 AFC Caching Rule Elements and Attributes

Rule Element Children Attribute Description and Value

<cache>

Specifies whether or not the object must be cached in the web cache. A value of false will ensure the object is never cached. The default is true.

<duration>

Defines the duration in seconds for which the object will be cached in the web cache. The default is 300 seconds.

<agent-caching>

Specify a value of true to use a browser cache in the absence of a web cache.

<agent-duration>

Defines the duration in seconds for which the object is cached in a browser cache. The default is -1. If <agent-caching> is true and <agent-duration> is not defined, then the value for <duration> is used instead.

<compress>

Specifies whether or not the object cached in the web cache must be compressed. The default value is true.

<cache-key-pattern>

Determines the URLs to match for the rule. One and only one <cache-key-pattern> element must be defined for the file extensions or the path prefix of a request URL. A <cache-key-pattern> value starting with a "*." value will be used as a file extension mapping, and others will be used as path prefix mapping.

<search-key>
<key>

Defines the search keys tagged to the cached object. Each <caching-rule> can define one <search-key> element with one or more child <key> elements. The value of a search key is used in invalidating cached content. A default <search-key> is added at runtime for the context root of the application in order to identify all resources related to an application.

<varyBy>
<vary-element>
<vary-name>
<vary-type>

Used for versioning objects cached in the web cache. A <varyBy> element can have one or more <vary-element> elements that define the parameters for versioning a cached object. Most static resources will not require this definition.

Each <vary-element> is defined by:

  • <vary-name>: Valid values are cookieName for the name of the cookie whose value the response varies on, or headerName for the name of the HTTP header whose value determines the version of the object that is cached in the web cache.

  • <vary-type>: Valid values are cookie or header.

The web cache automatically versions request parameters. Multiple version of an object will be stored in web cache based on the request parameter.

A.4.3 Configuring Flash as Component Output Format

By default, the application uses the output format specified for each component. For example, applications using ADF Data Visualization components can specify a Flash output format to display animation and interactivity effects in a web browser. If the component output format is Flash, and the user's platform doesn't support the Flash Player, as in Apple's iOS operating system, the output format is automatically downgraded to the best available fallback.

You can configure the use of Flash content across the entire application by setting a flash-player-usage context parameter in adf-config.xml. The valid settings include:

  • downgrade: Specify that if the output format is Flash, but the Flash Player isn't available, then downgrade to the best available fallback. The user will not be prompted to download the Flash Player.

  • disable: Specify to disable the use of Flash across the application. All components will be rendered in their non-Flash versions, regardless of whether or not the Flash Player is available on the client.

Example A-8 shows the syntax for application-wide disabling of Flash in adf-config.xml.

Example A-8 Flash Disabled in adf-config.xml

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
    <flash-player-usage>disabled</flash-player-usage>
  </adf-faces-config></adf-config>

The context parameter also supports an EL Expression value. This allows applications to selectively enable or disable Flash for different parts of the application, or for different users, based on their preferences.

Note:

Previously Data Visualization dvt:graph and dvt:gauge components used an imageFormat=AUTO" value. The AUTO value has been deprecated and you should set use imageFormat="FLASH" and set flash-player-usage context parameter to downgrade to achieve the same effect application-wide.

A.4.4 Using Content Delivery Networks

Content Delivery Networks (CDNs) improve web application performance by providing more efficient network access to content. Applications can use a variety of CDN configurations to optimize the user experience. An increasingly common configuration is to route all requests through a CDN. The CDN acts as a proxy between the client and the application. CDN-specific configuration tools can be used to specify caching and compression rules.

An alternate approach is to limit which requests are routed through the CDN. For example, only requests for auxiliary resources (images, JavaScript libraries, style sheets) might be directed to the CDN, while requests for application-generated HTML content can be served up directly. In this case, it is necessary to convert relative resource URIs to absolute URIs that point to the host that is serviced by the CDN.

For example, say your application-defined images are held in a local directory named images. Your code to reference images might look something like Example A-9:

Example A-9 Default Image Reference

<af:image source="/images/logo.png"
          shortDesc="My Company Logo"
          id="i1"/>

One way to indicate that the image should be retrieved from a CDN is to explicitly specify an absolute URI for the image source, as shown in Example A-10:

Example A-10 Image Reference from a CDN Using an Absolute URI

<af:image source="http://mycdn.com/images/logo.png"
          shortDesc="My Company Logo"
          id="i1"/>

A downside of this approach is that it requires updating many locations (possibly every image reference) in the application, duplicating the CDN base URI across pages. This can make enabling and disabling CDN usage or switching from one CDN to another prohibitively difficult.

An alternative approach might be to EL bind resource-related attributes, as shown in Example A-11:

Example A-11 EL Binding to a CDN Base URI

  <af:image source="#{preferences.baseUri}/logo.png"
                     shortDesc="My Company Logo"
                     id="i1"/>

This approach allows the CDN base URI to be specified in a single location (for example, in a managed bean). However, it places a burden on application developers to use the correct EL expressions throughout their content.

Rather than repeating references to the CDN location (either directly or through EL expressions) throughout the application, ADF Faces provides a centralized mechanism for modifying resource URIs. This mechanism allows one or more prefixes, or "base resource URIs", to be specified for resources. These base resource URIs are defined in the application's adf-config.xml file, under the http://xmlns.oracle.com/adf/rewrite/config namespace.

For example, Example A-12 specifies that all png images in the images directory should be rewritten to include the http://mycdn.com prefix.

Example A-12 Specifying a CDN Prefix in adf-config.xml

  <adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">
    <resource-uris>
      <base-resource-uri uri="http://mycdn.com/">
        <match-pattern>î/.*/images/.*\.png$</match-pattern>
      </base-resource-uri>
    </resource-uris>
  </adf-uri-rewrite-config>

The regular expression specified by the <match-pattern> element (î/.*/images/.*\.png$) is tested against all resource URIs rendered by the application. Any matching URIs are transformed to include the prefix specified by the <base-resource-uri> element's URI attribute.

One advantage of this solution is that it can be used to modify not just application-defined resource URIs, but URIs for resources that are used by ADF Faces itself. To simplify this task, ADF Faces exposes a small set of aliases that can be used with the <match-alias> element in place of regular expressions.

For example, the configuration in Example A-13 applies the http://mycdn.com/ prefix to all images defined by ADF Faces components:

Example A-13 Apply Prefix to a Resource

  <adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">
    <resource-uris>
      <base-resource-uri uri="http://mycdn.com/">
        <match-alias>af:images</match-alias>
      </base-resource-uri>
    </resource-uris>
  </adf-uri-rewrite-config>

Unlike the regular expressions specified via <match-pattern> elements, the aliases used with <match-alias> do not match application-defined resources. So, for example, the af:images alias in the above configuration will cause images defined by ADF Faces components, such as the default background images and icons that come with ADF Faces, to be prefixed without also prefixing images that are explicitly bundled with the application.

In addition to the af:images alias, aliases are also provided for targeting the ADF Faces skins (style sheets), JavaScript libraries and resource documents.

To set up URIs for a CDN:

  1. Create or open the adf-config.xml file (for more information, see Section A.4.1, "How to Configure ADF Faces in adf-config.xml").

  2. Create rewrite rules to define the replacement URIs for the CDN, using the elements shown in Table A-2.

    Note:

    All attribute values may be EL-bound. However, EL-bound attributes are only evaluated once (at parse time).

    Table A-2 CDN URI Rewrite Elements

    Element Definition

    <adf-uri-rewrite-config>

    This xmlns value must be set to http://xmlns.oracle.com/adf/rewrite/config

    <resource-uris>

    Defines the rules to rewrite the paths to given resources

    <base-resource-uri>

    Defines the base URI for the rewritten path. Multiple <base-resource-uri> elements may be defined. This element has three attributes:

    • uri: sets URI for the CDN. This will be used to create the full URI for the given resource."

    • secure-uri: sets the prefix when the URI is secure, for example, "https://"

    • output-context-path: determines whether or not to remove the application-specific context path in the rewritten URI. Valid values are either remove (the default) or preserve.

    <match-pattern>

    A regular expression that is tested against rendered resource URIs. If a match is found, the resource URI is prefixed with the URI specified by the <base-resource-uri> element..Multiple <match-pattern> elements may be defined for each <base-resource-uri> element.

    Note that in order to minimize runtime overhead, the results of resource uri rewriting are cached. To prevent excessive caching, <match-pattern> regular expressions should only target static resources. Dynamically generated, data-centric resources (for example, resources generated from unbounded query parameter values) must not be rewritten using the base resource uri mechanism.

    <match-alias>

    Defines an alias that matches one of the ADF Faces-provided resources. The resource may be one of the following:

    • af:documents: matches ADF Faces' HTML resources (for example, blank.html)

    • af:images: matches ADF Faces' and Trinidad's image resources

    • af:coreScripts: matches ADF Faces' boot and core JavaScript libraries

    • af:skins: matches skin-generated style sheets

    Multiple <match-alias> elements may be defined for each <base-resource-uri> element.

    The values specified in the match elements are compared against all URIs that pass through ExteralContext.encodeResourceURL(). If a URI matches, the prefix specified in the enclosing <base-resource-uri> element is applied.

    Example A-14 shows how an application might be configured to use a CDN.

    Example A-14 CDN URI Elements

    <adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">   
  <resource-uris>
    <base-resource-uri uri="http://mycdn.com/"
                       secure-uri="https"
                       output-context-path="remove">
      <match-pattern>î/.*/images/.*\.png$</match-pattern>
      <match-alias>af:documents</match-alias>
      <match-alias>af:coreScripts</match-alias>
    </base-resource-uri>
  </resource-uris>
</adf-uri-rewrite-config>

A.4.4.1 What You May Need to Know About Skin Style Sheets and CDN

While you can use the af:skins alias to rewrite skin style sheets to point to the CDN, in cases where the CDN is configured to proxy requests back to the application server, problems can arise if a the application is running in a clustered and/or load-balanced environment.

Skin style sheets are generated and stored on the server that rendered the containing page content. By routing the style sheet request through the CDN, server affinity may be lost (for example, if the CDN lives in a different domain, resulting in a loss of the session cookie). As a result, the style sheet request may be routed to a server that has not yet generated the requested style sheet. In such cases, the style sheet request will not complete successfully.

To avoid potential failures in load-balanced and/or clustered environments you should not rewrite skin style sheet URIs in cases where cookies or session affinity may be lost.

A.4.4.2 What You May Need to Know About JavaScript and CDN

The af:coreScripts alias can be used to rewrite ADF's "core" JavaScript libraries (that is, the JavaScript libraries that are present on every ADF page) to a CDN. In addition, <match-pattern> regular expressions can be used to rewrite arbitrary (for example, application-defined) JavaScript library URIs. However, in cases where JavaScript libraries are introduced into the page dynamically (for example, as a result of partial page rendering), some origin policy restrictions apply. As a result, JavaScript library URIs that have been rewritten to a cross-origin host may fail to load.

You should limit JavaScript library URI rewriting to those libraries covered by af:coreScripts and also in cases where the application-provided libraries are known to be included as part of initial page renders (that is, the libraries are never introduced as part of a PPR request).

A.5 Configuration in adf-settings.xml

The adf-settings.xml file holds project- and library-level settings such as ADF Faces help providers and caching and compression rules. The configuration settings for the adf-settings.xml files are fixed and cannot be changed during and after application deployment. There can be multiple adf-settings.xml files in an application, however the adf-settings.xml file users are responsible for merging the contents of their configurations.

A.5.1 How to Configure for ADF Faces in adf-settings.xml

Before you can provide configuration for your application, you must first create the adf-settings.xml file. Then you can add the configuration for any project features that your application will use. For more information about configurations in this file, see Section A.5.2, "What You May Need to Know About Elements in adf-settings.xml."

To create and edit adf-settings.xml:

  1. The adf-settings.xml file must reside in a META-INF directory. Where you create this directory depends on how you plan on deploying the project that uses the adf-settings.xml file.

    • If you will be deploying the project with the application EAR file, create the META-INF directory in the /application_name/.adf directory.

    • If the project has a dependency on the adf-settings.xml file, and the project may be deployed separately from the application (for example a bounded task flow deployed in an ADF library), then create the META-INF directory in the /src directory of your view project.

      Tip:

      If your application uses Oracle ADF Model, then you can create the META-INF directory in the /adfmsrc directory.

  2. In JDeveloper choose File > New.

  3. In the New Gallery, expand General, select XML and then XML Document, and click OK.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.

  4. In the source editor, replace the generated code with the code shown in Example A-15, using the correct settings for your web application root.

    Example A-15 XML for adf-settings.xml File

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings"
              xmlns:wap="http://xmlns.oracle.com/adf/share/http/config" >
  <wap:adf-web-config xmlns="http://xmlns.oracle.com/adf/share/http/config">
    <web-app-root rootName="myroot" />
  </wap:adf-web-config>
</adf-settings>

  5. You can now add the elements needed for the configuration of features you wish to use. For more information, see Section A.5.2, "What You May Need to Know About Elements in adf-settings.xml."

  6. Save the file as adf-settings.xml to the META-INF directory created in Step 1.

A.5.2 What You May Need to Know About Elements in adf-settings.xml

The following configuration elements are supported in the adf-settings.xml file.

A.5.2.1 Help System

You register the help provider used by your help system using the following elements:

  • <adf-faces-config>: A parent element that groups configurations specific to ADF Faces.

  • <prefix-characters>: The provided prefix if the help provider is to supply help topics only for help topic IDs beginning with a certain prefix. This can be omitted if prefixes are not used.

  • <help-provider-class>: The help provider class.

  • <custom-property> and <property-value>: A property element that defines the parameters the help provider class accepts.

Example A-16 shows an example of a registered help provider. In this case, there is only one help provider for the application, so there is no need to include a prefix.

Example A-16 Help Provider Registration

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="MYAPP">
    <help-provider-class>
      oracle.adfdemo.view.webapp.MyHelpProvider
    </help-provider-class>
    <property>
      <property-name>myCustomProperty</property-name>
      <value>someValue</value>
    </property>
  </help-provider>
</adf-faces-config>
</adf-settings>

A.5.2.2 Caching Rules

Application-specific libraries and JARs contain a variety of resources that may require caching and/or compression of files. In the event of multiple libraries or JARs, an application may include one or more adf-setting.xml files that contain various caching rules based on matching URLs. The caching rules are merged into an ordered list at runtime. If a request for a resource matches more than one caching rule, the rule encountered first in the list will be honored.

The ADF Faces JAR includes default caching rules for common resource types, such as .js, .css, and image file types. These fixed rules are defined in the adf-settings.xml file, and cannot be changed during or after application deployment. Application developers can define application caching rules in the adf-config.xml file that take precedence over the rules defined in adf-settings.xml. Example A-17 shows the adf-settings.xml file for the ADF Faces JAR.

Example A-17 ADF Faces adf-settings.xml File

<adf-settings>
  <adf-faces-settings>
    <caching-rules>
      <caching-rule id="cache css">
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.css</cache-key-pattern>
      </caching-rule>
      <caching-rule id="cache js">
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.js</cache-key-pattern>
      </caching-rule>
      <caching-rule id="cache png">
        <compress>false</compress>
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.png</cache-key-pattern>
      </caching-rule>
      <caching-rule id="cache jpg">
        <compress>false</compress>
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.jpg</cache-key-pattern>
      </caching-rule>
      <caching-rule id="cache jpeg">
        <compress>false</compress>
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.jpeg</cache-key-pattern>
       </caching-rule>
      <caching-rule id="cache gif">
        <compress>false</compress>
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.gif</cache-key-pattern>
      </caching-rule>
      <caching-rule id="cache html">
        <compress>true</compress>
        <duration>99999</duration>
        <agent-caching>true</agent-caching>
        <cache-key-pattern>*.html</cache-key-pattern>
      </caching-rule>
    </caching-rules>
  </adf-faces-settings>
</adf-settings>

A.6 Configuration in trinidad-config.xml

When you create a JSF application using ADF Faces components, you configure ADF Faces features (such as skin family and level of page accessibility support) in the trinidad-config.xml file. Like faces-config.xml, the trinidad-config.xml file has a simple XML structure that enables you to define element properties using the JSF Expression Language (EL) or static values.

A.6.1 How to Configure ADF Faces Features in trinidad-config.xml

In JDeveloper, when you insert an ADF Faces component into a JSF page for the first time, a starter trinidad-config.xml file is automatically created for you in the /WEB-INF directory. Example A-18 shows a starter trinidad-config.xml file.

Example A-18 Starter trinidad-config.xml File Created by JDeveloper

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://xmlns.oracle.com/trinidad/config">
 
  <skin-family>skyros</skin-family>
  <skin-version>v1</skin-version>
 
</trinidad-config>

By default, JDeveloper configures the skyros skin family for a JSF application that uses ADF Faces. You can change this to fusion-fx, simple, or use a custom skin. If you wish to use a custom skin, create the trinidad-skins.xml configuration file, and modify trinidad-config.xml file to use the custom skin. For more information about creating custom skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

Typically, you would configure the following in the trinidad-config.xml file:

  • Page animation

  • Level of page accessibility support

  • Time zone

  • Enhanced debugging output

  • Oracle Help for the Web (OHW) URL

You can also register a custom file upload processor for uploading files.

In JDeveloper, you can use the XML editor to modify the trinidad-config.xml file.

To edit trinidad-config.xml:

  1. In the Application Navigator, double-click trinidad-config.xml to open the file in the XML editor.

  2. If you are familiar with the element names, enter them in the editor. Otherwise use the Structure window to help you insert them.

  3. In the Structure window:

    1. Right-click an element to choose from the Insert before or Insert after menu, and click the element you wish to insert.

    2. Double-click the newly inserted element in the Structure window to open it in the Property Inspector. Enter a value or select one from a dropdown list (if available).

      In most cases you can enter either a JSF EL expression (such as #{view.locale.language=='en' ? 'minimal' : 'skyros'}) or a static value (for example., <debug-output>true</debug-output>). EL expressions are dynamically reevaluated on each request, and must return an appropriate object (for example, a boolean object).

For a list of the configuration elements you can use, see Section A.6.2, "What You May Need to Know About Elements in trinidad-config.xml."

Once you have configured the trinidad-config.xml file, you can retrieve the property values programmatically or by using JSF EL expressions. For more information, see Section A.8, "Using the RequestContext EL Implicit Object."

A.6.2 What You May Need to Know About Elements in trinidad-config.xml

All trinidad-config.xml files must begin with a <trinidad-config> element in the http://myfaces.apache.org/trinidad/config XML namespace. The order of elements inside of <trinidad-config> does not matter. You can include multiple instances of any element.

A.6.2.1 Animation Enabled

Certain ADF Faces components use animation when rendering. For example, trees and tree tables use animation when expanding and collapsing nodes. The following components use animation when rendering:

  • Table detail facet for disclosing and undisclosing the facet

  • Trees and tree table when expanding and collapsing nodes

  • Menus

  • Popup selectors

  • Dialogs

  • Note windows and message displays

The type and time of animation used is configured as part of the skin for the application. For more information, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

You can set the animation-enabled element to either true or false, or you can use an EL expression that resolves to either true or false.

Note:

Enabling animation will have an impact on performance. For more information, see the "Oracle Application Development Framework Performance Tuning" section in the Oracle Fusion Middleware Performance and Tuning Guide.

A.6.2.2 Skin Family

As described in Section A.6.1, "How to Configure ADF Faces Features in trinidad-config.xml," JDeveloper by default uses the skyros skin family for a JSF application that uses ADF Faces. You can change the <skin-family> value to fusion-fx, simple, or to a custom skin definition. For information about creating and using custom skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

You can use an EL expression for the skin family value, as shown in the following code:

<skin-family>#{prefs.proxy.skinFamily}</skin-family>

A.6.2.3 Time Zone and Year

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>: By default, ADF Faces uses the time zone used by the application server if no value is set. If needed, you can use an EL expression that evaluates to a TimeZone object. This value is used by org.apache.myfaces.trinidad.converter.DateTimeConverter while converting strings to Date.

  • <two-digit-year-start>: This value is specified as a Gregorian calendar year and is used by org.apache.myfaces.trinidad.converter.DateTimeConverter to convert strings to Date. This element defaults to the year 1950 if no value is set. If needed, you can use a static, integer value or an EL expression that evaluates to an Integer object.

A.6.2.4 Enhanced Debugging Output

By default, the <debug-output> element is false. 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 invalid locations).

Performance Tip:

Debugging impacts performance. Set this parameter to false in a production environment.

A.6.2.5 Page Accessibility Level

Use <accessibility-mode> to define the level of accessibility support in an application. 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.

    Note:

    Screen reader mode may have a negative effect on other users. For example, access keys are not displayed if the accessibility mode is set to screen reader mode.

Use <accessibility-profile> to configure the color contrast and font size used in the application. The supported values are:

  • high-contrast: Application displays using high-contrast instead of the default contrast.

  • large-fonts: Application displays using large fonts instead of the default size fonts.

To use more than one setting, separate the values with a space.

A.6.2.6 Language Reading Direction

By default, ADF Faces page rendering direction is based on the language being used by the browser. You can, however, explicitly set the default page rendering direction in the <right-to-left> element by using an EL expression that evaluates to a Boolean object, or by using true or false, as shown in the following code:

<!-- Render the page right-to-left for Arabic -->
<!-- and left-to-right for all other languages -->
<right-to-left>
 #{view.locale.language=='ar' ? 'true' : 'false'}
</right-to-left>

A.6.2.7 Currency Code and Separators for Number Groups and Decimal Points

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 the org.apache.myfaces.trinidad.converter.NumberConverter class to format currency fields that do not specify an explicit currency code in their own converter. Use a static value or an EL expression that evaluates to a String object. For example:

    <!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>

  • <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. You can use a static value or an EL expression that evaluates to a Character object. If set, this value is used by the org.apache.myfaces.trinidad.converter.NumberConverter class while parsing and formatting.

    For example, to set the number grouping separator to a period when the German language is used in the application, use this 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>

  • <decimal-separator>: Defines the separator (for example, 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. You can use a static value or an EL expression that evaluates to a Character object. If set, this value is used by the org.apache.mtfaces.trinidad.converter.NumberConverter class while parsing and formatting.

    For example, to set the decimal separator to a comma when the German language is used in the application, use this code:

    <!-- Set the decimal separator to comma for German -->
<!-- and period for all other languages -->
<decimal-separator>
 #{view.locale.language=='de' ? ',' : '.'}
</decimal-separator>

A.6.2.8 Formatting Dates and Numbers Locale

By default, ADF Faces and MyFaces Trinidad will format dates (including the first day of the week) and numbers in the same locale used for localized text (which by default is the locale of the browser). If, however, you want dates and numbers formatted in a different locale, you can use the <formatting-locale> element, which takes an IANA-formatted locale (for example, ja, fr-CA) as its value. The contents of this element can also be an EL expression pointing at an IANA string or a java.util.Locale object.

A.6.2.9 Output Mode

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 emailing a page's content.

A.6.2.10 Number of Active PageFlowScope Instances

By default ADF Faces sets the maximum number of active PageFlowScope instances at any one time to 15. Use the <page-flow-scope-lifetime> element to change the number. Unlike other elements, you must use a static value: EL expressions are not supported.

A.6.2.11 Custom File Uploaded Processor

Most applications do not need to replace the default UploadedFileProcessor instance provided in ADF Faces, but if your application must support uploading of very large files, or if it relies 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 your custom implementation using the <uploaded-file-processor> element, as shown in the following code:

<uploaded-file-processor>
 com.mycompany.faces.myUploadedFileProcessor
</uploaded-file-processor>

A.6.2.12 Client-Side Validation and Conversion

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.

The JavaScript-enabled validators and converters run on the client when the form is submitted; thus errors can be caught without a server roundtrip.

The <client-validation-disabled> configuration element is not supported in the rich client version of ADF Faces. This means you cannot turn off client-side validation and conversion in ADF Faces applications.

A.7 Configuration in trinidad-skins.xml

By default, JDeveloper uses the skyros skin family when you create JSF pages with ADF Faces components. The skin family is configured in the trinidad-config.xml file, as described in Section A.6.1, "How to Configure ADF Faces Features in trinidad-config.xml." If you wish to use a custom skin for your application, create a trinidad-skins.xml file, which is used to register custom skins in an application.

For detailed information about creating custom skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

A.8 Using the RequestContext EL Implicit Object

In ADF Faces, you can use the EL implicit object requestContext to retrieve values from configuration properties defined in the trinidad-config.xml file. The requestContext implicit object, which is an instance of the org.apache.myfaces.trinidad.context.RequestContext class, exposes several properties of type java.util.Map, enabling you to use JSF EL expressions to retrieve context object property values.

For example, the EL expression #{requestContext} returns the RequestContext object itself, and the EL expression #{requestContext.skinFamily} returns the value of the <skin-family> element from the trinidad-config.xml file.

You can also use EL expressions to bind a component attribute value to a property of the requestContext implicit object. For example, in the EL expression that follows, the <currency-code> property is bound to the currencyCode attribute value of the JSF ConvertNumber component:

<af:outputText>
  <f:convertNumber currencyCode="#{requestContext.currencyCode}"/>
</af:outputText>

You can use the following requestContext implicit object properties:

  • requestContext.accessibilityMode: Returns the value of the <accessibility-mode> element from the trinidad-config.xml file.

  • requestContext.agent: Returns an object that describes the client agent that is making the request and that is to display the rendered output. The properties in the agent object are:

    • agentName: Canonical name of the agent browser, (for example, gecko and ie).

    • agentVersion: Version number of the agent browser.

    • capabilities: Map of capability names (for example, height, width) and their values for the current client request.

    • hardwareMakeModel: Canonical name of the hardware make and model (for example, nokia6600 and sonyericssonP900).

    • platformName: Canonical name of the platform (for example, ppc, windows, and mac).

    • platformVersion: Version number of the platform.

    • type: Agent type (for example, desktop, pda, and phone).

  • requestContext.clientValidationDisabled: Returns the value of the <client-validation-disabled> element from the trinidad-config.xml file.

  • requestContext.colorPalette: Returns a Map that takes color palette names as keys, and returns the color palette as a result. Each color palette is an array of java.awt.Color objects. Provides access to four standard color palettes:

    • web216: The 216 web-safe colors

    • default49: A 49-color palette, with one fully transparent entry

    • opaque40: A 49-color palette, without a fully transparent entry

    • default80: An 80-color palette, with one fully transparent entry

  • requestContext.currencyCode: Returns the value of the <currency-code> element from the trinidad-config.xml file.

  • requestContext.debugOutput: Returns the value of the <debug-output> element from the trinidad-config.xml file.

  • requestContext.decimalSeparator: Returns the value of the <decimal-separator> element from the trinidad-config.xml file.

  • requestContext.formatter: Returns a Map object that performs message formatting with a recursive Map structure. The first key must be the message formatting mask, and the second key is the first parameter into the message.

  • requestContext.helpSystem: Returns a Map object that accepts help system properties as keys, and returns a URL as a result. For example, the EL expression #{requestContext.helpSystem['frontPage']} returns a URL to the front page of the help system. This assumes you have configured the <oracle-help-servlet-url> element in the trinidad-config.xml file.

  • requestContext.helpTopic: Returns a Map object that accepts topic names as keys, and returns a URL as a result. For example, the EL expression #{requestContext.helpTopic['foo']} returns a URL to the help topic "foo". This assumes you have configured the <oracle-help-servlet-url> element in the trinidad-config.xml file.

  • requestContext.numberGroupingSeparator: Returns the value of the <number-grouping-separator> element from the trinidad-config.xml file.

  • requestContext.oracleHelpServletUrl: Returns the value of the <oracle-help-servlet-url> element from the trinidad-config.xml file.

  • requestContext.outputMode: Returns the value of the <output-mode> element from the trinidad-config.xml file.

  • requestContext.pageFlowScope: Returns a map of objects in the pageFlowScope object.

  • requestContext.rightToLeft: Returns the value of the <right-to-left> element from the trinidad-config.xml file.

  • requestContext.skinFamily: Returns the value of the <skin-family> element from the trinidad-config.xml file.

  • requestContext.timeZone: Returns the value of the <time-zone> element from the trinidad-config.xml file.

  • requestContext.twoDigitYearStart: Returns the value of the <two-digit-year-start> element from the trinidad-config.xml file.

For a complete list of properties, refer to the Javadoc for org.apache.myfaces.trinidad.context.RequestContext.

Note:

One instance of the org.apache.myfaces.trinidad.context.RequestContext class exists per request. The RequestContext class does not extend the JSF FacesContext class.

To retrieve a configuration property programmatically, first call the static getCurrentInstance() method to get an instance of the RequestContext object, and then call the method that retrieves the desired property, as shown in the following code:

RequestContext context = RequestContext.getCurrentInstance();

// Get the time-zone property
TimeZone zone = context.getTimeZone();

// Get the right-to-left property
if (context.isRightToLeft())
{
  .
  .
  .
}

A.9 Using JavaScript Library Partitioning

ADF Faces groups its components' JavaScript files into JavaScript features. A JavaScript feature is a collection of JavaScript files associated with a logical identifier that describes the feature. For example, the panelStretchLayout client component is comprised of the following two JavaScript files

  • oracle/adf/view/js/component/rich/layout/
    AdfRichPanelStretchLayout.js

  • oracle/adfinternal/view/js/laf/dhtml/rich/
    AdfDhtmlPanelStretchLayoutPeer.js

These two files are grouped into the AdfRichPanelStretchLayout feature.

JavaScript features are further grouped into JavaScript partitions. JavaScript partitions allow you to group JavaScript features into larger collections with the goal of influencing the download size and number of round trips. For example, since the panelStretchLayout component is often used with the panelSplitter component, the features for these two components are grouped together in the stretch partition, along with the other ADF Faces layout components that can stretch their children. At runtime, when a page is loaded, the framework determines the components used on the page, and then from that, determines which features are needed (feature names are the same as the components' constructor name). Only the partitions that contain those features are downloaded. For more information about JavaScript partitioning, see Section 1.2.1.2, "JavaScript Library Partitioning."

Features and partitions are defined using configuration files. ADF Faces ships with a default features and partitions configuration file. You can overwrite the default partitions file by creating your own implementation. When you create custom ADF Faces components, you can create your own features and partition configuration files for those components.

By default, JavaScript partitioning is turned on. Whether or not your application uses JavaScript partitioning is determined by a context parameter in the web.xml file. For more information about enabling or disabling JavaScript partitioning, see Section A.2.3.14, "JavaScript Partitioning."

A.9.1 How to Create a JavaScript Feature

You create a JavaScript feature by creating an adf-js-features.xml file, and then adding entries for the features.

Note:

You create JavaScript features when you create custom ADF Faces components. All existing ADF Faces components already have features created for them, and these cannot be changed.

To create a JavaScript feature:

  1. If not already created, create a META-INF directory for your component.

  2. Right-click the META-INF directory, and choose New from the context menu.

  3. In the New Gallery, expand General, select XML and then XML Document, and click OK.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.

  4. Enter adf-js-features.xml as the file name and save it in the META-INF directory.

  5. In the source editor, replace the generated code with the code shown in Example A-6.

    Example A-19 XML for adf-js-features.xml File

    <?xml version="1.0" encoding="utf-8" ?>
<adf-js-features xmlns="http://xmlns.oracle.com/adf/faces/feature"
 
</adf-js-features>

  6. Add the following elements to populate a feature with the relevant component files and dependencies.

    • features: The root element of the configuration file.

    • feature: Create as a child to the features element. This element must contain one feature-name child element and can also contain any number of feature-class, as well as any number of feature-dependency elements.

    • feature-name: Create as a child to the feature element. Specifies the name of the feature. You must use the client component's constructor name for this value.

    • feature-class: Create as a child to the feature element. Specifies the location of the single JavaScript file or class to be included in this feature. There can be multiple feature-class elements.

    • feature-dependency: Create as a child to the feature element. Specifies the name of another feature that this feature depends on. For example, if one component B extends component A, then the feature that represents component A must be listed as a dependency for component B. By noting dependencies, the framework can ensure that any dependent classes are available, even if the two features are not in the same partition.

    Example A-20 shows the feature element for a fictitious custom component that uses popup components (and therefore has a dependency to the popup feature).

    Example A-20 JavaScript Features Configuration

    <features xmlns="http://xmlns.oracle.com/adf/faces/feature">
  <feature>
    <feature-name>AcmeMyPane</feature-name>
    <feature-class>
      oracle/adfdemo/acme/js/component/AcmeMyPane.js
    </feature-class>
    <feature-class>
      oracle/adfdemo/acme/js/event/AcmePaneSelectEvent.js
    </feature-class>
    <feature-class>
      oracle/adfdemo/acme/js/component/AcmeMyPanePeer.js
    </feature-class>

  <!-- Dependencies -->
 
  <!-- Popup hints -->
  <feature-dependency>AdfRichPopup</feature-dependency>
 
</feature>

A.9.2 How to Create JavaScript Partitions

You create a JavaScript partition by creating an adf-js-partitions.xml file, and then adding entries for the features.

Note:

ADF Faces provides a default adf-js-partitions.xml file (see Example A-23). If you want to change the partition configuration, you need to create your own complete adf-js-partitions.xml file. At runtime, the framework will search the WEB-INF directory for that file. If one is not found, it will load the default partition file.

To create JavaScript partitions:

  1. Right-click the WEB-INF directory, and choose New from the context menu.

  2. In the New Gallery, expand General, select XML and then XML Document, and click OK.

    Tip:

    If you don't see the General node, click the All Technologies tab at the top of the Gallery.

  3. Enter adf-js-partitions.xml as the file name and save it in the WEB-INF directory.

  4. In the source editor, replace the generated code with the code shown in Example A-6.

    Example A-21 XML for adf-js-partitions.xml File

    <?xml version="1.0" encoding="utf-8" ?>
<adf-js-partitions xmlns="http://xmlns.oracle.com/adf/faces/partition"
 
</adf-js-partitions>

  5. Add the following elements to populate a partition with the relevant features.

    • partitions: The root element of the configuration file.

    • partition: Create as a child to the partitions element. This element must contain one partition-name child element and one or more feature elements.

    • partition-name: Create as a child to the partition element. Specifies the name of the partition. This value will be used to produce a unique URL for this partition's JavaScript library.

    • feature: Create as a child to the partition element. Specifies the feature to be included in this partition. There can be multiple feature elements.

    Tip:

    Any feature configured in the adf-js-features.xml file that does not appear in a partition is treated as if it were in its own partition.

    Example A-22 shows the partition element for the tree partition that contains the AdfRichTree and AdfRichTreeTable features.

    Example A-22 JavaScript Partition Configuration

    <partition>
  <partition-name>tree</partition-name>
  <feature>AdfUITree</feature>
  <feature>AdfUITreeTable</feature>
  <feature>AdfRichTree</feature>
  <feature>AdfRichTreeTable</feature>
</partition>

A.9.3 What You May Need to Know About the adf-js-partitions.xml File

The default ADF Faces adf-js-partitions.xml file has partitions that you can override by creating your own partitions file. For more information, see Section A.9.2, "How to Create JavaScript Partitions." Example A-23 shows the default ADF Faces adf-js-partitions.xml file.

Example A-23 The Default adf-js-partitions.xml File

<?xml version="1.0" encoding="utf-8"?>
 
<partitions xmlns="http://xmlns.oracle.com/adf/faces/partition">
 
  <partition>
    <partition-name>boot</partition-name>
    <feature>AdfBootstrap</feature>
  </partition>
 
  <partition>
    <partition-name>core</partition-name>
 
    <feature>AdfCore</feature>
 
    <!-- Behavioral component super classes -->
    <feature>AdfUIChoose</feature>
    <feature>AdfUICollection</feature>
    <feature>AdfUICommand</feature>
    <feature>AdfUIDialog</feature>
    <feature>AdfUIDocument</feature>
    <feature>AdfUIEditableValue</feature>
    <feature>AdfUIForm</feature>
    <feature>AdfUIGo</feature>
    <feature>AdfUIInput</feature>
    <feature>AdfUIObject</feature>
    <feature>AdfUIOutput</feature>
    <feature>AdfUIPanel</feature>
    <feature>AdfUIPopup</feature>
    <feature>AdfUISelectBoolean</feature>
    <feature>AdfUISelectInput</feature>
    <feature>AdfUISelectOne</feature>
    <feature>AdfUISelectMany</feature>
    <feature>AdfUIShowDetail</feature>
    <feature>AdfUISubform</feature>
    <feature>AdfUIValue</feature>
 
    <!-- These are all so common that we group them with core -->
    <feature>AdfRichDocument</feature>
    <feature>AdfRichForm</feature>
    <feature>AdfRichPopup</feature>
    <feature>AdfRichSubform</feature>
    <feature>AdfRichCommandButton</feature>
    <feature>AdfRichCommandLink</feature>
 
    <!-- 
      Dialog is currently on every page for messaging.  No use
      in putting these in a separate partition.
    -->
    <feature>AdfRichPanelWindow</feature>
    <feature>AdfRichDialog</feature>
 
    <!-- af:showPopupBehavior is so small/common, belongs in core -->
    <feature>AdfShowPopupBehavior</feature>
  </partition>
 
  <partition>
    <partition-name>accordion</partition-name>
    <feature>AdfRichPanelAccordion</feature>
  </partition>
 
  <partition>
    <partition-name>border</partition-name>
    <feature>AdfRichPanelBorderLayout</feature>
  </partition>
 
  <partition>
    <partition-name>box</partition-name>
    <feature>AdfRichPanelBox</feature>
  </partition>
  
  <partition>
    <partition-name>calendar</partition-name>
    <feature>AdfUICalendar</feature>
    <feature>AdfRichCalendar</feature>
    <feature>AdfCalendarDragSource</feature>
    <feature>AdfCalendarDropTarget</feature>
  </partition>
  
  <partition>
    <partition-name>collection</partition-name>
    <feature>AdfUIDecorateCollection</feature>
    <feature>AdfRichPanelCollection</feature>
  </partition>
 
  <partition>
    <partition-name>color</partition-name>
    <feature>AdfRichChooseColor</feature>
    <feature>AdfRichInputColor</feature>
  </partition>
 
  <partition>
    <partition-name>date</partition-name>
    <feature>AdfRichChooseDate</feature>
    <feature>AdfRichInputDate</feature>
  </partition>
 
  <partition>
    <partition-name>declarativeComponent</partition-name>
    <feature>AdfUIInclude</feature>
    <feature>AdfUIDeclarativeComponent</feature>
    <feature>AdfRichDeclarativeComponent</feature>
  </partition>
 
  <partition>
    <partition-name>detail</partition-name>
    <feature>AdfRichShowDetail</feature>
  </partition>
 
  <partition>
    <partition-name>dnd</partition-name>
    <feature>AdfDragAndDrop</feature>
    <feature>AdfCollectionDragSource</feature>
    <feature>AdfStampedDropTarget</feature>
    <feature>AdfCollectionDropTarget</feature>
    <feature>AdfAttributeDragSource</feature>
    <feature>AdfAttributeDropTarget</feature>
    <feature>AdfComponentDragSource</feature>
    <feature>AdfDropTarget</feature>    
  </partition>
  
  <partition>
    <partition-name>detailitem</partition-name>
    <feature>AdfRichShowDetailItem</feature>
  </partition>
 
  <partition>
    <partition-name>file</partition-name>
    <feature>AdfRichInputFile</feature>
  </partition>
 
  <partition>
    <partition-name>form</partition-name>
    <feature>AdfRichPanelFormLayout</feature>
    <feature>AdfRichPanelLabelAndMessage</feature>
  </partition>
 
  <partition>
    <partition-name>format</partition-name>
    <feature>AdfRichOutputFormatted</feature>
  </partition>
 
  <partition>
    <partition-name>frame</partition-name>
    <feature>AdfRichInlineFrame</feature>
  </partition>
 
  <partition>
    <partition-name>header</partition-name>
    <feature>AdfRichPanelHeader</feature>
    <feature>AdfRichShowDetailHeader</feature>
  </partition>
 
  <partition>
    <partition-name>imagelink</partition-name>
    <feature>AdfRichCommandImageLink</feature>
  </partition>
 
  <partition>
    <partition-name>iedit</partition-name>
    <feature>AdfInlineEditing</feature>
  </partition>
 
  <partition>
    <partition-name>input</partition-name>
    <feature>AdfRichInputText</feature>
    <feature>AdfInsertTextBehavior</feature>
  </partition>
 
  <partition>
    <partition-name>label</partition-name>
    <feature>AdfRichOutputLabel</feature>
  </partition>
 
  <partition>
    <partition-name>list</partition-name>
    <feature>AdfRichPanelList</feature>
  </partition>
 
  <partition>
    <partition-name>lov</partition-name>
    <feature>AdfUIInputPopup</feature>
    <feature>AdfRichInputComboboxListOfValues</feature>
    <feature>AdfRichInputListOfValues</feature>
  </partition>
 
  <partition>
    <partition-name>media</partition-name>
    <feature>AdfRichMedia</feature>
  </partition>
 
  <partition>
    <partition-name>message</partition-name>
    <feature>AdfUIMessage</feature>
    <feature>AdfUIMessages</feature>
    <feature>AdfRichMessage</feature>
    <feature>AdfRichMessages</feature>
  </partition>
 
  <partition>
    <partition-name>menu</partition-name>
    <feature>AdfRichCommandMenuItem</feature>
    <feature>AdfRichGoMenuItem</feature>
    <feature>AdfRichMenuBar</feature>
    <feature>AdfRichMenu</feature>
  </partition>
 
  <partition>
    <partition-name>nav</partition-name>
    <feature>AdfUINavigationPath</feature>
    <feature>AdfUINavigationLevel</feature>
    <feature>AdfRichBreadCrumbs</feature>
    <feature>AdfRichCommandNavigationItem</feature>
    <feature>AdfRichNavigationPane</feature>
  </partition>
 
  <partition>
    <partition-name>note</partition-name>
    <feature>AdfRichNoteWindow</feature>
  </partition>
 
  <partition>
    <partition-name>poll</partition-name>
    <feature>AdfUIPoll</feature>
    <feature>AdfRichPoll</feature>
  </partition>
 
  <partition>
    <partition-name>progress</partition-name>
    <feature>AdfUIProgress</feature>
    <feature>AdfRichProgressIndicator</feature>
  </partition>
 
  <partition>
    <partition-name>print</partition-name>
    <feature>AdfShowPrintablePageBehavior</feature>
  </partition>
 
  <partition>
    <partition-name>scrollComponentIntoView</partition-name>
    <feature>AdfScrollComponentIntoViewBehavior</feature>
  </partition>
 
  <partition>
    <partition-name>query</partition-name>
    <feature>AdfUIQuery</feature>
    <feature>AdfRichQuery</feature>
    <feature>AdfRichQuickQuery</feature>
  </partition>
 
  <partition>
    <partition-name>region</partition-name>
    <feature>AdfUIRegion</feature>
    <feature>AdfRichRegion</feature>
  </partition>
 
  <partition>
    <partition-name>reset</partition-name>
    <feature>AdfUIReset</feature>
    <feature>AdfRichResetButton</feature>
  </partition>
 
  <partition>
    <partition-name>rte</partition-name>
    <feature>AdfRichTextEditor</feature>
    <feature>AdfRichTextEditorInsertBehavior</feature>
  </partition>
 
  <partition>
    <partition-name>select</partition-name>
 
    <feature>AdfRichSelectBooleanCheckbox</feature>
    <feature>AdfRichSelectBooleanRadio</feature>
    <feature>AdfRichSelectManyCheckbox</feature>
    <feature>AdfRichSelectOneRadio</feature>
  </partition>
 
  <partition>
    <partition-name>selectmanychoice</partition-name>
    <feature>AdfRichSelectManyChoice</feature>
  </partition>
 
  <partition>
    <partition-name>selectmanylistbox</partition-name>
    <feature>AdfRichSelectManyListbox</feature>
  </partition>
 
  <partition>
    <partition-name>selectonechoice</partition-name>
    <feature>AdfRichSelectOneChoice</feature>
  </partition>
 
  <partition>
    <partition-name>selectonelistbox</partition-name>
    <feature>AdfRichSelectOneListbox</feature>
  </partition>
 
  <partition>
    <partition-name>shuttle</partition-name>
    <feature>AdfUISelectOrder</feature>
    <feature>AdfRichSelectManyShuttle</feature>
    <feature>AdfRichSelectOrderShuttle</feature>
  </partition>
 
  <partition>
    <partition-name>slide</partition-name>
    <feature>AdfRichInputNumberSlider</feature>
    <feature>AdfRichInputRangeSlider</feature>
  </partition>
 
  <partition>
    <partition-name>spin</partition-name>
    <feature>AdfRichInputNumberSpinbox</feature>
  </partition>
 
  <partition>
    <partition-name>status</partition-name>
    <feature>AdfRichStatusIndicator</feature>
  </partition>
 
  <partition>
    <partition-name>stretch</partition-name>
    <feature>AdfRichDecorativeBox</feature>
    <feature>AdfRichPanelSplitter</feature>
    <feature>AdfRichPanelStretchLayout</feature>
    <feature>AdfRichPanelDashboard</feature>
    <feature>AdfPanelDashboardBehavior</feature>
    <feature>AdfDashboardDropTarget</feature>
  </partition>
 
  <partition>
    <partition-name>tabbed</partition-name>
    <feature>AdfUIShowOne</feature>
    <feature>AdfRichPanelTabbed</feature>
  </partition>
 
  <partition>
    <partition-name>table</partition-name>
    <feature>AdfUIIterator</feature>
    <feature>AdfUITable</feature>
    <feature>AdfUITable2</feature>
    <feature>AdfUIColumn</feature>
    <feature>AdfRichColumn</feature>
    <feature>AdfRichTable</feature>
  </partition>
 
  <partition>
    <partition-name>toolbar</partition-name>
    <feature>AdfRichCommandToolbarButton</feature>
    <feature>AdfRichToolbar</feature>
  </partition>
 
  <partition>
    <partition-name>toolbox</partition-name>
    <feature>AdfRichToolbox</feature>
  </partition>
 
  <partition>
    <partition-name>train</partition-name>
    <feature>AdfUIProcess</feature>
    <feature>AdfRichCommandTrainStop</feature>
    <feature>AdfRichTrainButtonBar</feature>
    <feature>AdfRichTrain</feature>
  </partition>
 
  <partition>
    <partition-name>tree</partition-name>
    <feature>AdfUITree</feature>
    <feature>AdfUITreeTable</feature>
    <feature>AdfRichTree</feature>
    <feature>AdfRichTreeTable</feature>
  </partition>
 
  <!--
    Some components which typically do have client-side representation,
    but small enough that we might as well download in a single partition
    in the event that any of these are needed.
  -->
  <partition>
    <partition-name>uncommon</partition-name>
    <feature>AdfRichGoButton</feature>
    <feature>AdfRichIcon</feature>
    <feature>AdfRichImage</feature>
    <feature>AdfRichOutputText</feature>
    <feature>AdfRichPanelGroupLayout</feature>
    <feature>AdfRichSeparator</feature>
    <feature>AdfRichSpacer</feature>
    <feature>AdfRichGoLink</feature>
  </partition>
 
  <partition>
    <partition-name>eum</partition-name>
    <feature>AdfEndUserMonitoring</feature>
  </partition>
 
  <partition>
    <partition-name>ads</partition-name>
    <feature>AdfActiveDataService</feature>
  </partition>
 
  <partition>
    <partition-name>automation</partition-name>
    <feature>AdfAutomationTest</feature>
  </partition>
 
</partitions>

A.9.4 What Happens at Runtime: JavaScript Partitioning

ADF Faces loads the library partitioning configuration files at application initialization time. First, ADF Faces searches for all adf-js-features.xml files in the META-INF directory and loads all that are found (including the ADF Faces default feature configuration file).

For the partition configuration file, ADF Faces looks for a single file named adf-js-partitions.xml in the WEB-INF directory. If no such file is found, the ADF Faces default partition configuration is used.

During the render traversal, ADF Faces collects information about which JavaScript features are required by the page. At the end of the traversal, the complete set of JavaScript features required by the (rendered) page contents is known. Once the set of required JavaScript features is known, ADF Faces uses the partition configuration file to map this set of features to the set of required partitions. Given the set of required partitions, the HTML <script> references to these partitions are rendered just before the end of the HTML document.