Chapter 21. Jakarta Server Faces Configuration

21.1. Multiple Jakarta Server Faces implementation of Jakarta Server Faces

The jsf subsystem allows you to install multiple Jakarta Server Faces implementations on the same JBoss EAP server instance. You can install a version of Sun Mojarra or Apache MyFaces that implements Jakarta Server Faces specification 2.3, or later.

21.1.1. Installing a Jakarta Server Faces Implementation

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

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

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the Jakarta Server Faces implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p com/sun/jsf-impl/IMPL_NAME-VERSION
    Note

    For example, replace IMPL_NAME-VERSION with a version of Mojarra that supports the Jakarta Server Faces specification 2.3, or later.

  2. Copy the Jakarta Server Faces implementation JAR file to the IMPL_NAME-VERSION/ subdirectory.
  3. In the IMPL_NAME-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 Jakarta Server Faces API JAR File

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the Jakarta Server Faces implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p javax/faces/api/IMPL_NAME-VERSION
  2. Copy the Jakarta Server Faces API JAR file to the IMPL_NAME-VERSION/ subdirectory.
  3. In the IMPL_NAME-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 Jakarta Server Faces Injection JAR File

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory for the Jakarta Server Faces implementation: 

    $ cd EAP_HOME/modules/
$ mkdir -p org/jboss/as/jsf-injection/IMPL_NAME-VERSION

  2. Follow the instructions outlined in the Patching and Upgrading guide to download the latest cumulative patch for your JBoss EAP instance. Next, complete either of the following steps:

    • If you have not applied the patch updates to the server, then 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 IMPL_NAME-VERSION/ subdirectory.
    • If you have applied the patch updates to the server, then copy the wildfly-jsf-injection and weld-core-jsf JAR files from the latest patch updates directory to the IMPL_NAME-VERSION/ subdirectory. For example, EAP_HOME/modules/system/layers/base/.overlays/layer-base-jboss-eap-7.4.z.CP/org/jboss/as/jsf-injection, where z is the latest version number.
  3. In the IMPL_NAME-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 Jakarta Server Faces Implementation

  1. Run the following management CLI command to set the new Jakarta Server Faces implementation as the default implementation: 

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

21.1.2. Multi-Jakarta Server Faces Implementation Support

JBoss EAP 7.4 ships with a single Jakarta Server Faces implementation, Jakarta Server Faces 2.3 implementation based on Mojarra.

Multi-Jakarta Server Faces allows the installation of multiple Jakarta Server Faces implementations and versions on the same JBoss EAP server. The goal is to allow the use of any of the Jakarta Server Faces implementations, MyFaces or Mojarra, and any version of those implementations from Faces 2.1 and beyond, and Jakarta Server Faces 2.3 and beyond. Multi-Jakarta Server Faces 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-Jakarta Server Faces Implementation

The way multi-Jakarta Server Faces works is that for each Jakarta Server Faces 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 Jakarta Server Faces 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 Jakarta Server Faces 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 Jakarta Server Faces Implementation

The multi-Jakarta Server Faces feature includes the default-jsf-impl-slot attribute in the jsf subsystem. This attribute allows you to change the default Jakarta Server Faces 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 Jakarta Server Faces 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 Jakarta Server Faces 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 Jakarta Server Faces deployments: 

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

You can override this setting for a particular Jakarta Server Faces 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>