2009/05/20 - Apache Shale has been retired.

Introduction

This page documents the use of Shale in your web applicatons, including external dependencies and detailed instructions on configuring your application. You might also consider starting from the shale-blank example application that has many of the basics set up for you, ready to be customized for your own use.

External Dependencies

The following table describes runtime external dependencies of the Shale libraries included in the distribution.

1. Shale has been tested with the JavaServer Faces Reference Implementation (Version 1.1_01) and with Apache MyFaces (Version 1.1.1). Be sure to read the release documentation of each implementation to acquire the dependencies of that package.
2. Spring ships with either an all-in-one JAR file (spring.jar) or a set of smaller JAR files containing only portions of the framework. If you do not use the all-in-one file, you will need to use spring-beans.jar, spring-context.jar, spring-core.jar, and spring-web.jar.

Configuring Your Application For Shale

(A) Add Required Libraries

If your server does not already provide an implementation of JavaServer Faces, you must include such an implementation (plus all of its dependent JARs) in the /WEB-INF/lib directory.

Most Shale based applications will require shale-core.jar (and its dependencies, as described above). If you wish to utilize the features provided in the optional Shale components, include those JARs (and ther external dependencies) as well.

The shale-test.jar contains base classes for JUnit based unit tests for your application classes. As such, it is useful only at application build time, and should never be included in a runtime web application archive.

The shale-tiger.jar contains feature extensions that depend on platform capabilities (most particularly the annotations facility) of Java SE 5 (code named "Tiger"). You must NOT include this library if you are running on a JDK 1.4 platform.

If you use Maven 2 as your build environment, the process of selecting the correct JAR files and dependencies can be delegated to Maven. Each Shale module has a group identifier of org.apache.shale, and an artifact identifier of shale-xxxxx depending on the base name of the JAR file. For example, to include the Shale Core library (and all of its dependencies) in your web application, add the following entry into the dependencies section of your pom.xml file:

    <dependency>
        <groupId>org.apache.shale</groupId>
        <artifactId>shale-core</artifactId>
        <version>1.0.4</version>
    </dependency>

(B) Configure /WEB-INF/web.xml Resource

Create a /WEB-INF/web.xml resource that conforms to the rules defined in the Servlet 2.4 Specification. You can use the one in the Use Cases example as a guide. Include the following elements (at appropriate places) as needed.

Configure whether you want JavaServer Faces to save component state on the client side or the server side. This lets you choose between the tradeoffs of extra network traffic versus extra server memory usage, without affecting your application code.

    <context-param>
      <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
      <param-value>server</param-value>
    </context-param>

If you have defined JavaServer Faces configuration resources in addition to, or instead of, the default one (/WEB-INF/faces-config.xml), list them here. You may specify more than one resource by separating the paths with a comma (',') character. Note that the default configuration resource will be processed, if it is present, whether or not it is explicity listed here.

    <context-param>
      <param-name>javax.faces.CONFIG_FILES</param-name>
      <param-value>/WEB-INF/managed-beans.xml,/WEB-INF/navigation.xml</param-value>
    </context-param>

If you have defined your own Command Chain commands (to customize the behavior of the standard chains, or to implement mappings for remote commands), tell Commons Chain where your configuration resource is. You can specify more than one resource by separating the paths with a comma (',') character.

    <context-param>
      <param-name>org.apache.commons.chain.CONFIG_WEB_RESOURCE</param-name>
      <param-value>/WEB-INF/chain-config.xml</param-value>
    </context-param>

If you have defined your own Shale Dialog configuration resources in addition to (or instead of) the standard path (/WEB-INF/dialog-config.xml), specify the path here. You may specify more than one resource by separating the paths with a comma (',') character.

    <context-param>
      <param-name>org.apache.shale.dialog.CONFIGURATION</param-name>
      <param-value>/WEB-INF/dialog-config.xml</param-value>
    </context-param>

If you are using the optional integration with Spring, you must specify that path to the configuration resource for the ApplicationContext. You can specify more than one resource by separating them with whitespace.

    <context-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>/WEB-INF/applicationContext.xml</param-value>
    </context-param>

If you are using the Clay plugin, you must specify the path to the configuration resource defining your Clay component definitions. You can specify more than one resource by separating them with comma (',') characters.

    <context-param>
      <param-name>clay-config-files</param-name>
      <param-value>/WEB-INF/clay-config.xml</param-value>
    </context-param>

If you are using the Tapestry-like views feature of the Clay plugin, you may override the default resource extension (.clay) used to identify pages containing component references.

    <context-param>
      <param-name>clay-template-suffix</param-name>
      <param-value>.clay</param-value>
    </context-param>

Configure the standard Shale application controller filter, and map it to the requests you want it to apply to. At a minimum, you will want to map this filter to the same pattern that FacesServlet is mapped to (see below); however, the simplest approach is to use the /* pattern to map the filter to all incoming requests.

    <filter>
      <filter-name>shale</filter-name>
      <filter-class>
        org.apache.shale.faces.ShaleApplicationFilter
      </filter-class>
    </filter>

    <filter-mapping>
      <filter-name>shale</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>

Configure the Commons Chain configuration listener, so that command chains definitions specified by the application, and those defined internally by Shale, will be loaded at application startup time.

    <listener>
      <listener-class>
        org.apache.commons.chain.web.ChainListener
      </listener-class>
    </listener>

If you are using the Clay plugin, configure the Clay configuration listener, so that component definitions specified by the application as well as those specified internally by Shale, will be loaded at application startup time.

    <listener>
      <listener-class>
        org.apache.shale.clay.config.ClayConfigureListener
      </listener-class>
    </listener>

If you are using the Spring integration feature, configure the Spring configuration listener so that the application context will be configured at application startup time.

    <listener>
      <listener-class>
        org.springframework.web.context.ContextLoaderListener
      </listener-class>
    </listener>

Configure the standard JavaServer Faces processing servlet and mapping. You may use either prefix or extension mapping, and the JSF runtime will automatically adapt. The example below shows the most common default:

    <servlet>
      <servlet-name>faces</servlet-name>
      <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    </servlet>

    <servlet-mapping>
      <servlet-name>faces</servlet-name>
      <url-pattern>*.faces</url-pattern>
    </servlet-mapping>

If you are using the Tapestry-like views feature of the Clay plug-in, map the standard JavaServer Faces servlet to the same extension you specified for the clay-template-suffix context init parameter.

    <servlet-mapping>
      <servlet-name>faces</servlet-name>
      <url-pattern>*.html</url-pattern>
    </servlet-mapping>

Optionally, configure the "welcome file(s)" for your application.

    <welcome-file-list>
      <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

(C) Runtime Assertion Checking

Shale leverages the assert capability of JDK 1.4 (or later) Java Virtual Machine (JVM) runtime environments to support a large number of runtime assertion tests, to ensure that functional assumptions are satisfied. By default, the runtime JVM of your container will disable checking such assertions (so that they incur no production runtime hit on performance). During development, however, you will want to make sure that the -Denableassertions (or, if you only want Shale assertions enabled, use -Denableassertions:org.apache.shale... instead) command line argument is passed to the startup script for the servlet container used by your development tool. The details of configuring this command line option are, of necessity, tool specific.