Programming Jakarta Struts, 2nd Edition [Electronic resources] نسخه متنی

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/sourceindexl.
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/indexl.

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/downloadl.

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.

The URL http://jakarta.apache.org/commons/componentsl 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/binindexl.

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.