About Multi-JSF

WildFly ships with a single JSF implementation, a JSF 2.2 implementation based on Mojarra.

"Multi-JSF" allows installation of multiple JSF implementations (and versions) on the same WildFly server.  The goal is to allow use of any JSF implementation (MyFaces or Mojarra) and any version of those implementation from JSF 1.2 all the way up to  JSF 2.2 and beyond.  This is far superior to the old WAR_BUNDLES_JSF_IMPL method because JSF jars do not need to be bundled with the webapp.  More importantly, Multi-JSF provides an implementation that is fully integrated with the container.  This means more efficient annotation processing, lifecycle handling, and other integration advantages.

If you are just looking for a quick tutorial on installing a different JSF version into WildFly, try Steps to add a new JSF implementation or version to WildFly.

If you are looking for an even quicker tutorial that installs a default version of MyFaces, try Steps to add MyFaces support to WildFly

How it works

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 app containing the specified context param, it adds the slotted modules to the deployment.

Here is an example of the context param for the latest version of MyFaces:

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

How a JSF implementation is installed

A single JSF implementation is installed using a CLI deployment archive.  This archive includes the required jars and module.xml files.  It also includes CLI scripts for installing/uninstalling the JSF impls using the CLI module command.  You execute the installation archive like this:

[standalone@localhost:9999 /] deploy <local path to archive>/install-myfaces-2.1.12.cli

The install script inside the archive looks like this:

module add --name=javax.faces.api --slot=myfaces-2.1.12 --resources=myfaces-api-2.1.12.jar --module-xml=myfaces-api-module.xml
module add --name=com.sun.jsf-impl --slot=myfaces-2.1.12 --resources=myfaces-impl-2.1.12.jar --module-xml=myfaces-impl-module.xml
module add --name=org.jboss.as.jsf-injection --slot=myfaces-2.1.12 --module-xml=injection-module.xml
module add --name=org.apache.commons.digester --slot=main --resources=commons-digester-1.8.jar --module-xml=myfaces-digester-module.xml

Note: If the digester module already exists you will get a harmless warning when you execute the script.

How the CLI deployment archives are created

A CLI deployment archive for a JSF implementation/version is created using a maven project that is part of the WildFly build.  The project can be executed at <WILDFLY_SOURCE_ROOT>/jsf/multi-jsf-installer.

To create an archive with the project, you  call it like this:

mojarra 1.2 example

mvn -Djsf-version=1.2_15 -Pmojarra-1.2 clean assembly:single

mojarra 2.x example

mvn -Djsf-version=2.1.23 -Pmojarra-2.x clean assembly:single

myfaces example

mvn -Djsf-version=2.1.12 -Pmyfaces clean assembly:single

This pulls in the JSF resources and creates the install/uninstall scripts. It is all bundled together in an archive (zip) file that must be manually renamed with a .cli extension.

How to change the default JSF implementation in WildFly

The Multi-JSF feature adds a new attribute to the JSF subsystem.  default-jsf-impl-slot allows you to change the default JSF implementation.  You just need to issue a write-attribute command and set the value to one of the active impls.  Then restart WildFly.

Alternatively, you can set this in your configuration file, such as standalone.xml:

<subsystem xmlns="urn:jboss:domain:jsf:1.0" default-jsf-impl-slot="myfaces-2.1.12"/>

To see which JSF impls 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"
    ]
}