The Apache MyFaces Core project

The Apache MyFaces Core project is where it all started. It does not do much more than implement the JSF standard. There are currently three relevant versions of this standard:

The Core project currently has branches for each of these JSF versions. The 1.1, 1.2 and 2.0 versions are stable and are updated regularly.

Why should I use MyFaces Core?

Every Java EE application server comes with a bundled JSF implementation. Often the reference implementation (RI), known as "Mojarra", is used for this. However, you can bundle an alternative JSF implementation to be used with your project. This way, you can use MyFaces Core as JSF implementation on every Java EE application server. One of the benefits of using MyFaces Core is that it generates more informative logging, which can be helpful while debugging. If you're looking for an application server that uses MyFaces Core by default, you should take a look at Apache Geronimo.

Getting started

So you want to use MyFaces Core as the JSF implementation in your project. This section tells you how to get started.

Maven

If you're using Maven to manage dependencies, you can use on of the Maven archetypes provided by the Maven archetypes sub project to generate an empty project with all of the libraries you need already in place. See the Maven archetypes for details. After you've created a project, continue with the Configuring MyFaces section.

Managing dependencies manually

If you're not using Maven, you'll have to manage your dependencies manually. This section describes what's needed to add MyFaces Core as a dependency to you project.

  1. Downloading Apache MyFaces Core.

    1. The latest version of MyFaces Core can be downloaded from the MyFaces Core donwload page. Depending on hte JSF version you want to use, you should download a MyFaces Core 1.1.x, 1.2.x or 2.0.x version. (I.o.w.: the first two digits of the MyFaces Core version correspond to the JSF version it is designed for.)

    2. MyFaces Core is available as .zip and .tar.gz file. If you're working on Windows, you should download the .zip, otherwise, you can download the .tar.gz.

  2. Unpacking the downloaded file. Use your favorite unzip / unarchive tool to unpack the downloaded file. If everything went well, you should end up with a single directory called myfaces-core-x.y.z-bin, where x.y.z is the version number.

  3. Adding the JARs to you classpath. Inside the myfaces-core-x.y.z-bin directory is a lib directory, that contains a collection of .jar files. For your reference, here's a drill down of the contents of the lib directory in the distribution:

    • myfaces-impl-x.y.z.jar: the MyFaces Core JSF implementation.

    • myfaces-api-x.y.z.jar: the JSF API. These are all the interfaces and classes that are called from the outside. In other words, these are those things you import from the javax.faces package.

    • myfaces-bundle-x.y.z.jar: a combination of the previous two in one single JAR.

    • commons-......jar: a series of libraries from the Apache Commons project, that MyFaces Core depends on.

    You should add either the myfaces-impl-x.y.z.jar and myfaces-api-x.y.z.jar or the myfaces-bundle-x.y.z.jar to your project's classpath. Further more, all commons-......jar files should also be added to the classpath. The procedure to add JARs to a classpath differs, depending on the IDE you are using for your project. After you've set the dependencies for you project, continue with the Configuring MyFaces section.

Configuring MyFaces

There are two important configuration files for a JSF application—web.xml and faces-config.xml. We will discuss the basics of both of them.

The web.xml configuration file

The web.xml configuration file resides in the /WEB-INF/ directory of the (to be) deployed web application. It configures the web server part of the application. The web.xml file can be used to define which file types may be requested by users, which directories can be accessed, and so on. With regards to JSF, the most important task of web.xml is to tell the web server that there is such a thing as a Faces Servlet, and that URLs containing a certain pattern should be forwarded to that Faces Servlet. A minimal web.xml could look like this:

 <?xml version="1.0" encoding="UTF-8"?>
 <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns="http://java.sun.com/xml/ns/javaee"
          xmlns:web="http://java.sun.com/xml/ns/javaee/webapp_2_5.xsd"
          xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                              http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
          id="WebApp_ID" version="2.5">
    <display-name>MyFaces Test Project</display-name>
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>
 </web-app> 

The part between the <servlet> tags tells the application server that it has to instantiate an object of the javax.faces.webapp.FacesServlet class as a Servlet and name it Faces Servlet. It will be started at the start up of the application. The part between the <servlet-mapping> tags tells the web server that any URL starting with /faces/ immediately after the address of the server and the location of the application will be handled by that Servlet.

The faces-config.xml configuration file

The faces-config.xml file defines the behavior of the Faces Servlet that is at the heart of a JSF application. Whereas a web.xml file is generally edited only at the start of a project or when structural changes are made to the application, faces-config.xml changes all the time, as the application grows. And while web.xml mostly contains general configuration options, a faces-config.xml file tends to be more specific to a certain application, as it may contain e.g. navigation details and other application-specific configurations. In JSF 2.0 the presence of a faces-config.xml file is no longer required, but in earlier JSF versions it is. A minimalistic faces-config.xml for JSF 1.2 may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                                  http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
              version="1.2">
    <application>
        <locale-config>
            <default-locale>en</default-locale>
            <supported-locale>en</supported-locale>
            <supported-locale>en_US</supported-locale>
        </locale-config>
        <message-bundle>my.company.Messages</message-bundle>
    </application>
</faces-config>

Additional configuration for Glassfish

To use MyFaces Core as the JSF implementation on a Glassfish 2.x application server, we have to make some additional settings in a GlassFish-specific configuration file—sun-web.xml. This file has to be in the WEB-INF folder of our project, along with most of the other configuration files, such as web.xml and faces-config.xml. The contents of the file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN"
                             "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
    <class-loader delegate="false"/>
    <property name="useMyFaces" value="true"/>
</sun-web-app>

This disables the default implementation and forces GlassFish to use MyFaces Core instead. Of course, we have to make sure that the MyFaces Core libraries are added properly to our application and configured correctly, as described in the previous sections.

Drafts/Site/Core (last edited 2011-03-18 10:27:58 by BartKummel)