Source Code for Bookstore Application

The source code for my Shale bookstore example is available at:

http://dchooge.myweb.uga.edu/shale-bookstore.zip
This project connects to a postgres database. All database connection work is handled in the DatabaseManager class.

A link so you can try out this example without installing and setting up shale/tomcat will be available soon.

Presentation on Building Applications in Shale

My presentation/tutorial on understanding and building within a Shale application is available at:

http://dchooge.myweb.uga.edu/Setting_up_Shale.ppt
This presentation goes over all required files for a Shale application as well as how to tie them all together. Additionally I go over some of the optional files and outline how they fit within the Shale framework. Excellent place to start for those who want a quick-start into building with Shale.

Shale v. Struts Presentation

My presentation comparing Shale and Struts is available at:

http://dchooge.myweb.uga.edu/Shale_Presentation.ppt

Helpful Links for Understanding Shale

The Shale Project's own page on development:
http://shale.apache.org/building.html

This page is helpful for some initial understanding, however, it has not been updated for quite a while and the information presented on it lags behind the current version of Shale by a few revisions.

IBM's tutorial on understanding JSF and Shale:
http://www-128.ibm.com/developerworks/java/library/j-shale0228/

Once again this information lags behind the current version of Shale by a number of revisions. It is extremely good at giving an explanation of the directory structure of Shale as well as important files for use with Shale.

A Developer's tutorial on Shale:
http://www.timfanelli.com/item/134

This is the best site of the three for a full understanding of Shale. Like the others it does lag behind the current version, however, the information contained here is abstracted enough that version is of a lesser concern.

Understanding Forms and Beans

All of the source code for this posting can be downloaded from:

http://dchooge.myweb.uga.edu/ExampleFiles.zip

This example is extremely basic and simply allows the user to enter text on one page then submit this information for display on another. However, even this simple example shows how information can be passed from one page to another as well as the invocation of Java functions from JSF pages.

For this example I'll be extending the blank-shale application starting with the welcome page. Overall, the shale application is comprised of two pages:

1. welcome.jsp - This is an edited version of the welcome page present in shale-blank. It now accepts user into and saves this information to StringBean.java. A new commandButton has also been added that actually submits the entered information to the Bean and the passes control to the "next" view. I'll go into the navigation options later but for now its enough to simply note that this option is configured in faces-config.xml
2. showString.jsp - This new page simply displays the string entered on welcome.jsp and saved into StringBean.java

As a further note the prompts present on both welcome.jsp and showString.jsp are pulled from Bundle.properties

Shale requires that each JSF page be backed by an AbstractViewController. In the case of the welcome.jsp page this is simply the edited form of the WelcomeBean.java file present in the original shale-blank application. By the same token showString.jsp is backed by ShowStringViewController.java. There are several key functions included in these two files that are currently unused but will find use later as the application is developed more:

1. prerender() - The function called just before the page this Java file is attached to is rendered. This function is often used to set up database connections needed on the page or to execute functions who's outcome is displayed on the JSF page in question.
2. preprocess() - This function is extremely similar to prerender() however in this case it is called just prior to any other function calls on the page.

The two AbstractViewControllers are then declared in faces-config.xml and tied to the page through the tag on the welcome page or the tag on the showString.jsp page.

Finally, the object that will store the user entered value is created by StringBean.java. Once again this Bean is declared in faces-config.xml file. The user entered value is actually saved to this Bean through the the inputText declaration:

It is the commandButton declared on the welcome.jsp page that passes control from one JSF page to another. Namely, it checks the section of faces-config.xml and passes to the specified.

Finally, the user entered text shows up on the showString.jsp page through the outputText tag:

As a final note it is the getters and setters present in StringBean.java that are actually used to both store and recall the values entered by the user.

Understanding the Shale directory structure

With any major coding project an understanding of the directory structure is essential. It is, of course, no different with Shale. Thus, before diving into adding functionality to the blank shale template we should go over exactly what makes up the Shale installation.

A Shale install contains three major folders:

1. docs - Contains the javadocs for the project. With the shale-blank application this largely contains documentation on dependencies, API function calls, and general information about the Shale architecture.
2. target - This is where the project builds. Once you make code changes and then instruct Maven to build it is in this folder where the new .war file will appear as well as testing files, reports etc.
3. src - This folder contains all the source code for your project and as such will be the folder you interact with the most.

Of these three folders the most important for our purposes is the src folder. It is here where the majority of development will take place and thus deserves a closer look than both the docs and target directories.

The src directory once again contains three child directories and like the previous three only one of these is truly important. The test and site directories contain files relating to testing your environment and additional files for website design, respectively. The main directory, however, contains the files that ultimately make up the application that is built on top of Shale.

The simplistic blank-shale application is made up of four files all housed in in the src directory:

1. index.jsp - In the previous posting when you went to http://127.0.0.1/shale-blank/ page this is the first page to actually be opened. It strictly contains a forward to the more interesting welcome.jsp.
2. welcome.jsp - This is the page that actually displays the simple date and time.
3. messages.jspf - Like index.jsp this page strictly loads another file namely it loads the messages to be used in the shale application.
4. Bundle.properties - This file houses all the messages used throughout the Shale application. There are currently only two messages defined and they can both been seen actually used on the welcome.jsp page.

Thus, we have the major files in the empty shale-blank application. It is this structure that we'll be extending to create our webapp based on Shale.

How-to set up and run Shale

Getting a Shale installation up and running can be a fairly difficult process given Shale's newness. Before you even start with Shale you'll need to download and install a few applications you will need later once Shale is actually built.

1.) First off make sure you have Java installed with JAVA_HOME correctly configured.

2.) Next, download and install the latest version of maven from: http://maven.apache.org/download.html

Installing Maven is a fairly simple process. Just unzip to your directory of choice and set-up the classpath to point to Maven's /bin directory.

3.) Now, download and install Apache Tomcat from: http://tomcat.apache.org/ Tomcat will be used to allow access to Shale once built.

4.) With all this down you can finally download Shale itself. Shale comes in several different flavors designed to suit a varity of different needs. For our purposes we'll be using the blank shale application. This version of Shale is specifically designed to allow easy development and is available at: http://people.apache.org/dist/shale/v1.0.3/shale-blank-1.0.3.zip
A full list of all Shale versions is at: http://people.apache.org/dist/shale/v1.0.3/

Unzip to the directory you wish to develop from and open a console in the top-level Shale directory. Now make sure you have an active internet connection and run the command "mvn" this will invoke Maven using the pom.xml in the same directory. Maven will download all dependencies and build the blank Shale application in the form of "shale-blank.war"

5.) Finally its time to actually run this newly built Shale application. Start Tomcat if you haven't already and drop the "shale-blank.war" file into "YOUR_TOMCAT_DIR/webapps" directory. Now you can view the extremely simple empty-shale application at:

http://127.0.0.1:8080/shale-blank/

PowerPoint Presentation on Enterprise Software Engineering

The presentation on Enterprise Software Engineering is available at:

http://dchooge.myweb.uga.edu/Enterprise_Presentation.ppt