<?xml version="1.0"?>
<!--
    $Id: installation-1_0.xml 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<document url="installation-1.0.html">

    <properties>
        <title>Installation (1.0)</title>
    </properties>

    <body>

        <section name="Prerequisite Software" href="Prerequisites">

            <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>
                    .
                </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>
                    (version 3.1
                    or later required, version 3.2 or later recommended).
                </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.0 or later. You can download and install
                    the JAXP
                    <a href="http://java.sun.com/xml">reference
                        implementation</a>
                    ,
                    which is required for building the Struts source
                    distribution. 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.3 or later
                    of the
                    <a href="http://jakarta.apache.org/ant">Ant</a>
                    build system.
                    This package is also strongly recommended for use in
                    developing your
                    own web applications based on Struts.
                    <ul>
                        <li>If you are using the release version of Ant
                            version 1.3, you will
                            also need to download the "optional.jar" file that
                            contains the
                            implementation of Ant's
                            <code>&lt;style&gt;</code>
                            command.
                        </li>
                        <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>
                    </ul>
                </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>Xalan XSLT Processor</strong>
                    - If you are building Struts from
                    the source distribution, you must download and install
                    version 1.2
                    (problems have been reported with current versions of
                    Xalan 2.0)
                    of the
                    <a href="http://xml.apache.org/xalan">Xalan</a>
                    XSLT processor (which also includes the Xerces XML
                    parser), or use the
                    version of Xalan included in the JAXP 1.1 release. This
                    processor is used to convert the Struts documentation from
                    its internal
                    XML-based format into the HTML that is presented in the
                    Struts
                    documentation application.
                </li>
            </ul>

        </section>

        <section name="Install A Struts Binary Distribution"
                 href="Installing">

            <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/struts.jar</strong>
                    - This JAR file contains all of the
                    Java classes included in Struts. It should be copied into
                    the
                    <code>WEB-INF/lib</code>
                    directory of your web application.
                    <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 will
                    like cause you
                    to encounter ClassNotFoundException problems unless
                    <em>all</em>
                    of
                    your application classes are stored in the shared
                    repository.
                </li>
                <li>
                    <strong>lib/struts*.tld</strong>
                    - These are the "tag library
                    descriptor" files that describe the custom tags in the
                    various Struts
                    tag libraries. They should be copied into the
                    <code>WEB-INF</code>
                    directory of your web application.
                </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://jakarta.apache.org/struts">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-example.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/struts-exercise-taglib.war</strong>
                    - This web
                    application contains test pages for the various custom
                    tags supported
                    by 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>webapps/struts-template.war</strong>
                    - This web application
                    both introduces and demonstrates the Struts template tags.
                </li>
                <li>
                    <strong>webapps/struts-upload.war</strong>
                    - This web application
                    is a quick example of uploading files using the Struts
                    framework.
                </li>
            </ul>

            <p>To use Struts in your own application, you will need to follow
                these steps:</p>
            <ul>
                <li>Copy the file
                    <code>lib/struts.jar</code>
                    from the Struts distribution
                    into the
                    <code>WEB-INF/lib</code>
                    directory of your web application.
                </li>
                <li>Copy the all of the files that match
                    <code>lib/struts*.tld</code>
                    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>&lt;servlet&gt;</code>
                    element to define the
                    controller servlet, and a
                    <code>&lt;servlet-mapping&gt;</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:
                </li>
            </ul>

            <pre>&lt;taglib&gt;
                &lt;taglib-uri&gt;/WEB-INF/struts-bean.tld&lt;/taglib-uri&gt;
                &lt;taglib-location&gt;/WEB-INF/struts-bean.tld&lt;/taglib-location&gt;
                &lt;/taglib&gt;

                &lt;taglib&gt;
                &lt;taglib-uri&gt;/WEB-INF/struts-html.tld&lt;/taglib-uri&gt;
                &lt;taglib-location&gt;/WEB-INF/struts-html.tld&lt;/taglib-location&gt;
                &lt;/taglib&gt;

                &lt;taglib&gt;
                &lt;taglib-uri&gt;/WEB-INF/struts-logic.tld&lt;/taglib-uri&gt;
                &lt;taglib-location&gt;/WEB-INF/struts-logic.tld&lt;/taglib-location&gt;
                &lt;/taglib&gt;

                &lt;taglib&gt;
                &lt;taglib-uri&gt;/WEB-INF/struts-template.tld&lt;/taglib-uri&gt;
                &lt;taglib-location&gt;/WEB-INF/struts-template.tld&lt;/taglib-location&gt;
                &lt;/taglib&gt;
            </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>&lt;%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %&gt;
                &lt;%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %&gt;
                &lt;%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;
                &lt;%@ taglib uri="/WEB-INF/struts-template.tld"
                prefix="template" %&gt;
            </pre>

            <ul>
                <li>When compiling the Java classes that comprise your
                    application, be sure
                    to include the
                    <code>struts.jar</code>
                    file (copied earlier) on the
                    CLASSPATH that is submitted to the compiler.
                </li>
            </ul>
        </section>

        <section name="Installing Struts with your servlet container"
                 href="Containers">

            <p>
                <strong>WARNING</strong>
                - Do
                <strong>NOT</strong>
                add
                <code>struts.jar</code>
                to the classpath of your servlet container in an
                attempt to avoid placing it in the
                <code>/WEB-INF/lib</code>
                directory of
                each individual web app! Doing so will cause problems with
                <code>ClassNotFoundException</code>
                exceptions.
            </p>

            <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>Status of various containers</h4>
            <ul>
                <li>Bluestone Universal Business Server -
                    <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>Orion Application Server -
                    <a href="installation-oas.html">Additional steps
                        required.</a>
                </li>
                <li>Resin 1.2+ "standalone" - 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>Weblogic -
                    <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>
        </section>


        <section name="Building Struts From Source" href="Building">

            <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>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>

        </section>

    </body>
</document>
