README

$Id: README,v 1.13 2001/03/24 00:05:36 craigmcc Exp $

				Struts
				======

Introduction
------------

This subproject contains the source code for the "Struts" application support
package, consisting of the following major components:

- Controller servlet with action mapping technology, implementing the Model-
  View-Controller (MVC) design pattern for web applications commonly called
  "Model 2", with a servlet as the "front component".

- Comprehensive custom tag library for building internationalized JSP pages
  that have HTML forms which interact with JavaBeans that are managed
  automatically by the controller servlet.

- Useful utility classes that can process XML input, as well as use Java
  reflection to populate JavaBean properties by matching names in the same
  way that the standard JSP tag

	<jsp:setProperty name="beanname" property="*"/>

  works.


Installing and Using Struts
---------------------------

You can utilize a binary distribution of Struts in your own web applications
by following these steps.  All of these steps are required if you want to
run the Struts application framework (including executing the example
application).  If you simply wish to use the Struts custom tag library,
and not the MVC framework, only the steps marked (*) are required.

- (*) Download and install a Java2 (version 1.2 or later) Java Development Kit
  Kit implementation for your operating system platform.  Define an environment
  variable JAVA_HOME that points at the base directory of your JDK
  installation, and add the directory "$JAVA_HOME/bin" to your PATH variable.

- Download and install an XML parser that is compatible with the Java
  API for XML Parsing (JAXP) specification.  A useful XML parser is the
  JAXP Reference Implementation, version 1.0.1 or later, that is available
  at <http://java.sun.com/xml>.  Another JAXP-compatible parser that has
  been reported to work fine with Struts is Xerces, version 1.1.2 or later,
  available at <http://xml.apache.org>.  Be sure to add the "jaxp.jar" and
  "parser.jar" (or whatever JAR file comes with your parser) files to
  your CLASSPATH environment variable.

- Download and install the JDBC 2.0 Optional Package Binary (formerly known
  as the Standard Extensions package) from the Java Software web site
  <http://java.sun.com/products/jdbc>, and install the "jdbc2_0-stdext.jar"
  file on your classpath (or as a system extension).

- (*) Download and install a servlet container that supports the Servlet
  API Specification, version 2.2 or later, and the JavaServer Pages (JSP)
  Specification, version 1.1 or later.  A useful servlet container is
  Tomcat, version 3.2 or later, that is available at
  <http://jakarta.apache.org>.

- (*) Download and unpack a Struts binary distribution, available from
  <http://jakarta.apache.org/builds/jakarta-struts/nightly/>.

- (*) Install the Struts documentation application by deploying file
  "lib/struts-documentation.war" into your servlet container, using the
  standard techniques supported by that container.  (For Tomcat, simply
  copy this file to the $TOMCAT_HOME/webapps directory and restart Tomcat).

- Install the Struts example application by deploying file
  "lib/struts-example.war" into your servlet container, using the standard
  techniques supported by that container.  (For Tomcat, simply copy this
  file to the $TOMCAT_HOME/webapps directory and restart Tomcat).

- (*) Copy the files "lib/struts*.tld" from the Struts distribution into the
  "WEB-INF" directory of your web application.

- (*) Copy the file "lib/struts.jar" from the Struts distribution into the
  "WEB-INF/lib" directory of your web application.

- (*) Modify your "WEB-INF/web.xml" file 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.  Normally, you will map
  the controller servlet to a wildcard pattern ("/execute/*") or a filename
  extension pattern ("*.do").  Use the "WEB-INF/web.xml" file from the
  example application (see below) for an example of how this is done.

- (*) Modify the "WEB-INF/web.xml" file for your web application to include
  a tag library declaration like this for each Struts tag library you will
  be using:

	<taglib>
	    <taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
	    <taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
	</taglib>

- Create a file "WEB-INF/struts-config.xml" that defines the mappings for your
  requests to specific action classes.  Use the "struts-config.xml" file from
  the example application (see below) as a guide.

- (*) In each JSP page that will use the Struts custom tags, add a line at
  the top of the page like this (for each Struts tag library needed):

	<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="struts-bean" %>

  (If you wish, you can use a prefix other that "struts-bean").

- When compiling your web application components, be sure that the
  "struts.jar" file (copied above) is included on the CLASSPATH environment
  variable used by your Java compiler.


The Struts Documentation Application
------------------------------------

Struts comes with a web application that contains all of the documentation
relevant to an application developer who wants to use it, including:
* Reference manual for the custom tag library
* User's Guide for applications based on the framework
* API documentation for the Struts classes

To view this documentation, deploy the file "webapps/struts-documentation.war"
into your servlet container, and use a web browser to access a URL like this:

	http://localhost:8080/struts-documentation

For notes about installing Struts applications on various servlet containers,
please see the INSTALL document in the same directory as this README file.


The Struts Example Application
------------------------------

Struts comes with an example web application, which was installed into your
servlet container if you followed the steps above.  This example is the
beginnings of a portal application that would allow users to register
themselves, and maintain a set of subscriptions they own to mail servers
elsewhere on the Internet.  When completed, this application will provide
the ability to read mail from various mail servers, through the application.

In the absence of detailed documentation, this application can serve as a
guide to using the interesting features of Struts.  You will find the source
code to the JSP pages associated with the example in directory "web/example",
and the source code to the Java classes in directory "src/example".  The
source code to the Struts components themselves is in directory "src/share".

To run the example application, deploy the file "webapps/struts-example.war"
into your servlet container, and use a web browser to access a URL like this:

	http://localhost:8080/struts-example

You can register yourself as a new user, or log on with username "user" and
password "pass".

For notes about installing Struts applications on various servlet containers,
please see the INSTALL document in the same directory as this README file.


Using the Struts Source Distribution
------------------------------------

If you wish to contribute to the development of the Struts toolkit, you should
download and install a source distribution of Struts from
<http://jakarta.apache.org/builds/jakarta-struts/nightly/src>.  You will also
need a recent nightly build of the Ant project development tool (you *must*
use version 1.3 or later of Ant).

Before committing any changes to the Struts CVS repository, you must do a
"build clean" followed by a "build dist", to ensure that everything compiles
and builds cleanly.