B.1 The Binary Versus Source Distributions

There are two distribution methods for the Struts framework, source and binary. The source distribution gives you more control over the build package environment. However, this method is not for beginners. Unless you have a specific need (e.g., you need to insert a modified class file into the build), you should stick with the binary distribution. This section presents both methods.

B.1.1 Building Struts from the Source Distribution

You can obtain the source packages of Struts and the rest of the Jakarta projects from http://jakarta.apache.org/site/sourceindex.html. Several different versions are usually available, so be sure to get the one that's appropriate for your needs. There is always a nightly build of Struts that includes the latest changes and fixes. In most situations, you'll want to go with the nightly build, but be aware that it may also include new bugs.

When choosing a download, you have the option of selecting a ZIP file or a compressed TAR file. Choose the one that is appropriate for your operating system.

Once you have downloaded the appropriate version, extract the contents into a directory. The directory doesn't have to be empty, but it's easier if it is. The Struts source distribution file unpacks everything into a subdirectory called jakarta-struts.

Before you can build the source files, you will also need to download several prerequisite software packages (if they're not already installed in your environment). The following list describes the required software:

Java SDK

Version 1.2 or later. You can download the latest version from http://java.sun.com/j2se.

Servlet container

One that supports the 2.2 Servlet specification or later and the 1.1 JavaServer Pages specification or later.

Ant build tool

Version 1.5.4 or later. You can download the latest version from http://ant.apache.org/.

Servlet API classes

All servlet containers should contain the necessary files; just make sure the necessary JARs are in the classpath for the build tool.

XML parser

One that supports JAXP Version 1.1 or later. The Xerces parser is compatible and can be obtained from http://xml.apache.org/xerces-j.

Xalan XSLT Processor

Version 1.2 or later. Note that some problems have been reported with Version 2.0. The processor is used to convert the XML documentation files into HTML documentation files. The processor also includes the Xerces parser. You can download Xalan from http://xml.apache.org/xalan-j/index.html.

JDBC 2.0 Optional package classes

The Struts framework supports an implementation of javax.sql.DataSource and therefore requires the JDBC 2.0 Optional classes to be present. You can obtain the JDBC 2.0 classes from http://java.sun.com/products/jdbc/download.html.

You will also need to download the third-party packages listed in Table B-1 and extract the JAR files included with the packages. Each package has both a source and binary distribution available. Unless you are a true masochist, you should download the binary distributions of these packages.

Table B-1. Third-party packages required for Struts compilation

Package name	URL
Commons BeanUtils	http://jakarta.apache.org/commons/beanutils.html
Commons Collections	http://jakarta.apache.org/commons/collections.html
Commons Digester	http://jakarta.apache.org/commons/digester.html
Commons Logging	http://jakarta.apache.org/commons/logging.html
Commons Pool	http://jakarta.apache.org/commons/pool/index.html
Commons FileUpload	http://jakarta.apache.org/commons/fileupload
Commons Lang	http://jakarta.apache.org/commons/lang
Commons DBCP	http://jakarta.apache.org/commons/dbcp
Commons Validator	http://cvs.apache.org/viewcvs/jakarta-commons/validator
Jakarta ORO	http://jakarta.apache.org/oro

The URL http://jakarta.apache.org/commons/components.html provides a nice summary of the different release schedules of the Commons components.

Extract the binary distributions of each of these packages and put the JAR files somewhere that you can easily reference them, as will need to in the next step. Each package is extracted into its own subdirectory. You can leave the JAR files there for easier reference.

The next step is to create a build.properties file that specifies environmental dependencies such as the location of the third-party JARs extracted in the previous step. The Struts source distribution provides a build.properties.sample file in the top-level source distribution directory. Open this file and rename it build.properties. You need to customize this file for your particular environment. The file paths are relative to the location of the properties file. For example, to reference the Commons BeanUtils JAR file that is located in a directory called lib one level up, you would need to change the properties file to look like this:

# The JAR file containing version 1.0 (or later) of the Beanutils package # from the Jakarta Commons project. commons-beanutils.jar=../lib/commons-beanutils-1.3/commons-beanutils.jar

Once you have all of the file paths set in the build.properties file, you are ready to turn the Struts source files into Struts binary files. Make sure Ant is installed and configured correctly, and make sure you downloaded the xalan.jar file and placed it in the <ANT_HOME>/lib directory (this is needed so that an Ant task can process the XML documentation files). You will need to be able to execute Ant from the command line in the top-level source directory.

Once you've completed these steps, go to the directory where the build.properties file is located and type:

ant dist

Messages will be spewed out in the console. When they finally stop, they should show that the build was successful, as in Figure B-1.

Figure B-1. A success message is printed when complete

If the build is unsuccessful, you will get a failed message, usually with enough information to determine the cause. For example, if you forget to put the xalan.jar in the <ANT_HOME>/lib directory, the output will look similar to that in Figure B-2.

Figure B-2. A stack trace is usually included in failed builds

Assuming that the build was successful, the Struts binaries and dependent files are copied to the dist directory underneath the top-level source distribution directory.

B.1.2 Installing the Binary Distribution

Download the binary distribution and unpack it into a directory. The files are in a subdirectory called jakarta-struts within the distribution. As with the source distribution, you can download either a ZIP file or a compressed TAR file. You can obtain the binary distribution from http://jakarta.apache.org/site/binindex.html.

If you built Struts from the source distribution, the binary files will already be unpacked into the dist/lib directory of the top-level source distribution directory.

The following steps need to be performed for a Struts application to work properly. Any necessary container-dependent modifications to these steps are discussed in the sections for the individual containers later in this appendix.

1. Copy all of the JAR files from the distribution's lib directory to the web application's WEB- INF/lib directory.

2. Copy all of the .tld files to the web application's WEB-INF directory.

3. If you plan to use the Validator framework, copy the validation-rules.xml file to the WEB- INF directory. See Chapter 11 for more information on the configuration files required by the Struts Validator.

4. Create a web application deployment descriptor (web.xml) and copy it to the WEB-INF directory. See Chapter 4 for details on how to configure the web.xml file.

5. Create a struts-config.xml file and copy it to the WEB-INF directory. See Chapter 4 for details on how to configure the configuration file for Struts.

6. Create a properties file called commons-logging.properties and copy it to the WEB-INF/ classes directory. Put the following line in the file:

   org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog

   
   

7. Create a Struts resource bundle and copy it to the WEB-INF/classes directory. See Chapter 12 for how to format this bundle and Chapter 4 for how to configure the Struts configuration file to use this bundle.

That's really all there is to installing the Struts framework. You still have to build the necessary JSP pages and other framework components, such as Action and ActionForm classes, but this is what is required to get the environment running. It's highly recommended that you play around with the example applications that are distributed with Struts. They are complete web applications, packaged as WAR files that you can copy to the container's webapps directory.

You have the option of using one of many different containers to run the Struts framework. In many cases, the steps just described should be followed exactly. However, not all containers are created equal, and some require modifications to the steps listed. The necessary modifications, if any, are described below.