Getting started with Shale and Clay
This tutorial is based on Maven and Eclipse. The guidelines also apply to any other scenario, but you must find the appropriate way of doing it within your IDE. The ShaleClay.zip (you will need to add the dependent jar files to the WEB-INF/llib folder manually or by running mvn war:inplace) file contains a complete Maven/Eclipse project which you may use as basis for this.
The easiest way to get started with Shale and Clay is by starting with the Maven2 clay-starter archetype.
Since the archetype currently has not made its way into the distribution, you will need to get the archetype from the Shale Subversion repository located at:
After you have downloaded the sources, you need to run the following Maven2 command in the shale-starter-archetype directory:
mvn clean install.
This will build the archetype and install into your local repository so that it is available to you.
Create a directory where you want the project, ex. C:\My projects\ShaleClay. Open a shell (CMD) and type in (on one line):
mvn archetype:create -DarchetypeGroupId=org.apache.shale.clay -DarchetypeArtifactId=clay-starter-archetype -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=com.acme.test -DpackageName=com.acme.test -DartifactId=shaleclay
What happens here is that Maven will create a project based on Shale and Clay. The parameters are:
archetypeGroupId – The archetype groupId
archetypeArtifactId – The archetype artifactId
archetypeVersion – The archetype version number
groupId – The groupId of you project
packageName – The default package name of your project – included source is placed here
artifactId - The groupId of you project
After you have done his, a project will have been created for you in a directory with the same name as you gave for the artifactId. Move to this directory.
To make Eclipse understand that this is an Eclipse project you need to run the following Maven2 command:
mvn eclipse:eclipse –Dwtpversion=1.5
After running this command a couple of files and a directory will be created that is needed for Eclipse. Your layout should look something like this:
Start Eclipse and open a workspace that points to C:\My projects\ShaleClay (or wherever you chose as a workspace for this project)
For Eclipse you now need to import the newly created project into the workspace:
Choose “File->Import”. In the next dialog select "General-Exisiting projects into workspace"
You should the get the following:
In the field "Select root directory" enter the name of you workspace or use the “Browse..” button to navigate to it. Eclipse should now list all available projects. Select the ShaleClay project and hit the “Finish” button.
You may see a red cross on your projectname if you have not defined the maven classpath variable “M2_REPO”. You can add it under "Window-preferences" and then "Java-Build Path-Classpath Variables"
Press the "New..." button. In the next dialog type inn M2_REPO in the name field and in the ”Path:” field you enter the path to your local Maven2 repository. Press "Ok" and "Ok" again in the next dialog.
Eclipse will then inform you that it has to rebuild the workspace. Press the "Yes" button.
If you still have a red cross after it has recompiled, check the default Java version in Eclipse. If you have Java5 as standard the cause is the compiler-level is mismatched with what Maven set when it generated the project. Go to the problems view, right click on the message and choose “Quick Fix”
Select "Change Java compiler level to 1.4" and press “Ok”.
Your project should now compile ok. Now comes the time to look at the project it self and how it is organized. If you expand your project it should look something like this:
In the Java sourcefolder (src/main/java) under the packagename you provided you should find two classes: Person and TestViewController.
In the resources folder (src/main/resources) you will find three property files. This is actually one property file with two language provisions of it. These can be identified by their name extention.
In the web sources folder (src/main/webapp) you will find several folders:
- The folder ”images” contains the images and backgrounds that are used for the site.
- The folder ”pages” contains standard definitions (defaultxxx.html) of the various parts that make up the site, along with some specific definitions (pageXbody.html)
- The folder “templates” contains the template that we are using to build our site – we will return to this shortly
- The folder ”theme” contains the cascading stylesheet we use to format our site.
- In the folder ”WEB-INF” we find all the important configuration files.
Lets take a closer look at these, starting with web.xml where we find these important declarations:
<!-- Override the default suffix for extension-mapped --> <context-param> <param-name>javax.faces.DEFAULT_SUFFIX</param-name> <param-value>.jsf</param-value> </context-param> <!-- Select JSF State Saving Mode --> <context-param> <param-name>javax.faces.STATE_SAVING_METHOD</param-name> <param-value>client</param-value> </context-param> <!-- Clay Common Configuration Resources --> <context-param> <param-name> org.apache.shale.clay.COMMON_CONFIG_FILES </param-name> <param-value>/WEB-INF/clay-config.xml</param-value> </context-param> <!-- Clay Configuration Full XML view Resources --> <context-param> <param-name> org.apache.shale.clay.FULLXML_CONFIG_FILES </param-name> <param-value>/WEB-INF/clay-views-config.xml</param-value> </context-param> <!-- Clay XML View Suffix --> <context-param> <param-name> org.apache.shale.clay.XML_TEMPLATE_SUFFIX </param-name> <param-value>.jsf</param-value> </context-param>
These declarations (context-param) are used by Clay and the JavaServer Faces (JSF) implementation at startup.
- javax.faces.DEFAULT_SUFFIX – Tells which page suffixes should be handled by JSF
- javax.faces.STATE_SAVING_METHOD – How should session state be persisted (Client-side or Server-side)
- org.apache.shale.clay.COMMON_CONFIG_FILES – What are the name(s )of the Clay configuration file(s), providing absolute path within the web-context
- org.apache.shale.clay.FULLXML_CONFIG_FILES – What are the name(s) of the Clay configuration file(s) that tells Clay about our page definitions.
- org.apache.shale.clay.XML_TEMPLATE_SUFFIX – Which page suffixes should be handled by Clay.
Then are the Filter definitions. A filter is a Javaclass that will be called by the webcontainer on every request that comes into it (Actually only requests that match a certain predefined pattern – See filter-mapping below)
<filter> <filter-name>shale</filter-name> <filter-class> org.apache.shale.application.faces.ShaleApplicationFilter </filter-class> </filter> <!-- Shale Application Controller Filter Mapping --> <filter-mapping> <filter-name>shale</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
Here Shale is wired into the request processing. In this case the Shale filter will be invoked on every request because of the