$Id: README,v 1.1 2000/05/31 22:28:09 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 Slide in your own web applications by following these steps: - Download and install a version 1.1 or later Java Development Kit implementation for your operating system platform. Note that some Struts classes require Java2 (that is, JDK 1.2.2 or later) to operate successfully. 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 . 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 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.1 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 file "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: /WEB-INF/struts.tld /WEB-INF/struts.tld - Create a file "WEB-INF/action.xml" that defines the mappings for your requests to specific action classes. Use the "action.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: <%@ taglib uri="/WEB-INF/struts.tld" prefix="struts" %> (If you wish, you can use a prefix other that "struts"). - 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 a developer (that is, it will when the docs are written :-). To view this documentation, deploy it on your servlet container, and use a web browser to access a URL like this: http://localhost:8080/struts-documentation 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 it on 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". 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 a version later than the Ant 3.1 release). 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.