<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <title>The Struts Framework Project - Installation (1.1)</title> <meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta content="Craig R. McClanahan" name="author" /> <meta content="Mike Schachter" name="author" /> <meta content="Ted Husted" name="author" /> <meta content="Martin Cooper" name="author" /> <meta content="Chris Assenza" name="author" /> <meta content="dIon Gillard" name="author" /> <meta content="Eric Wu" name="author" /> <meta content="John Rousseau" name="author" /> <meta content="John Ueltzhoeffer" name="author" /> <meta content="Mark Budai" name="author" /> <meta content="Paul Runyan" name="author" /> <meta content="Robert Hayden" name="author" /> <meta content="Stanley Santiago" name="author" /> <meta content="Wong Kok Kai" name="author" /> <meta content="Rob Leland" name="author" /> <meta content="John Berry" name="author" /> <link href="../struts.css" type="text/css" rel="stylesheet" /> </head> <body> <div id="heading"> <a href="http://apache.org/"> <img id="asf_logo_wide" alt="The Apache Project" src="../images/asf_logo_wide.gif" /> </a> <a href="http://struts.apache.org/"> <img id="struts-logo" alt="Struts Framework" src="../images/struts.gif" /> </a> </div> <!--end heading--> <div id="content"> <div id="menu"> <p>User Guide</p> <ul> <li> <a href="index.html">Table of Contents</a> </li> <li> <a href="preface.html">Preface</a> </li> <li> <a href="introduction.html">Introduction</a> </li> <li> <a href="building_model.html">Model Components</a> </li> <li> <a href="building_view.html">View Components</a> </li> <li> <a href="building_controller.html">Controller Components</a> </li> <li> <a href="configuration.html">Configuration</a> </li> <li> <a href="release-notes.html">Release Notes</a> </li> <li> <a href="installation.html">Installation</a> </li> </ul> <p>Developer Guides</p> <ul> <li> <a href="dev_bean.html">Bean Tags</a> </li> <li> <a href="dev_html.html">HTML Tags</a> </li> <li> <a href="dev_logic.html">Logic Tags</a> </li> <li> <a href="dev_nested.html">Nested Tags</a> </li> <li> <a href="dev_tiles.html">Tiles Tags</a> </li> <li> <a href="dev_util.html">Utilities</a> </li> <li> <a href="dev_validator.html">Validator</a> </li> </ul> <p>Quick Links</p> <ul> <li> <a href="../index.html">Welcome</a> </li> <li> <a href="index.html">User and Developer Guides *</a> </li> <li> <a href="../faqs/index.html">FAQs and HowTos</a> </li> </ul> <div class="authors"> <p> <strong>Contributors</strong> </p> <ul> <li>Craig R. McClanahan</li> <li>Mike Schachter</li> <li>Ted Husted</li> <li>Martin Cooper</li> <li>Chris Assenza</li> <li>dIon Gillard</li> <li>Eric Wu</li> <li>John Rousseau</li> <li>John Ueltzhoeffer</li> <li>Mark Budai</li> <li>Paul Runyan</li> <li>Robert Hayden</li> <li>Stanley Santiago</li> <li>Wong Kok Kai</li> <li>Rob Leland</li> <li>John Berry</li> </ul> </div> </div> <!--end menu--> <div id="main"> <h1 id="installation">6.2 Installation</h1> <h2 id="Prerequisites">Prerequisite Software</h2> <div class="indent"> <p>The Struts binary distribution needs three other software packages installed to operate. You may already have these installed on your system. To build Struts from source you may need to acquire and install several others. The complete list is as follows:</p> <ul> <li> <strong>Java Development Kit</strong> - You <strong>must</strong> 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 <a href="http://java.sun.com/j2se">http://java.sun.com/j2se</a>. To build Struts, Java 1.4.2 (the latest production JDK) is suggested. </li> <li> <strong>Servlet Container</strong> - You <strong>must</strong> 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 <a href="http://jakarta.apache.org/tomcat/">Tomcat</a>, but any compliant container should work well with Struts.</li> <li> <strong>XML Parser</strong> - Struts <strong>requires</strong> the presence of an XML parser that is compatible with the Java API for XML Parsing (JAXP) specification, 1.1 or later. This is bundled with J2SE 1.4 and later. For earlier versions of Java, the easiest way to obtain JAXP is probably by downloading the Web Services Developers Kit (1.1 or later!). See the <a href="http://java.sun.com/xml/jaxp/faq.html#jaxp-ri-latest"> Sun JAXP FAQ</a> for more information.) In Struts-based web applications, you may replace the reference implementation classes with any other JAXP compliant parser, such as <a href="http://xml.apache.org/xerces-j">Xerces</a>. See detailed instructions related to the parser in the instructions for <a href="#Building">building</a> and <a href="#Installing">installing</a> Struts, below.</li> <li> <strong>Ant Build System</strong> - If you are building Struts from the source distribution, you must download and install version 1.5.4 (or later) of the <a href="http://jakarta.apache.org/ant">Ant</a> build system. <ul> <li>Make sure that the "ant" and "ant.bat" scripts are executable, by adding the $ANT_HOME/bin directory to your PATH environment variable.</li> <li> Copy and review either the "build.properties.sample" or "build.properties.sample.lib" file as "build.properties". The latter is recommended if you are not active in Jakarta Commons development. </li> <li> <a href="http://maven.apache.org/">Maven</a> property files are also provided, but the Maven build is still experimental. New developers may find Maven easier to use, since it acquires the appropriate JARs automatically. </li> </ul> </li> <li> <strong>Servlet API Classes</strong> - In order to compile Struts itself, or applications that use Struts, you will need a <code>servlet.jar</code> 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 <a href="http://jakarta.apache.org/builds/jakarta-servletapi">here</a>. </li> <li> <strong>JDBC 2.0 Optional Package Classes</strong> - Struts supports an optional implementation of <code>javax.sql.DataSource</code>, so it requires the API classes to be compiled. They can be downloaded from <a href="http://java.sun.com/products/jdbc/download.html">http://java.sun.com/products/jdbc/download.html</a>.</li> <li> <strong>Other Packages</strong> - Struts utilizes several packages from other open source projects, especially the <a href="http://jakarta.apache.org/commons/">Jakarta Commons Project</a>. These are the packages which must be available if you wish to build Struts from source: <ul> <li> <a href="http://www.antlr.org/">ANTLR</a> (Version 2.7.2)</li> <li> <a href="http://jakarta.apache.org/commons/beanutils/">Jakarta Commons Beanutils</a> (Version 1.7.0)</li> <li> <a href="http://jakarta.apache.org/commons/digester/">Jakarta Commons Digester</a> (Version 1.6)</li> <li> <a href="http://jakarta.apache.org/commons/fileupload/">Jakarta Commons FileUpload</a> (Version 1.0)</li> <li> <a href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</a> (Version 1.0.4)</li> <li> <a href="http://jakarta.apache.org/commons/validator/">Jakarta Commons Validator</a> (Version 1.1.4) </li> <li> <a href="http://jakarta.apache.org/oro/">Jakarta ORO</a> (Version 2.0.7)</li> </ul> ANTLR is a <a href="http://antlr.org/license.html">public domain library</a>; all other libraries are distributed under the <a href="http://www.apache.org/licenses/">Apache Software License</a>. For your convenience, the requisite JARs are provided as a single download under the <code>lib</code> sub-directory with each release distribution. Please note that the minimum requirements may change between releases, and some JARs may need to be updated to use the latest Nightly Build. </li> <li> <strong>Xalan XSLT Processor</strong> - If you are building Struts from the source distribution, you will need a version of Xalan to perform XSLT transformations. If you are using the JAXP/1.1 XML parser, you should use the version of <code>xalan.jar</code> shipped with it. Otherwise, download and install version 1.2 of Xalan from <a href="http://xml.apache.org/xalan">here</a>. </li> <li> <strong>Unit tests</strong> - To verify your build against the JUnit and Cactus unit tests, three other packages must be available: <ul> <li> <a href="http://jakarta.apache.org/cactus">Jakarta Cactus</a> (Version 1.4.1)</li> <li> <a href="http://jakarta.apache.org/commons/lang/">Jakarta Commons Lang</a> (Version 2.0)</li> <li> <a href="http://www.junit.org">JUnit</a> (Version 3.8.1)</li> </ul> </li> </ul> </div> <h2 id="Installing">Install A Struts Binary Distribution</h2> <div class="indent"> <p>First, download a binary distribution of Struts by following the instructions <a href="../acquiring.html">here</a>. Then, make sure you have downloaded and installed the <a href="#Prerequisites">prerequisite</a> software packages described above.</p> <p>Unpack the Struts binary distribution into a convenient directory. (If you <a href="#Building">build Struts from the source distribution</a>, the result of the build will already be an unpacked binary distribution for you). The distribution consists of the following contents:</p> <ul> <li> <strong>lib/*.jar</strong> - The struts.jar contains the Java classes distributed by the Struts project. The other JAR files contain packages from other projects that are imported by Struts. When you launch a Struts-based application, these JARs need to be available to your application, usually by copying them to the application's <code>WEB-INF/lib</code> directory. <br /> <em>WARNING</em> - If you are going to be hosting multiple Struts based applications on the same servlet container, you will be tempted to place the <code>struts.jar</code> file into the shared repository supported by your container. Be advised that this may cause ClassNotFoundException problems unless <em>all</em> of your application classes are stored in the shared repository.</li> <li> <strong>lib/*.tld</strong> - These are the "tag library descriptor" files that describe the custom tags in the various Struts tag libraries. The tld file for any Struts taglibs that you use should be copied into the <code>WEB-INF</code> directory of your web application. (Applications under Servlet 2.3 containers can omit this step if the <a href="configuration.html#dd_config_taglib_23">standard uri</a> is referenced.)</li> <li> <strong>webapps/struts-blank.war</strong> - This is a simple "web application archive" file containing a basic starting point for building your own Struts-based applications.</li> <li> <strong>webapps/struts-documentation.war</strong> - This is a "web application archive" file containing all of the Struts documentation found on the <a href="http://struts.apache.org/">Struts web site</a> (including these pages). You can install this web application on any servlet container compatible with Servlet API 2.2 or later.</li> <li> <strong>webapps/struts-examples.war</strong> - This "modular" applications combines several usefule demonstrations: <ul> <li>Exercise-Taglib - This application module contains test pages for the various custom tags distributed with 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.</li> <li> <strong>Upload</strong> - This application module is a quick example of uploading files using the Struts framework. </li> <li> <strong>Validator</strong> - This application module is an example of using the validator framework, using both the server-side and optional client-side validation. </li> </ul> </li> <li> <strong>webapps/struts-mailreader.war</strong> - 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.</li> <li> <strong>webapps/tiles-documentation.war</strong> - This web application documents how to use tiles, and was developed using tiles.</li> </ul> <p>To use Struts in your own application, you will need to follow these steps:</p> <ul> <li>Copy the <code>lib/*.jar</code> files from the Struts distribution into the <code>WEB-INF/lib</code> directory of your web application.</li> <li>Copy the <code>lib/*.tld</code> files for any Struts taglibs you use from the Struts distribution into the <code>WEB-INF</code> directory of your web application.</li> <li>Modify the <code>WEB-INF/web.xml</code> file for your web application to include a <code><servlet></code> element to define the controller servlet, and a <code><servlet-mapping></code> element to establish which request URIs are mapped to this servlet. Use the <code>WEB-INF/web.xml</code> file from the Struts example application for a detailed example of the required syntax.</li> <li>Modify the <code>WEB-INF/web.xml</code> file of your web application to include the following tag library declarations (Servlet 2.3 can omit this step if the <a href="configuration.html#dd_config_taglib_23">standard uri</a> is referenced):</li> </ul> <pre><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> </pre> <ul> <li>Create a file <code>WEB-INF/struts-config.xml</code> that defines the action mappings and other characteristics of your specific application. You can use the <code>struts-config.xml</code> file from the Struts example application for a detailed example of the required syntax.</li> <li>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:</li> </ul> <pre><%@ taglib uri="/tags/struts-bean" prefix="bean" %> <%@ taglib uri="/tags/struts-html" prefix="html" %> <%@ taglib uri="/tags/struts-logic" prefix="logic" %> </pre> <ul> <li>When compiling the Java classes that comprise your application, be sure to include the JAR files (copied earlier) on the CLASSPATH that is submitted to the compiler.</li> </ul> </div> <h2 id="Containers">Installing Struts With Your Servlet Container</h2> <div class="indent"> <p>For most containers, you need only to: </p> <ul> <li>Copy the WAR files in your Struts <code>/webapp</code> directory to your containers <code>webapps</code> directory. </li> <li>In some cases, you may need to restart your container if it is running.</li> </ul> <h4>Running Struts Applications Under A Security Manager</h4> <p>Many application servers execute web applications under the control of a Java security manager, with restricted permissions on what classes in the web application can do. If you utilize form beans with mapped properties, you may encounter security exceptions unless you add the following permission to the set of permissions granted to your Struts application's codebase:</p> <pre> permission java.lang.RuntimePermission "accessDeclaredMembers"; </pre> <p>Consult the documentation on your application server for more information about how to configure additional security manager permissions.</p> <h4>Installing Struts on Various Containers</h4> <ul> <li>Bluestone Universal Business Server 7.2 - <a href="installation-ubs72.html">Additional steps required.</a> </li> <li>Borland Application Server 4.5 -No additional steps required.</li> <li>iPlanet Application Server - Service Pack 2 is recommended. Note that the database object in the Struts-Example application is not compatible with this container.</li> <li>iPlanet Web Server - <a href="installation-ip.html">Additional steps required.</a> </li> <li>iPortal Application Server - <a href="installation-ipas.html">Additional steps required.</a> </li> <li>Jetty - <a href="installation-jetty.html">Additional steps required.</a> </li> <li>JRun - <a href="installation-jr30.html">Additional steps required.</a> </li> <li>Novell ExteNd Application Server 4.0+ - <a href="installation-novell.html">Additional steps required.</a> </li> <li>Orion Application Server - <a href="installation-oas.html">Additional steps required.</a> </li> <li>Resin 1.2+ "standalone" - No additional steps required.</li> <li>RexIP - No additional steps required.</li> <li>SilverStream 3.7.1 and later - <a href="installation-sas.html">Additional steps required.</a> </li> <li>Tomcat 3.1 and prior - Not recommended. Use Tomcat 3.2.1 or later.</li> <li>Tomcat 3.2.1 with Apache - <a href="installation-tc.html">Additional steps required.</a> </li> <li>Tomcat 3.2.1+ "standalone" - No additional steps required.</li> <li>Tomcat 4.0 - No additional steps required.</li> <li>Trifork Enterprise Application Server 3.3.x - No additional steps required.</li> <li>Weblogic 5.1 sp8 - <a href="installation-wls5.html">Additional steps required.</a> </li> <li>WebLogic 6.0+ - No additional steps required.</li> <li>WebSphere - <a href="installation-was352.html">Additional steps required.</a> </li> <li>WebSphere - <a href="installation-was352-x.html">Steps for the Example Application.</a> </li> </ul> </div> <h2 id="Building">Building Struts From Source</h2> <div class="indent"> <p>First, download a source distribution of Struts by following the instructions <a href="../acquiring.html">here</a>. Then, make sure you have downloaded and installed <strong>all</strong> of the <a href="#Prerequisites">prerequisite</a> software packages described above.</p> <p>To build Struts, you will need to customize the build process to the details of your development environment as follows:</p> <ul> <li>The Struts source distribution uses a file named <code>build.properties</code> (in the top-level directory of the distribution) to identify the location of external components that Struts depends on.</li> <li>There is no <code>build.properties</code> file included with the source distribution. However, there is an example file named <code>build.properties.example</code> that you can copy to <code>build.properties</code> and then customize.</li> <li>The properties you must configure in <code>build.properties</code> are: <ul> <li> <strong>catalina.home</strong> - Pathname to the directory of your binary distribution of Tomcat 4.0 (required only if you wish to use the <code>deploy.catalina</code> target).</li> <li> <strong>commons-beanutils.jar</strong> - Pathname of the BeanUtils package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-collections.jar</strong> - Pathname of the Collections package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-digester.jar</strong> - Pathname of the Digester package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-fileupload.jar</strong> - Pathname of the Fileupload package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-lang.jar</strong> - Pathname of the Lang package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-logging.jar</strong> - Pathname of the Logging package JAR file from the Jakarta Commons project.</li> <li> <strong>commons-validator.jar</strong> - Pathname of the Validator package JAR file from the Jakarta Commons project.</li> <li> <strong>servletapi.home</strong> - Pathname to the directory of your binary distribution of the Servlet API classes.</li> <li> <strong>tomcat.home</strong> - Pathname to the directory of your binary distribution of Tomcat 3.2 (required only if you wish to use the <code>deploy.tomcat</code> target).</li> <li> <strong>xerces.home</strong> - 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 <code>deploy.catalina</code> target).</li> </ul> </li> <li>If you are a Struts developer with write access to the CVS repository, be sure that you do <strong>NOT</strong> check in a copy of the <code>build.properties</code> file, since it will be different for each individual developer.</li> </ul> <p>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 <code>build.properties</code> file as described above. Then, type:</p> <pre> ant dist </pre> <p>This command will create a binary distribution of Struts, in a directory named <code>dist</code> (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 <a href="#Installing">preceding section</a>.</p> <p>IMPORTANT NOTE: The <code>struts.jar</code>, as well as the JAR files from the Jakarta Commons project, must be in your classpath when compiling Struts. The <code>build.xml</code> provided does this automatically. If you use your development machine to test Struts application locally, be sure that the <code>struts.jar</code> is <strong>NOT</strong> on your classpath when your container is running. </p> </div> <hr class="section" /> <div class="indent"> <p class="right"> Next: <a href="../faqs/index.html">FAQs and HowTos</a> </p> </div> </div> <!--end main--> </div> <!--end content--> <div id="footer"> <img id="powered-logo" alt="Powered by Struts" src="../images/struts-power.gif" /> Copyright (c) 2000-2005, The Apache Software Foundation <span class="noprint">- <a href="http://wiki.apache.org/struts/StrutsDocComments">Comments?</a> </span> </div> <!--end footer--> </body> </html>