Struts Framework
|
Prerequisite Software |
In order to build a Struts source distribution, or install and use a
Struts binary distribution, you will need to acquire and install several
other software packages, as follows:
- Java Development Kit - You must download and install
a Java2 (version 1.2 or later) Java Development Kit implementation for
your operating system platform.
A good starting point for locating Java Development Kit distributions is
http://java.sun.com/j2se.
- Servlet Container - You must download and install a
servlet container that is compatible with the Servlet API Specification,
version 2.2 or later, and the JavaServer Pages (JSP) Specification,
version 1.1 or later. One popular choice is to download Apache's
Tomcat (version 3.1
or later required, version 3.2 or later recommended).
- Ant Build System - If you are building Struts from the
source distribution, you must download and install version 1.3 or later
of the Ant build system.
This package is also strongly recommended for use in developing your
own web applications based on Struts.
- If you are using the release version of Ant version 1.3, you will
also need to download the "optional.jar" file that contains the
implementation of Ant's
<style> command.
- Make sure that the "ant" and "ant.bat" scripts are executable, by
adding the $ANT_HOME/bin directory to your PATH environment
variable.
- Servlet API Classes - In order to compile Struts itself,
or applications that use Struts, you will need a
servlet.jar
file containing the Servlet and JSP API classes. Most servlet containers
include this JAR file. Otherwise, you can get the Servlet API classes
distribution from
here.
- JDBC 2.0 Optional Package Classes - Struts supports
an optional implementation of
javax.sql.DataSource , so it
requires the API classes to be compiled. They can be downloaded from
http://java.sun.com/products/jdbc/download.html.
- XML Parser - Struts requires the presence of an XML
parser that is compatible with the Java API for XML Parsing (JAXP)
specification, 1.0 or later. You can download and install the JAXP
reference implementation,
which is required for building the Struts source distribution. In
Struts-based web applications, you may replace the reference
implementation classes with any other JAXP compliant parser, such as
Xerces. See detailed
instructions related to the parser in the instructions for
building and installing
Struts, below.
- Xalan XSLT Processor - If you are building Struts from
the source distribution, you must download and install version 1.2
(problems have been reported with current versions of Xalan 2.0)
of the Xalan
XSLT processor (which also includes the Xerces XML parser), or use the
version of Xalan included in the JAXP 1.1 release. This
processor is used to convert the Struts documentation from its internal
XML-based format into the HTML that is presented in the Struts
documentation application.
|
Building Struts From Source |
First, download a source distribution of Struts by following the
instructions here. Then, make sure
you have downloaded and installed all of the
prerequisite software packages described
above.
To build Struts, you will need to customize the build process to the
details of your development environment as follows:
- The Struts source distribution uses a file named
build.properties (in the top-level directory of the
distribution) to identify the location of external components
that Struts depends on.
- There is no
build.properties file included with the
source distribution. However, there is an example file named
build.properties.example that you can copy to
build.properties and then customize.
- The properties you must configure in
build.properties are:
- catalina.home - Pathname to the directory of your
binary distribution of Tomcat 4.0 (required only if you wish to
use the
deploy.catalina target).
- servletapi.home - Pathname to the directory of
your binary distribution of the Servlet API classes.
- tomcat.home - Pathname to the directory of your
binary distribution of Tomcat 3.2 (required only if you wish to
use the
deploy.tomcat target).
- xerces.home - Pathname to the directory of your
binary distribution of the Xerces parser, version 1.2 or 1.3
(required only if you wish to use the
deploy.catalina
target).
- If you are a Struts developer with write access to the CVS repository,
be sure that you do NOT check in a copy of the
build.properties file, since it will be different for
each individual developer.
To build a "distribution" version of Struts, first change your current
directory to the directory in which you have unpacked the Struts
source distribution, and (if necessary) create or customize the
build.properties file as described above. Then, type:
ant dist
This command will create a binary distribution of Struts, in a
directory named dist (relative to where you
are compiling from). This directory contains an exact replica of the
files included in a binary distribution of Struts, as described
in the following section.
IMPORTANT NOTE: The struts.jar must be in your classpath when
compiling Struts. The build.xml provided does this automatically.
If you use your development machine to test Struts application locally, be
sure that the stuts.jar is NOT on your classpath when your
container is running.
|
Install A Struts Binary Distribution |
First, download a binary distribution of Struts by following the
instructions here. Then, make sure
you have downloaded and installed all of the
prerequisite software packages described
above.
Unpack the Struts binary distribution into a convenient directory.
(If you build Struts from the source distribution, the result of the
build will already be an unpacked binary distribution for you). The
distribution consists of the following contents:
- lib/struts.jar - This JAR file contains all of the
Java classes included in Struts. It should be copied into the
WEB-INF/lib directory of your web application.
WARNING - If you are going to be hosting multiple Struts
based applications on the same servlet container, you will be tempted
to place the struts.jar file into the shared repository
supported by your container. Be advised that this will like cause you
to encounter ClassNotFoundException problems unless all of
your application classes are stored in the shared repository.
- lib/struts*.tld - These are the "tag library
descriptor" files that describe the custom tags in the various Struts
tag libraries. They should be copied into the
WEB-INF
directory of your web application.
- webapps/struts-blank.war - This is a simple "web
application archive" file containing a basic starting point for
building your own Struts-based applications.
- webapps/struts-documentation.war - This is a
"web application archive" file containing all of the Struts
documentation found on the
Struts web site
(including these pages). You can install this web application
on any servlet container compatible with Servlet API 2.2 or later.
- webapps/struts-example.war - This is an example
web application that uses a large percentage of Struts features.
You can install this web application on any servlet container
compatible with the Servlet 2.2 (or later) and JSP 1.1 (or later)
specifications. If an XML parser is not made available to web
applications by your container, you will need to add one to the
WEB-INF/lib directory of this web application.
- webapps/struts-exercise-taglib.war - This web
application contains test pages for the various custom tags supported
by Struts. It is primarily of use to developers who are enhancing the
Struts custom tag libraries, but may also be useful as simple examples
of the usage of various Struts tags.
- webapps/struts-template.war - This web application
both introduces and demonstrates the Struts template tags.
- webapps/struts-upload.war - This web application
is a quick example of uploading files using the Struts framework.
To use Struts in your own application, you will need to follow
these steps:
- Copy the file
lib/struts.jar from the Struts distribution
into the WEB-INF/lib directory of your web application.
- Copy the all of the files that match
lib/struts*.tld
from the Struts distribution into the WEB-INF directory
of your web application.
- Modify the
WEB-INF/web.xml file for your web application
to include a <servlet> element to define the
controller servlet, and a <servlet-mapping> element
to establish which request URIs are mapped to this servlet. Use the
WEB-INF/web.xml file from the Struts example application
for a detailed example of the required syntax.
- Modify the
WEB-INF/web.xml file of your web application
to include the following tag library declarations:
<taglib>
<taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-html.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>/WEB-INF/struts-template.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-template.tld</taglib-location>
</taglib>
- Create a file
WEB-INF/struts-config.xml that defines the
action mappings and other characteristics of your specific application.
You can use the struts-config.xml file from the Struts
example application for a detailed example of the required syntax.
- At the top of each JSP page that will use the Struts custom tags,
add line(s) declaring the Struts custom tag libraries used on
this particular page, like this:
<@ taglib uri="/WEB-INF/struts-bean.tld" prefix="struts-bean" %>
<@ taglib uri="/WEB-INF/struts-html.tld" prefix="struts-html" %>
<@ taglib uri="/WEB-INF/struts-logic.tld" prefix="struts-logic" %>
<@ taglib uri="/WEB-INF/struts-template.tld" prefix="struts-template" %>
- When compiling the Java classes that comprise your application, be sure
to include the
struts.jar file (copied earlier) on the
CLASSPATH that is submitted to the compiler.
|
Installing Struts with your servlet container |
WARNING - Do NOT add
struts.jar to the classpath of your servlet container in an
attempt to avoid placing it in the /WEB-INF/lib directory of
each individual web app! Doing so will cause problems with
ClassNotFoundException exceptions.
For most containers, you need only to:
- Copy the WAR files in your Struts
/webapp directory to your
containers webapps directory.
- In some cases, you may need to restart your container if it is running.
Status of various containers
|
|