Design of AS7 multi-JSF feature

Note: For AS7, this feature was considered experimental.  It has been much improved in WildFly.  See Design of WildFly Multi-JSF feature for details.

 

About multi-JSF

Currently, AS7 ships with two JSF implementations, a JSF 2.1 implementation and a JSF 1.2 implementation.  A web application can select which implementation is used by including a context param in web.xml.  By default, it uses the JSF 2.1 imlementation.

 

"multi-JSF" allows installation of multiple JSF implementations (and versions) on the same AS7 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 the experimental JSF 2.2 versions.  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.

 

How it works

The way multi-JSF will work 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 milestone of Mojarra 2.2:

<context-param>
   <param-name>org.jboss.jbossfaces.JSF_CONFIG_NAME</param-name>
   <param-value>mojarra-2.2.0-m05</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-mojarra-2.2.0-m05.cli

 

The install script inside the archive looks like this:

module add --name=javax.faces.api --slot=mojarra-2.2.0-m05 --resources=jsf-api-2.2.0-m05.jar --module-xml=mojarra-api-module.xml

module add --name=com.sun.jsf-impl --slot=mojarra-2.2.0-m05 --resources=jsf-impl-2.2.0-m05.jar --module-xml=mojarra-impl-module.xml

module add --name=org.jboss.as.jsf-injection --slot=mojarra-2.2.0-m05 --resources=jboss-as-jsf-injection-7.2.0.Alpha1-SNAPSHOT.jar --module-xml=injection-module.xml

 

How the CLI deployment archives are created

A CLI deployment archive for a JSF implementation/version is created using a standalone maven project you can download from GitHub and run.  To create an archive with the project, you  call it like this:

 

mojarra example

mvn -Djsf-version=2.2.0-m05 -Pmojarra clean assembly:single

myfaces example

mvn -Djsf-version=2.1.8 -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 AS7

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

multi-jsf.png

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="mojarra-2.2.0-m05"/>

 

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.8",
        "mojarra-2.2.0-m05",
        "1.2",
        "main"
    ]
}

Demo

I've attached a copy of install-mojarra-2.2.0-m05.cli and install-myfaces-2.1.8.cli.   You can use these *.cli files with the latest nightly build of AS7 (jboss-as-7.2.0.Alpha1-SNAPSHOT).