JBoss.orgCommunity Documentation

Chapter 3. Deploying Your JSF Applications

3.1. The JSF Deployer
3.2. How the JSF Deployer Recognizes your JSF Application
3.3. Auto-adding of the JSF FacesServlet
3.4. Using a Non-standard FacesServlet
3.5. Bundling JSF Inside Your WAR
3.6. Changing the JSF Configuration for your WAR
3.7. Adding a New JSF Configuration
3.8. Activating a New JSF Configuration

In this chapter, we cover all the deployment options for your JSF applications.

JSF integration for JBoss AS6 has been re-written to take advantage of the JBoss deployer architecture. So instead of having JSF tightly coupled to the Servlet container, it is now an independent deployer that adds JSF to your WAR when needed.

The JSF Deployer is located in the deployers/jsf.deployer directory. By default, JBoss AS6 ships with three JSF implementations located in the jsf.deployer/Mojarra-2.0, jsf.deployer/MyFaces-2.0, and jsf.deployer/Mojarra-1.2 directories. These directories contain JSF Configurations.

Inside the jsf.deployer/META-INF directory you will find a file called jsf-integration-deployer-jboss-beans.xml. You can use this file for advanced configuration of the deployer, which we will describe in some of the sections that follow.

In past versions of JBoss AS, every web application had a JSF implementation and its supporting jars placed on its classpath. In addition, every web application went through at least some of the JSF initialization process - even when it didn't use JSF. With JBoss AS6, JSF jars are only added to the classpath when needed.

When a web application is deployed, the JSF Deployer determines if it is a JSF application. It recognizes a web application if any of the following are true:

If the JSF Deployer determines that a WAR is a JSF application, but javax.faces.webapp.FacesServlet is not already declared as a servlet, the deployer will add an instance of this servlet for you.

If it adds the FacesServlet, it will also add the following mappings for it:

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 jsf.deployer/META-INF/jsf-integration-deployer-jboss-beans.xml and add your servlet to the facesServlets property.

In this example, we add org.foo.MyWrapperFacesServlet. When an application is deployed with this servlet it will be recognized as a JSF application.

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

Some containers such as Tomcat 6 require you to bundle a JSF implementation in the WEB-INF/lib directory of your WAR. If you would like to use such a WAR with JBoss AS6 then you can signal the JSF Deployer to ignore your WAR and let it use the bundled JSF version.

To do that, just specify the WAR_BUNDLES_JSF context param in your web.xml file like this:

<context-param>
      <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name>
      <param-value>true</param-value>
</context-param>
       

JBoss AS ships with three JSF Implementations, Mojarra 1.2, Mojarra 2.0, and MyFaces 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 deployers/jsf.deployer directory you will see the JSF configurations that ship with JBoss AS6. To tell your application to use one of these JSF configurations, add this to your web.xml:

<context-param>
      <param-name>org.jboss.jbossfaces.JSF_CONFIG_NAME</param-name>
      <param-value>Mojarra-1.2</param-value>
 </context-param>
       

A new JSF Configuration is useful when you want to add a new JSF implementation to JBoss AS or you just want to enhance an implementation with extra jars such as component libraries. This can save you from bundling the same jars over and over in your WARs.

It's also useful for testing the same application against different JSF implementations, library versions, and configurations. You can create a JSF Configuration and then apply it to your WAR with a a simple context param.

A JSF Configuration consists of some jars and a special 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:

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.

The elements in your special 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.

To allow the JSF Deployer to recognize your JSF Configuration, you will need to edit deployers/jsf.deployer/META-INF/jsf-integration-deployer-jboss-beans.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>
       

<bean name="JSFUrlIntegrationDeployer-MyJSFConfig">
    <property name="JSFImplName">
      <value>MyJSFConfig</value>
    </property>
    <property name="JSFImplManagementDeployer">
      <inject bean="JSFImplManagementDeployer"/>
    </property>
</bean>