This document is for AS6 Milestone 4.  See the JSF on AS6 Guide for details on AS6 Final.

New JSF Deployer (introduced in AS6 M4)

JavaServer Faces integration for JBoss AS6 has been re-written to take advantage of the JBoss deployer architecture.  So instead of having JSF integrated through Tomcat, it is now an independent deployer that adds JSF to your WAR when needed.

How the JSF Deployer decides to add JSF to your WAR

There are several conditions that signal the JSF deployer to add a JSF configuration to your WAR:

• A FacesServlet is declared in WEB-INF/web.xml or a web-fragment.xml
• A faces-config.xml file is found in WEB-INF
• A faces-config.xml file is found in META-INF of some jar in WEB-INF/lib
• A *.faces-config.xml file is found in META-INF of some jar in WEB-INF/lib
• The javax.faces.CONFIG_FILES context param is declared in WEB-INF/web.xml or  a web-fragment.xml.
• The org.jboss.jbossfaces.JSF_CONFIG_NAME context param is declared in WEB-INF/web.xml or a web-fragment.xml
• "alwaysAddJSF" is set to true in jsf-integration-deployer-jboss-beans.xml.

Also, if javax.faces.webapp.FacesServlet is not already declared, it will automatically add an instance of this servlet with the following mappings:

• /faces/*
• *.jsf
• *.faces

Using a Non-standard FacesServlet

Though it is not recommended, some applications use a non-standard servlet to control JSF services.  You can configure the JSF Deployer to recognize a non-standard servlet as a JSF application.  Edit the file <JBOSS_CONFIG>/deployers/jsf.deployer/META-INF/jsf-integration-deployer-jboss-beans.xml and add your servlet to the facesServlets property:

{code:xml}<bean name="JSFImplManagementDeployer">





    <!--
      * Specify the servlet classes that signal this deployer to add JSF to a WAR. 
    -->
    <property name="facesServlets">
       <collection elementClass="java.lang.String">
          <value>javax.faces.webapp.FacesServlet</value>          
          <value>org.foo.MyWrapperFacesServlet</value>
       </collection>
    </property>{code}

How to Bundle Your Own JSF Implementation

You can bundle your own JSF implementation with your WAR and tell the JSF Deployer to ignore that WAR.  This is not recommended, but it can sometimes ease migration of your application from a non-JEE container such as Tomcat or Jetty.  Just add this to your web.xml:

  {code:xml}  <context-param>
      <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name>
      <param-value>true</param-value>
  </context-param>{code}

This context-param was available in earlier versions of JBoss AS.  However, it only worked when bundling MyFaces and when using the default classloader configuration.  Now in AS6 you can use this context-param any time you want to bundle your own JSF impl.

Changing the JSF Configuration for your WAR

JBoss AS ships with two JSF Implementations, Mojarra 1.2 and Mojarra 2.0.  By default, JSF applications will use Mojarra 2.0.  While most JSF 1.2 applications will run on JSF 2.0 without changes, there are a few rare instances where this is not the case.  Also, when migrating to JBoss AS6 from AS5, you might want to first use the older JSF implementation and "ease into" the world of JSF 2.0 later.

If you look at the <JBOSS_CONFIG>/deployers/jsf.deployer directory you will see the JSF configurations that ship with JBoss AS6.  To tell your application to use another JSF configuration, add this to your web.xml:

{code:xml}   <context-param>
      <param-name>org.jboss.jbossfaces.JSF_CONFIG_NAME</param-name>
      <param-value>Mojarra-1.2</param-value>
   </context-param>{code}

Adding a New JSF Configuration

A JSF Configuration consists of jars and a web.xml file.  When a JSF Configuration is added to a WAR by the JSF Deployer, the jars are added to the classpath and the elements in the web.xml file are activated.  To add your own JSF Confguration, just create the directory structure below.  This is usually done in the jsf.deployer directory:

jsf.deployer/MyJSFConfig/jsf-libs

jsf.deployer/MyJSFConfig/META-INF

Place your jar files in /jsf-libs and place your web.xml in /META-INF.  When your JSF Configuration is activated for a WAR, all jars in the jsf-libs directory will be added to the classpath.  So not only can you  use this for a new JSF implementation, you can also add things like JSF component libraries.

The elements in your META-INF/web.xml file will also be added to your WAR.  This can help you configure the JSF implementation and component libraries.  However, note that only a few web.xml elements are allowed in this file.  These elements are servlet, servlet-mapping, filter, filter-mapping, listener, and context-param.  All other web.xml elements are currently ignored, but we may support more in the future.

Activating a New JSF Configuration

To allow the JSF Deployer to recognize your JSF Configuration, you will need to edit <JBOSS_CONFIG>/deployers/jsf.deployer/META-INF/jsf-integration-deployer-jboss-beans.xml:

{code:xml}<property name="jsfConfigurations">

  <map keyClass="java.lang.String" valueClass="java.lang.String">

    <entry>

      <key>Mojarra-1.2</key>

      <value>${jboss.server.home.url}deployers/jsf.deployer/Mojarra-1.2</value>

    </entry>

    <entry>

      <key>Mojarra-2.0</key>

      <value>${jboss.server.home.url}deployers/jsf.deployer/Mojarra-2.0</value>

    </entry>
 
    <entry>

       <key>MyJSFConfig</key>

        <value>${jboss.server.home.url}deployers/jsf.deployer/MyJSFConfig</value>

     </entry>

  </map>   

</property>{code}

{code:xml}  <bean name="JSFUrlIntegrationDeployer-MyJSFConfig">
    <property name="JSFImplName">
      <value>MyJSFConfig</value>
    </property>
    <property name="JSFImplManagementDeployer">
      <inject bean="JSFImplManagementDeployer"/>
    </property>
  </bean>{code}