This section shows you how to download and set up the Apache Struts software.

2.1 Downloading and Configuring Struts

1. Download the Struts zip file.
   Start at http://jakarta.apache.org/site/binindex.cgi, or follow the link from http://jakarta.apache.org/struts/. I'm using Struts 1.1 in this tutorial.
2. Unzip into a directory of your choice.
   For example, unzip into C:\jakarta-struts-1.1. Throughout the rest of this tutorial, I'll refer to this location as struts_install_dir.
3. Update your CLASSPATH.
   Add struts_install_dir/lib/struts.jar to the CLASSPATH used by your compiler or IDE (not your server). Here are three possible ways of setting it:
   • Set it in your autoexec.bat file. E.g., on Windows if you unzipped into C:\jakarta-struts-1.1, you would add the following to C:\autoexec.bat:
     set CLASSPATH=C:\jakarta-struts-1.1\lib\struts.jar;%CLASSPATH%
     On Unix/Linux, use your .cshrc, .bashrc, or .profile instead.
   • Set it using the system settings. On WinXP, go to the Start menu and select Control Panel, then System, then the Advanced tab, then the Environment Variables button. On Win2K/WinNT, go to the Start menu and select Settings, then Control Panel, then System, then Environment. Either way, enter the CLASSPATH value from the previous bullet.
   • Set it in your editor or IDE. Most IDEs have a way of specifying the JAR files needed to compile projects. Or, you could make a small .bat file (Windows) or shell script (Unix/Linux) that supplies the struts.jar file as the argument to -classpath for javac.
4. Install an XML parser.
   If you have JDK 1.4 or Apache Tomcat, this step is not necessary, since they already come with an XML parser. But, if you use JDK 1.2 or 1.3 with another server, you might need to obtain the XML parsing libraries. Here are two good sources:
   • http://xml.apache.org/
   • http://java.sun.com/xml/

2.2 Testing Struts

1. Install struts-blank.war.
   Install the Web application from struts_install_dir/webapps/struts-blank.war on your server. For example, with Apache Tomcat, copy struts_install_dir/webapps/struts-blank.war to tomcat_install_dir/webapps/.
2. Start or restart the server.
   Most servers only recognize new Web apps when the server is started.
3. Access http://localhost/struts-blank/.
   This URL assumes you are running the server on your desktop and are using port 80. In general, access http://hostname:port/struts-blank/. You should see something like the following.

   

2.3 Setting Up Struts Applications

To make your own Struts application, you need to create a Web application that has the appropriate JAR files, TLD files, and web.xml entries. You almost always do this by starting with the struts-blank application and modifying it. You have three options for doing this:

• Option 1 (Good): Copy/rename the struts-blank directory to your development directory.
  When you tested your Struts installation, you ran the struts-blank Web app. When you did so, Tomcat and most other servers unpacked the struts-blank.war file into the struts-blank directory. So, copy that directory to whatever location you use for developing custom Web applications, and rename it to whatever app name you choose. For example, if you are using Tomcat and devel_dir is the location you use for development, copy the tomcat_install_dir/webapps/struts-blank directory to devel_dir, rename it to struts-test, resulting in devel_dir/struts-test.
• Option 2 (Good): Unjar struts-blank.war into your development directory.
  If your server doesn't automatically unpack WAR files, then even if you ran the struts-blank test described above, you have no regular directory to work with. Besides, some people prefer to unpack the WAR file themselves anyhow. To do so:
  1. Copy struts_install_dir/webapps/struts-blank.war to your development directory.
  2. Make a new directory (e.g., called struts-test).
  3. Unjar struts-blank.war into that directory You can use jar -xvf or a standard zip tool like WinZip or the Windows XP explorer.
  4. Whenever you want to test your application, copy struts-test to the server's Web application autodeploy directory (e.g., onto the shortcut to tomcat_install_dir/webapps).
• Option 3 (Bad): Rename struts-blank and leave it in the server's deployment directory.
  It is quite common to work directly in server's deployment directory (e.g., to work directly in tomcat_install_dir/webapps/struts-test). However, this approach scales poorly to real applications, makes it harder to test changes (you have no stable working version), and doesn't support your "real" deployment server anyhow (which is almost certainly not your desktop machine). If you don't have a good deployment system using your IDE or ant scripts, you can easily make a shortcut (Windows) or symbolic link (Unix/Linux) to the server's autodeploy directory, and just copy the Web app onto the shortcut each time. For example, suppose you are using Tomcat on Windows. To easily develop in one directory and then deploy in another, just do this:
  1. Grab tomcat_install_dir/webapps with your right mouse, drag it into devel_dir, release, and choose "Create Shortcut Here".
  2. Create struts-test or other applications as subdirectories within devel_dir, as described above.
  3. Deploy by using the right mouse to drag struts-test onto the shortcut from step 1, releasing, and choosing "Copy".

2.4 Accessing Struts Documentation

You probably already have bookmarked the APIs for standard Java, servlets, and JSP. But you will also want to frequently refer to the Apache Struts documentation. You can do this two ways:

• Read a local copy.
  This is fastest, but the documentation can get a bit out of date. To read a local copy, install the struts-documentation.war Web app. For example, if you are using Apache Tomcat on port 80 on your local machine, copy struts_install_dir/webapps/struts-documentation.war to tomcat_install_dir/webapps, restart server, and use the URL http://localhost/struts-documentation/.
• Read it from the Apache site.
  This option is slower, but guarantees that you get the latest versions of the documentation. To read the online version of the documentation, start at http://jakarta.apache.org/struts/learning.html. The documentation includes FAQs, user guides, tutorials, and the API in Javadoc format.

2.5 Adding Struts to an Existing Web Application

By far the easiest way to develop a Struts application is to start with struts-blank, rename it, and work from there. If that approach is an option for you, do it that way and skip this section. However, if you already have an existing Web application and want to add Struts capabilities to it, starting with struts-blank won't work. Adding Struts capabilities to existing Web apps is a huge pain in the neck, and will proably require several attempts to get it right. Here is a quick summary:

• Copy JAR files from struts-blank/WEB-INF/lib to your_web_app/WEB-INF/lib.
• Copy TLD files from struts-blank/WEB-INF to your_web_app/WEB-INF.
• Copy struts-config.xml from struts-blank/WEB-INF to your_web_app/WEB-INF.
• Copy the application properties file from struts-blank/WEB-INF/classes/resources to your_web_app/WEB-INF/classes/resources.
• If you plan on using the automatic validator (see Section 5, Validating User Input), copy validation.xml and validator-rules.xml from struts-blank/WEB-INF to your_web_app/WEB-INF.
• If you plan on using Tiles (see Section 6, Composing Pages with Tiles), copy struts-tiles.xml from struts-blank/WEB-INF to your_web_app/WEB-INF.
• Copy declarations out of struts-blank/WEB-INF/web.xml into your_web_app/WEB-INF/web.xml. Most importantly, copy the servlet and servlet-mapping entries that map *.do to org.apache.struts.action.ActionServlet. Be sure you keep the entries in the same locations: the order of elements in web.xml matters.

Next section: Processing Requests with Action Objects

More Information

J2EE Short Courses Personally developed and taught by the author of Core Servlets & JSP, More Servlets & JSP, and this Jakarta Struts tutorial. Programming with Servlet & JSP Technology. Fast-paced, hands-on course for developers who know Java but have little or no experience with servlets and JSP. Offered June 20-23 in Columbia, MD. Jakarta Struts and Advanced Servlet & JSP Programming. Advanced hands-on course for developers with significant previous experience with servlets and JSP. Offered June 26-30 in Columbia, MD. Web App Development with JavaServer Faces (JSF). Advanced hands-on course for developers with significant previous experience with servlets and JSP. Offered July 11-13 in Columbia, MD. Applying Jakarta Struts. Advanced Struts course for those with significant previous JSP and servlet experience. On-site Training Courses: JSP, Servlets, Jakarta Struts, JSF, AJAX, and Java 5. Customizable courses taught by Marty at your organization. Choose any combination of topics from Marty's Java 5, JSP, servlet, Struts, JSF, and AJAX courses. Available in any country. Contact Marty Send email to hall@coreservlets.com to report errors and omissions in this writeup, or to inquire about training courses on Struts, JSP, servlets, JSF, AJAX, or Java 5 programming.

References Jakarta Struts home page. Jakarta Struts documentation. JSP and servlet programming resources. Servlet 2.3 and JSP 1.2 API. Servlet 2.4 API. JSP 2.0 API. JSP, servlet, and Struts training and consulting Jakarta Struts Books Struts in Action: Building Web Applications with the Leading Java Framework. Programming Jakarta Struts. Professional Jakarta Struts. Servlet & JSP Books Core Servlets and JavaServer Pages, Second Edition. Free online version of the First Edition of Core Servlets and JavaServer Pages. In PDF. Free Online Edition of More Servlets and JavaServer Pages. In PDF.