<?xml version="1.0"?>
<!--
    $Id$

    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.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>Installation</title>
    </properties>

    <body>
        <section name="6.2 Installation" href="installation">
        
            <blockquote><em><p>
            "Would you tell me, please, which way I ought to go from here?"
            </p><p>
            "That depends a good deal on where you want to get to."
            </p><p>
            "I don't much care where"
            </p><p>
            "Then it doesn't much matter which way you go."
            </p><p>
            "so long as I get somewhere."
            </p><p>
            "Oh, you're sure to do that, if only you walk long enough."
            </p></em></blockquote>
             
            <subsection name="Prerequisite Software" href="Prerequisites">

                <p>The framework's binary distribution needs three other
                    software packages installed to
                    operate. You may already have these installed on your
                    system. To build the framework 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 Java Development Kit (version 1.4 or later) 
                        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 the framework, Java 1.4.2 (the latest
                        production JDK) is suggested and
                        required if you use our Maven build system.
                    </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.3 or later, and the JavaServer Pages (JSP)
                        Specification,
                        version 1.2 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 the framework.
                    </li>

                    <li>
                        <strong>Maven Build System</strong>
                        - (optional) If you are building the framework from the
                        source distribution, you must download and install the
                        <a href="http://maven.apache.org/">Apache
                            Maven 2</a>
                        build system (2.0.4 or later).
                    </li>

                </ul>

            </subsection>

            <subsection name="Install a Library Distribution"
                        href="Installing">

                <p>First, download a binary distribution of Struts
                    by following the
                    instructions
                    <a href="http://struts.apache.org/downloads.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 Library distribution into a convenient
                    directory.
                    (If you are <a href="http://struts.apache.org/downloads.html#Building">
                    building 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-*.jars contains Java classes
                        distributed by Apache Struts. The other JAR files
                        contain packages
                        from other projects that are imported by the 
                        framework. When you launch
                        a your 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
                        applications on the same servlet container, you will
                        be tempted
                        to place the
                        <code>struts-core.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>
                </ul>

                <p>To use Struts Library in your own application, you
                    will need to follow
                    these steps:</p>
                <ul>
                    <li>Copy the
                        <code>lib/*.jar</code>
                        files from the
                        Library distribution into the
                        <code>WEB-INF/lib</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 Mailreader application
                        for a detailed example of the required syntax.
                    </li>
                    <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
                        Blank application for examples of the required syntax.
                    </li>
                    <li>At the top of each JSP page that will use JSP tags,
                        add line(s) declaring the JSP tag libraries used on
                        this particular page, like this:</li>
                </ul>

                <pre>
                    &lt;%@ taglib uri="http://struts.apache.org/tags-bean" prefix="bean" %&gt;
                    &lt;%@ taglib uri="http://struts.apache.org/tags-html" prefix="html" %&gt;
                    &lt;%@ taglib uri="http://struts.apache.org/tags-logic" prefix="logic" %&gt;
                </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>
            </subsection>
            <subsection
                    name="Installing The Framework With Your Servlet Container"
                    href="Containers">

                <p>For most containers, you need only to:</p>
                <ul>
                    <li>Copy the WAR files in your 
                        <code>/webapps</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 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 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 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 MailReader 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>
            </subsection>

            <subsection>
                <p class="right">
                    Next:
                    <a href="../faqs/index.html">FAQs and HowTos</a>
                </p>
            </subsection>

        </section>
    </body>
</document>
