MyFaces Tomahawk

Tomahawk has been part of the Apache MyFaces project from the very beginning. Its main goal is to implement a larger set of components than the rather minimal set that is defined in the JSF specification. Tomahawk contains both extended versions of standard JSF components and components that are not defined at all in the standard. Some examples of components that are added by Tomahawk are:

• A CAPTCHA component
• An extensive data table component that includes pagination functionality for larger data sets
• A file upload component
• Various date selection components
• A google calendar-like component to display and edit schedules
  

Tomahawk also features some custom validators that make it easy to validate, for instance, credit card numbers and email addresses. There are three variants of Tomahawk, as follows:

• Tomahawk for JSF 1.1 is compatible with both JSF 1.1 and JSF 1.2;
• Tomahawk for JSF 1.2 takes advantage of some features of JSF 1.2, making it incompatible with JSF 1.1;
• Tomahawk for JSF 2.0 is still based on the Tomahawk for JSF 1.1 version, but has some minor changes to take advantage of JSF 2.0 features.
  

Getting started with Tomahawk

To use the Tomahawk component set, we first have to do some set up. The following steps have to be taken:

1. Download Tomahawk and add it to our project
2. Make some settings in the web.xml file
3. Add some extra libraries to resolve a few dependencies
   

The following subsections will focus on each of these tasks.

Downloading Tomahawk

Tomahawk comes in three flavors:

• A version for JSF 1.1 that is compatible with both JSF 1.1 and JSF 1.2, but doesn’t take advantage of the JSF 1.2 features
• A version for JSF 1.2 that does take advantage of some the JSF 1.2 features and isn’t compatible with JSF 1.1
• A version for JSF 2.0, only compatible with JSF 2.0

Each of those versions can be downloaded from the download page of the Tomahawk project.

Configuring web.xml

Tomahawk uses a special Extensions Filter. This filter is used to serve common resources such as images and JavaScript files. These resources are needed by some of the components, and are provided in the Tomahawk JAR file. The Extensions Filter can provide resources transparently; it doesn’t matter if the resources are located as separate files within the project or in a JAR file in the classpath. We have to add some lines to our web.xml file to make this extensions filter work. First, we have to define the filter itself:

    <filter>
        <filter-name>MyFacesExtensionsFilter</filter-name>
        <filter-class>org.apache.myfaces.webapp.filter.ExtensionsFilter</filter-class>
        <init-param>
            <param-name>uploadMaxFileSize</param-name>
            <param-value>20m</param-value>
        </init-param>
    </filter>

The filter-name can be anything, but it’s a good idea to choose a descriptive name. The filter-class is the fully-classified name of the Filter implementation that is provided by Tomahawk. This class can be found in the Tomahawk JAR. The ExtensionsFilter is also used to handle file uploads for the <t:inputFileUpload> component. Therefore, we have to set the maximum file size for uploads here. Any file size can be set, and the following suffixes can be used:

• No suffix for bytes
• k for kilobytes
• m for megabytes
• g for gigabytes

Now that the filter is defined, we have to add at least one filter mapping to make it work. Tomahawk uses two filter mappings. The first filter mapping looks like this:

    <filter-mapping>
        <filter-name>MyFacesExtensionsFilter</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
    </filter-mapping>

The filter-name value refers to the name that we defined in the filter definition. The servlet-name refers to the name that we gave to our Faces Servlet. If you gave your Faces Servlet another name, make sure that you use that name here. This mapping will cause all pages that are handled by the Faces Servlet to pass the through the Extensions Filter. This enables the Extensions Filter to scan each page for links to resources, and then change those links so they point to the Extensions Filter.

In the second filter mapping, we need to map a URL prefix to the Extensions Filter. This will cause all requests that start with this pattern to be routed directly to the Extensions Filter. The Extensions Filter can then serve up the requested resource. This filter mapping looks like this:

    <filter-mapping>
        <filter-name>MyFacesExtensionsFilter</filter-name>
        <url-pattern>/faces/myFacesExtensionResource/*</url-pattern>
    </filter-mapping>

Again, the filter-name should match the name defined in the filter definition. The url-pattern can be anything, but it should start with the pattern that is used for the Faces Servlet (/faces/* in this example). It is also a good idea to have some relation between the name of the filter and the second part or the URL pattern. Now we’re ready to go!

Resolving dependencies

Various Tomahawk components depend on one or more external libraries, which are not distributed within the Tomahawk package. Of course, you don’t need to download the dependencies yourself if you’re using Maven. But if you're not, you can refer to the following table to resolve the dependencies manually:

The listed versions apply to Tomahawk 1.1.9. You should understand that different versions of Tomahawk may depend on different versions of the listed libraries, or even on other libraries.