Skip Headers

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

Previous | Next |

# A.8 web.xml

This section describes Oracle ADF configuration settings specific to the standard `web.xml` deployment descriptor file.

In JDeveloper when you create a project that uses JSF technology, a starter `web.xml` file with default settings is created for you in `/WEB-INF`. To edit the file, double-click web.xml in the Application Navigator to open it in the XML editor.

The following must be configured in `web.xml` for all applications that use JSF and ADF Faces:

- JSF servlet and mapping—The servlet `javax.faces.webapp.FacesServlet` that manages the request processing lifecycle for web applications utilizing JSF to construct the user interface.

- ADF Faces filter and mapping—A servlet filter to ensure that ADF Faces is properly initialized by establishing a `AdfFacesContext` object. This filter also processes file uploads.

- ADF resource servlet and mapping—A servlet to serve up web application resources (images, style sheets, JavaScript libraries) by delegating to a `ResourceLoader`.

The JSF servlet and mapping configuration settings are automatically added to the starter `web.xml` file when you first create a JSF project. When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the configuration settings for ADF Faces filter and mapping, and resource servlet and mapping``.

Example A-10 Configuring web.xml for ADF Faces and JSF

    <?xml version = '1.0' encoding = 'windows-1252'?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
      <description>Empty web.xml file for Web Application</description>

      <!-- Installs the ADF Faces Filter -- >
      <filter>
        <filter-name>adfFaces</filter-name>
        <filter-class>oracle.adf.view.faces.webapp.AdfFacesFilter</filter-class>
      </filter>

      <!-- Adds the mapping to ADF Faces Filter -- >
      <filter-mapping>
        <filter-name>adfFaces</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
      </filter-mapping>

      <!-- Maps the JSF servlet to a symbolic name -->
      <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
      </servlet>

      <!-- Maps ADF Faces ResourceServlet to a symbolic name -- >
      <servlet>
        <servlet-name>resources</servlet-name>
        <servlet-class>oracle.adf.view.faces.webapp.ResourceServlet</servlet-class>
      </servlet>

      <!-- Maps URL pattern to the JSF servlet's symbolic name -->
      <!-- You can use either a path prefix or extension suffix pattern -->
      <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
      </servlet-mapping>

      <!-- Maps URL pattern to the ResourceServlet's symbolic name -->
      <servlet-mapping>
        <servlet-name>resources</servlet-name>
        <url-pattern>/adf/*</url-pattern>
      </servlet-mapping>
    ...
    </web-app>

Section A.8.1.1 through Section A.8.1.7 detail the context parameters you could use in `web.xml` when you work with JSF and ADF Faces.

## A.8.1 Tasks Supported by the web.xml File

The following JSF and ADF Faces tasks are supported by the `web.xml` file.

### A.8.1.1 Configuring for State Saving

You can specify the following state-saving context parameters:

- `javax.faces.STATE_SAVING_METHOD`—Specifies where to store the application's view state. By default this value is `server`, which stores the application's view state on the server. If you wish to store the view state on the browser client, set this value to `client`. JDeveloper then automatically uses token-based client-side state saving (see `oracle.adf.view.faces.CLIENT_STATE_METHOD` below). You can specify the number of tokens to use instead of using the default number of 15 (see `oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS` below).

- `oracle.adf.view.faces.CLIENT_STATE_METHOD`—Specifies the type of client-side state saving to be used when client-side state saving is enabled. The values are:

  - `token`—(Default) Stores the page state in the session, but persists a token to the client. The simple token, which identifies a block of state stored back on the `HttpSession, is stored on the client`. This enables ADF Faces to disambiguate multiple appearances of the same page. Failover `HttpSession` is supported. This matches the default server-side behavior that will be provided in JSF 1.2.

  - `all`—Stores all state on the client in a (potentially large) hidden form field. This matches the client-side state saving behavior in JSF 1.1, but it is useful for developers who do not want to use `HttpSession`.

- `oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS`—Specifies how many tokens should be stored at any one time per user. The default is 15. When this value is exceeded, the state is lost for the least recently viewed pages, which affects users who actively use the Back button or who have multiple windows opened at the same time. If you're building HTML applications that rely heavily on frames, you would want to increase this value.

Example A-11 shows part of a `web.xml` file that contains state-saving parameters.

Example A-11 Context Parameters for State Saving in web.xml

    <context-param>
      <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
      <param-value>client</param-value>
    </context-param>

    <context-param>
      <param-name>oracle.adf.view.faces.CLIENT_STATE_MAX_TOKENS</param-name>
      <param-value>20</param-value>
    </context-param>

### A.8.1.2 Configuring for Application View Caching

You can specify the following application view caching context parameter:

- `oracle.adf.view.faces.USE_APPLICATION_VIEW_CACHE`—Specifies whether to enable the application view caching feature. When application view caching is enabled, the first time a page is viewed by any user, ADF Faces caches the initial page state at an application level. Subsequently, all users can reuse the page's cached state coming and going, significantly improving application performance. Default is `false`.

Example A-12 shows part of a `web.xml` file that contains the application view caching parameter.

Example A-12 Context Parameters for Application View Caching in web.xml

    <context-param>
      <param-name>oracle.adf.view.faces.USE_APPLICATION_VIEW_CACHE</param-name>
      <param-value>true</param-value>
    </context-param>

### A.8.1.3 Configuring for Debugging

You can specify the following debugging context parameters:

- `oracle.adf.view.faces.DEBUG_JAVASCRIPT`—ADF Faces by default obfuscates the JavaScript it delivers to the client, as well as strip comments and whitespace. This dramatically reduces the size of the ADF Faces JavaScript download, but also makes it tricky to debug the JavaScript. Set to `true` to turn off the obfuscation during application development. Set to `false` for application deployment.

- `oracle.adf.view.faces.CHECK_FILE_MODIFICATION`—By default this parameter is `false`. If it is set to `true`, ADF Faces will automatically check the modification date of your JSPs, and discard saved state when they change. When set to `true`, this makes development easier, but adds overhead that should be avoided when your application is deployed. Set to `false` for application deployment.

  For testing and debugging in JDeveloper's embedded OC4J, you don't need to explicitly set this parameter to `true` because ADF Faces automatically detects the embedded OC4J and runs with the file modification checks enabled.

Example A-13 shows part of a `web.xml` file that contains debugging parameters.

Example A-13 Context Parameters for Debugging in web.xml

    <context-param>
      <param-name>oracle.adf.view.faces.DEBUG_JAVASCRIPT</param-name>
      <param-value>true</param-value>
    </context-param>

    <context-param>
      <param-name>oracle.adf.view.faces.CHECK_FILE_MODIFICATION</param-name>
      <param-value>true</param-value>
    </context-param>

### A.8.1.4 Configuring for File Uploading

You can specify the following file upload context parameters:

- `oracle.adf.view.faces.UPLOAD_TEMP_DIR`—Specifies the directory where temporary files are to be stored during file uploading. The default is the user's temporary directory.

- `oracle.adf.view.faces.UPLOAD_MAX_DISK_SPACE`—Specifies the maximum amount of disk space that can be used in a single request to store uploaded files. The default is 2000K.

- `oracle.adf.view.faces.UPLOAD_MAX_MEMORY`—Specifies the maximum amount of memory that can be used in a single request to store uploaded files. The default is 100K.

Example A-14 shows part of a `web.xml` file that contains file upload parameters.

Example A-14 Context Parameters for File Uploading in web.xml

    <context-param>
      <param-name>oracle.adf.view.faces.UPLOAD_TEMP_DIR</param-name>
      <param-value>/tmp/Adfuploads</param-value>
    </context-param>

    <context-param>
      <param-name>oracle.adf.view.faces.UPLOAD_MAX_DISK_SPACE</param-name>
      <param-value>5120000</param-value>
    </context-param>

    <context-param>
      <param-name>oracle.adf.view.faces.UPLOAD_MAX_MEMORY</param-name>
      <param-value>512000</param-value>
    </context-param>

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

For information about file uploading, see Section 11.6, "Providing File Upload Capability".

### A.8.1.5 Configuring for ADF Model Binding

When you use ADF data controls to build web pages, the following must be configured in `web.xml`:

- ADF binding filter—A servlet filter to create the `ADFContext`, which contains context information about ADF, including the security context and the environment class that contains the request and response object. ADF applications use this filter to preprocess any HTTP requests that may require access to the binding context.

- Servlet context parameter for the application binding container—Specifies which CPX file the filter reads at runtime to define the application binding context. For information about CPX files, see Section 5.3, "Working with the DataBindings.cpx File".

In JDeveloper when you first use the Data Control Palette to build your databound JSF page, the ADF data binding configuration settings are automatically added to the `web.xml` file.

Example A-15 shows part of a `web.xml` file that contains ADF Model binding settings. For more information about the Data Control Palette and binding objects, see Chapter 5, "Displaying Data in a User Interface".

Example A-15 ADF Model Binding Configuration Settings in web.xml

    <context-param>
      <param-name>CpxFileName</param-name>
      <param-value>view.DataBindings</param-value>
    </context-param>

    <filter>
      <filter-name>adfBindings</filter-name>
      <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
    </filter>

    <filter-mapping>
      <filter-name>adfBindings</filter-name>
      <url-pattern>*.jsp</url-pattern>
    </filter-mapping>

    <filter-mapping>
      <filter-name>adfBindings</filter-name>
      <url-pattern>*.jspx</url-pattern>
    </filter-mapping>

### A.8.1.6 Other Context Configuration Parameters for JSF

Other optional, application-wide parameters for JSF are:

- `javax.faces.CONFIG_FILES`—Specifies paths to JSF application configuration resource files. Use a comma-separated list of application-context relative paths for the value (see Example A-16). You need to set this parameter if you use more than one JSF configuration file in your application, as described in Section A.10.1.

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

- `javax.faces.LIFECYCLE_ID`—Specifies a lifecycle identifier other than the default set by the `javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE` constant.

Example A-16 Configuring for Multiple JSF Configuration Files in web.xml

    <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>

### A.8.1.7 What You May Need to Know

If you have multiple filters for your application, make sure they are listed in `web.xml` in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.