$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 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 . Another JAXP-compatible parser that has been reported to work fine with Struts is Xerces, version 1.1.2 or later, available at . 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 , 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 . - (*) Download and unpack a Struts binary distribution, available from . - (*) 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 element to define the controller servlet, and a 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: /WEB-INF/struts-bean.tld /WEB-INF/struts-bean.tld - 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 . 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.