Chapter 21. JavaServer Faces (JSF) Configuration

21.1. Multi-JSF Implementation of JavaServer Faces

The JavaServer Faces (JSF) subsystem allows you to install multiple JSF implementations on the same JBoss EAP server instance. In particular, you can install any version of Sun Mojarra or Apache MyFaces that implements JSF specification 2.1, or later.

21.1.1. Installing a JSF Implementation

The following procedure describes how to manually install a new JSF implementation and make it the default implementation.

  1. Add the JSF implementation JAR file.
  2. Add the JSF API JAR file.
  3. Add the JSF injection JAR file.
  4. Add the commons-digester JAR file if you are installing MyFaces.
  5. Set the default JSF implementation.
Add the JSF Implementation JAR File

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the JSF implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p com/sun/jsf-impl/JSF_IMPL_NAME-JSF_VERSION
    Note

    For example, replace JSF_IMPL_NAME-JSF_VERSION with mojarra-2.2.11 for Mojarra 2.2.11.

  2. Copy the JSF implementation JAR file to the JSF_IMPL_NAME-JSF_VERSION/ subdirectory.
  3. In the JSF_IMPL_NAME-JSF_VERSION/ subdirectory, create a module.xml file similar to this Mojarra template or this MyFaces template. If you use a template, be sure to use appropriate values for the replaceable variables noted.
Add the JSF API JAR File

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the JSF implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p javax/faces/api/JSF_IMPL_NAME-JSF_VERSION
  2. Copy the JSF API JAR file to the JSF_IMPL_NAME-JSF_VERSION/ subdirectory.
  3. In the JSF_IMPL_NAME-JSF_VERSION/ subdirectory, create a module.xml file similar to this Mojarra template or this MyFaces template. If you use a template, be sure to use appropriate values for the replaceable variables noted.
Add the JSF Injection JAR File

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the JSF implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p org/jboss/as/jsf-injection/JSF_IMPL_NAME-JSF_VERSION
  2. Copy the wildfly-jsf-injection and weld-core-jsf JAR files from EAP_HOME/modules/system/layers/base/org/jboss/as/jsf-injection/main/ to the JSF_IMPL_NAME-JSF_VERSION/ subdirectory.
  3. In the JSF_IMPL_NAME-JSF_VERSION/ subdirectory, create a module.xml file similar to this Mojarra template or this MyFaces template. If you use a template, be sure to use appropriate values for the replaceable variables noted.
Add the commons-digester JAR File for MyFaces

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the commons-digester JAR: 

    $ cd EAP_HOME/modules/
$ mkdir -p org/apache/commons/digester/main
  2. Download the commons-digester JAR file and copy it to the main/ subdirectory.
  3. In the main/ subdirectory, create a module.xml file similar to this template. If you use the template, be sure to use appropriate values for the replaceable variables noted.
Set the Default JSF Implementation

  1. Run the following management CLI command to set the new JSF implementation as the default implementation: 

    /subsystem=jsf:write-attribute(name=default-jsf-impl-slot,value=JSF_IMPL_NAME-JSF_VERSION)
  2. Restart the JBoss EAP server for the changes to take effect.

21.1.2. Multi-JSF Implementation Support

JBoss EAP 7.2 ships with a single JSF implementation, a JSF 2.3 implementation based on Mojarra.

Multi-JSF allows the installation of multiple JSF implementations and versions on the same JBoss EAP server. The goal is to allow the use of any of the JSF implementations, MyFaces or Mojarra, and any version of those implementations from JSF 2.1 and beyond. Multi-JSF provides an implementation that is fully integrated with the container, which allows more efficient annotation processing, lifecycle handling, and other integration advantages.

21.1.2.1. Working of the Multi-JSF Implementation

The way multi-JSF works is that for each JSF version, a new slot is created in the modules path under com.sun.jsf-impl, javax.faces.api, and org.jboss.as.jsf-injection. When the jsf subsystem is started, it scans the module path to find all the installed JSF implementations. When the jsf subsystem deploys a web application containing the specified context parameter, it adds the slotted modules to the deployment.

For example, to indicate that the JSF application should use MyFaces 2.2.12, assuming MyFaces 2.2.12 has been installed on the server, the following context parameter must be added: 

<context-param>
   <param-name>org.jboss.jbossfaces.JSF_CONFIG_NAME</param-name>
   <param-value>myfaces-2.2.12</param-value>
</context-param>

21.1.2.2. Changing the Default JSF Implementation

The multi-JSF feature includes the default-jsf-impl-slot attribute in the jsf subsystem. This attribute allows you to change the default JSF implementation, as described in the following procedure:

  1. Use the write-attribute command to set the value of the default-jsf-impl-slot attribute to one of the active JSF implementations: 

    /subsystem=jsf:write-attribute(name=default-jsf-impl-slot,value=JSF_IMPLEMENTATION)

  2. Restart the JBoss EAP server for the change to take effect. 

    reload

To see which JSF implementations are installed, you can execute the list-active-jsf-impls operation. 

/subsystem=jsf:list-active-jsf-impls
{
    "outcome" => "success",
    "result" => [
        "myfaces-2.1.12",
        "mojarra-2.2.0-m05",
        "main"
    ]
}

21.2. Disallowing DOCTYPE Declarations

You can use the following management CLI commands to disallow DOCTYPE declarations in JSF deployments: 

/subsystem=jsf:write-attribute(name=disallow-doctype-decl,value=true)
reload

You can override this setting for a particular JSF deployment by adding the com.sun.faces.disallowDoctypeDecl context parameter to the deployment’s web.xml file: 

<context-param>
  <param-name>com.sun.faces.disallowDoctypeDecl</param-name>
  <param-value>false</param-value>
</context-param>