<?xml version="1.0"?>
<!--
    $Id: configuration.xml 562110 2007-08-02 13:45:57Z 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.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>Configuring Applications</title>
    </properties>

    <body>
        <section name="5. Configuring Applications">

            <blockquote><p><em>
            "An author doesn't necessarily understand the meaning of his own 
            story better than anyone else."
            </em></p></blockquote>

            <a name="config-overview"/>
            <subsection name="5.1 Overview">

                <p>
                    Before you can build an application, you need to lay a
                    solid foundation.
                    There are several setup tasks you need to perform before
                    deploying
                    your application.
                    These include components in the configuration file
                    and in the Web Application Deployment Descriptor.
                </p>

            </subsection>

            <a name="struts-config"/>
            <subsection name="5.2 The configuration file">

                <p>
                    The
                    <a href="building_controller.html#4_8_Writing_Action_Mappings">
                        Writing Action
                        Mappings</a>
                    section covered writing the
                    <code>&lt;form-bean&gt;</code>
                    and
                    <code>&lt;action-mapping&gt;</code>
                    portions of the configuration file.
                    These elements usually play an important role in the
                    development of an
                    application.
                    The other elements in a configuration file tend to be
                    static:
                    you set them once and leave them alone.
                </p>

                <p>
                    These "static" configuration elements are:
                </p>

                <ul>

                    <li>
                        &lt;controller&gt;
                    </li>

                    <li>
                        &lt;message-resources&gt;
                    </li>

                    <li>
                        &lt;plug-in&gt;
                    </li>

                </ul>

            </subsection>

            <a name="controller_config"/>
            <subsection name="5.2.1 Controller Configuration">

                <p>
                    The
                    <code>&lt;controller&gt;</code>
                    element allows you to configure
                    the ActionServlet.
                    Many of the controller parameters were previously defined
                    by servlet
                    initialization parameters in your
                    <code>web.xml</code>
                    file but have been
                    moved to this section of
                    <code>struts-config.xml</code>
                    in order to allow
                    different modules in the same web application to be
                    configured differently.
                    For full details on available parameters see the
                    <a href="../struts-core/dtddoc/struts-config_1_3.dtd.html">
                        struts-config DTDDoc</a>
                    or the list below.
                </p>


                <ul>

                    <li>
                        <strong>bufferSize</strong>
                        - The size (in bytes) of the input buffer
                        used when processing file uploads.
                        [4096] (optional)
                    </li>

                    <li>
                        <strong>catalog</strong>
                        - Name of the catalog to use when processing requests
                        for this module.
                        [struts]
                    </li>

                    <li>
                        <strong>className</strong>
                        - Classname of configuration bean.
                        [org.apache.struts.config.ControllerConfig] (optional)
                    </li>

                    <li>
                        <strong>command</strong>
                        - Name of the command to execute to process a request.
                        [servlet-standard]
                    </li>

                    <li>
                        <strong>contentType</strong>
                        - Default content type (and optional character
                        encoding) to be set on each response.
                        May be overridden by the Action, JSP, or other
                        resource to which
                        the request is forwarded.
                        [text/html] (optional)
                    </li>

                    <li>
                        <strong>forwardPattern</strong>
                        - Replacement pattern defining how the "path"
                        attribute of a
                        <code>&lt;forward&gt;</code>
                        element is mapped to a
                        context-relative URL when it starts with a slash.
                        This value may consist of any combination of the
                        following:

                        <ul>

                            <li>
                                <em>$M</em>
                                - Replaced by the module prefix of this
                                module.
                            </li>

                            <li>
                                <em>$P</em>
                                - Replaced by the "path" attribute of the
                                selected
                                <code>&lt;forward&gt;</code>
                                element.
                            </li>

                            <li>
                                <em>$$</em>
                                - Causes a literal dollar sign to be rendered.
                            </li>

                            <li>
                                <em>$x</em>
                                - (Where "x" is any character not defined
                                above)
                                Silently swallowed, reserved for future use.
                            </li>

                        </ul>

                        If not specified, the default forwardPattern is
                        consistent with the
                        previous behavior of forwards.
                        [$M$P] (optional)
                    </li>

                    <li>
                        <strong>inputForward</strong>
                        - Set to
                        <code>true</code>
                        if you want the
                        <code>input</code>
                        attribute of
                        <code>&lt;action&gt;</code>
                        elements
                        to be the name of a local or global
                        <code>ActionForward</code>
                        , which
                        will then be used to calculate the ultimate URL.
                        Set to
                        <code>false</code>
                        to treat the
                        <code>input</code>
                        parameter of
                        <code>&lt;action&gt;</code>
                        elements as a module-relative path to
                        the resource to be used as the input form.
                        [false] (optional)
                    </li>

                    <li>
                        <strong>locale</strong>
                        - Set to
                        <code>true</code>
                        if you want a
                        <code>Locale</code>
                        object stored in the user's session if not already
                        present.
                        [true] (optional)
                    </li>

                    <li>
                        <strong>maxFileSize</strong>
                        - The maximum size (in bytes) of a file to be
                        accepted as a file upload.
                        Can be expressed as a number followed by a "K", "M",
                        or "G",
                        which are interpreted to mean kilobytes, megabytes, or
                        gigabytes,
                        respectively.
                        [250M] (optional)
                    </li>

                    <li>
                        <strong>memFileSize</strong>
                        - The maximum size (in bytes) of a file whose contents
                        will
                        be retained in memory after uploading. Files larger
                        than
                        this threshold will be written to some alternative
                        storage
                        medium, typically a hard disk. Can be expressed as a
                        number
                        followed by a "K", "M", or "G", which are interpreted
                        to
                        mean kilobytes, megabytes, or gigabytes, respectively.
                        ["256K"]
                    </li>

                    <li>
                        <strong>multipartClass</strong>
                        - The fully qualified Java class name of the
                        multipart request handler class to be used with this
                        module.
                        [org.apache.struts.upload.CommonsMultipartRequestHandler]
                        (optional)
                    </li>

                    <li>
                        <strong>nocache</strong>
                        - Set to
                        <code>true</code>
                        if you want the controller
                        to add HTTP headers for defeating caching to every
                        response from
                        this module.
                        [false] (optional)
                    </li>

                    <li>
                        <strong>pagePattern</strong>
                        - Replacement pattern defining how the
                        <code>page</code>
                        attribute of custom tags using it is mapped to a
                        context-relative URL of the corresponding resource.
                        This value may consist of any combination of the
                        following:

                        <ul>

                            <li>
                                <em>$M</em>
                                - Replaced by the module prefix of this
                                module.
                            </li>

                            <li>
                                <em>$P</em>
                                - Replaced by the "path" attribute of the
                                selected
                                <code>&lt;forward&gt;</code>
                                element.

                            </li>
                            <li>
                                <em>$$</em>
                                - Causes a literal dollar sign to be rendered.
                            </li>

                            <li>
                                <em>$x</em>
                                - (Where "x" is any character not defined
                                above)
                                Silently swallowed, reserved for future use.
                            </li>

                        </ul>

                        If not specified, the default pagePattern is
                        consistent with the
                        previous behavior of URL calculation.
                        [$M$P] (optional)
                    </li>
                    <li>

                        <strong>processorClass</strong>
                        - The fully qualified Java class name of the
                        <code>RequestProcessor</code>
                        subclass to be used with this module.
                        [org.apache.struts.chain.ComposableRequestProcessor]
                        (optional)
                    </li>

                    <li>
                        <strong>tempDir</strong>
                        - Temporary working directory to use when processing
                        file uploads.
                        [{the directory provided by the servlet container}]
                    </li>

                </ul>

                <p>
                    This example uses the default values for several
                    controller parameters.
                    If you only want default behavior you can omit the
                    controller section
                    altogether.
                </p>

                <source><![CDATA[
<controller
    processorClass="org.apache.struts.action.RequestProcessor"
       contentType="text/html"/>;
]]></source>

            </subsection>

            <a name="resources_config"/>
            <subsection name="5.2.2 Message Resources Configuration">

                <p>
                    The framework has built in support for
                    internationalization (I18N).
                    You can define one or more
                    <code>&lt;message-resources&gt;</code>
                    elements
                    for your webapp; modules can define their own resource
                    bundles.
                    Different bundles can be used simultaneously in your
                    application, the 'key'
                    attribute is used to specify the desired bundle.
                </p>

                <ul>

                    <li>
                        <strong>className</strong>
                        - Classname of configuration bean.
                        [org.apache.struts.config.MessageResourcesConfig]
                        (optional)
                    </li>

                    <li>
                        <strong>factory</strong>
                        - Classname of MessageResourcesFactory.
                        [org.apache.struts.util.PropertyMessageResourcesFactory]
                        (optional)
                    </li>

                    <li>
                        <strong>key</strong>
                        - ServletContext attribute key to store this bundle.
                        [org.apache.struts.action.MESSAGE] (optional)
                    </li>

                    <li>
                        <strong>null</strong>
                        - Set to
                        <code>false</code>
                        to display missing resource
                        keys in your application like '
                        <em>???keyname???</em>
                        ' instead of
                        <code>null</code>
                        .
                        [true] (optional)
                    </li>

                    <li>
                        <strong>escape</strong>
                        - Set to
                        <code>true</code>
                         if  
                         <i>escape processing</i>
                         should be performed on the error message string. 
                        [true] (optional)
                    </li>

                    <li>
                        <strong>parameter</strong>
                        - Name of the resource bundle. (required)
                    </li>

                </ul>


                <p>Example configuration:</p>

                <source><![CDATA[
<message-resources
    parameter="MyWebAppResources"
         null="false" />
]]></source>

                <p>
                    This would set up a message resource bundle provided in
                    the file
                    <code>MyWebAppResources.properties</code>
                    under the default key.
                    Missing resource keys would be displayed as '
                    <em>???keyname???</em>
                    '.
                </p>

                <p>
                </p>

                <p>
                    The default <code>PropertyMessageResources</code>
                    implementation can operate in one of three modes:
                </p>

                <ul>
                  <li><b>Default</b> - default, backwardly compatible,
                      Struts behaviour (i.e. the way its always worked).</li>
                  <li><b>JSTL</b> - compatible with how JSTL finds messages.</li>
                  <li><b>Resource</b> - compatible with how Java's 
                      <code>PropertyResourceBundle</code> finds messages.</li>
                </ul>

                <p>
                    The <i>mode</i> can be configured in the struts-config.xml 
                   (for more details see <code>PropertyMessageResources</code>
                    <a href="../apidocs/org/apache/struts/util/PropertyMessageResources.html">
                    JavaDoc</a>):.
                </p>
                <source><![CDATA[
<message-resources parameter="MyWebAppResources">
    <set-property key="mode" value="JSTL"/>
</message-resources>
]]></source>

            </subsection>

            <a name="plugin_config"/>
            <subsection name="5.2.3 PlugIn Configuration">

                <p>
                    Struts PlugIns are configured using the
                    <code>&lt;plug-in&gt;</code>
                    element within the configuration file.
                    This element has only one valid attribute, 'className',
                    which is the fully
                    qualified name of the Java class which implements the
                    <code>org.apache.struts.action.PlugIn</code>
                    interface.
                </p>

                <p>
                    For PlugIns that require configuration themselves, the
                    nested
                    <code>&lt;set-property&gt;</code>
                    element is available.
                </p>

                <p>
                    This is an example using the Tiles plugin:
                </p>

                <source><![CDATA[
<plug-in className="org.apache.struts.tiles.TilesPlugin">
    <set-property
        property="definitions-config"
           value="/WEB-INF/tiles-defs.xml"/>
</plug-in>
]]></source>

            </subsection>

            <a name="dd_config_modules"/>
            <subsection name="5.3 Configuring Your Application for Modules">

                <p>
                    Very little is required in order to start taking advantage
                    of the
                    module feature.
                    Just go through the following steps:
                </p>

                <ol>

                    <li>
                        Prepare a configuration file for each module.
                    </li>

                    <li>
                        Inform the controller of your module.
                    </li>

                    <li>
                        Use Actions to refer to your pages.
                    </li>

                </ol>

            </subsection>

            <a name="module_config-files"/>
            <subsection name="5.3.1 Module Configuration Files">

                <p>
                    Back in version 1.0, a few "boot-strap" options were placed
                    in the
                    <code>web.xml</code>
                    file, and the bulk of the configuration was done in a
                    single
                    <code>struts-config.xml</code>
                    file.
                    Obviously, this wasn't ideal for a team environment, since
                    multiple users
                    had to share the same configuration file.
                </p>

                <p>
                    Since version 1.1, you have two options: you can list
                    <a href="#dd_config">
                        multiple struts-config files</a>
                    as a
                    comma-delimited list, or you can subdivide a larger
                    application into
                    modules.
                </p>

                <p>
                    With the advent of modules, a given module has its own
                    configuration file.
                    This means each team (each module would presumably be
                    developed by a
                    single team) has their own configuration file, and there
                    should be a lot
                    less contention when trying to modify it.
                </p>

            </subsection>

            <a name="module_config-inform_controller"/>
            <subsection name="5.3.2 Informing the Controller">

                <p>
                    Since version 1.0, you listed your configuration file as an
                    initialization
                    parameter to the action servlet in
                    <code>web.xml.</code>
                    This is still done since version 1.1, but the parameter can
                    be extended.
                    In order to tell the framework machinery about your
                    different modules, you
                    specify multiple 'config' initialization parameters, with
                    a slight twist.
                    You'll still use 'config' to tell the ActionServlet about
                    your "default"
                    module, however, for each additional module, you will
                    list an initialization parameter named "config
                    <em>/module</em>
                    ", where
                    <em>/module</em>
                    is
                    the prefix for your module (this gets used when
                    determining which URIs fall
                    under a given module, so choose something meaningful!).
                    For example:
                </p>
                               
                <source><![CDATA[
    ...
    <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/conf/struts-default.xml</param-value>
    </init-param>
    <init-param>
        <param-name>config/module1</param-name>
        <param-value>/WEB-INF/conf/struts-module1.xml</param-value>
    </init-param>
    ...
]]></source>

                <p>
                    Here we have two modules.
                    One happens to be the "default" module, identified by the
                    param-name of
                    "config", and the other will be using the module prefix
                    "/module1" based
                    on the param-name it was given ("config/module1").
                    The controller is configured to find the respective
                    configuration files
                    under
                    <code>/WEB-INF/conf/</code>
                    (which is the recommended place to put all configuration
                    files).
                    Pretty simple!
                </p>

                <p>
                    (The
                    <code>struts-default.xml</code>
                    would be equivalent to what most folks call
                    <code>struts-config.xml.</code>
                    I just like the symmetry of having all my module
                    configuration files being
                    named
                    <code>struts-
                        <em>module.xml</em>
                    </code>
                    )
                </p>

                <p>
                    If you'd like to vary where the pages for each module are
                    stored,
                    see the
                    <a href="#controller_config">
                        forwardPattern</a>
                    setting for the
                    Controller.
                </p>

            </subsection>


            <a name="module_config-switching"/>
            <subsection name="5.3.3 Switching Modules">

                <p>
                    There are three approaches for switching from one module
                    to another.
                </p>
                
                <ol>
                    <li>
                    You can use the
                    <code>org.apache.struts.actions.SwitchAction</code>
                    from the Extras JAR,
                  </li>
                  <li>
                    you can use a
                    <code>&lt;forward&gt;</code>
                    (global or local) and specify the contextRelative
                    attribute with a value of true,
                  </li>
                  <li>
                    or you can specify the "module" parameter as part of any
                    of the Struts JSP hyperlink tags (Include, Img, Link,
                    Rewrite, or Forward).
                  </li>
                </ol>

                <p>
                    You can use
                    <code>org.apache.struts.actions.SwitchAction</code>
                    like so:
                </p>

                <source><![CDATA[
    ...
    <action-mappings>
    <action path="/toModule"
    type="org.apache.struts.actions.SwitchAction"/>
    ...
    </action-mappings>
    ...
]]></source>

                <p>
                    Now, to change to ModuleB, we would use a URI like this:
                </p>

                <source>
                    http://localhost:8080/toModule.do?prefix=/moduleB&amp;page=/index.do
                </source>

                <p>
                    If you are using the "default" module as well as "named"
                    modules (like "/moduleB"),
                    you can switch back to the "default" module with a URI
                    like this:
                </p>

                <source>
                    http://localhost:8080/toModule.do?prefix=&amp;page=/index.do
                </source>

                <p>
                    Here's an example of a global forward:
                </p>

                <source><![CDATA[
<global-forwards>
    <forward       name="toModuleB"
        contextRelative="true"
                   path="/moduleB/index.do"
               redirect="true"/>
   ...
</global-forwards>
]]></source>

                <p>
                    You could do the same thing with a local forward declared
                    in an
                    ActionMapping:
                </p>

                <source><![CDATA[
   <action-mappings>
   <action ... >
       <forward       name="success"
           contextRelative="true"
                      path="/moduleB/index.do"
                  redirect="true"/>
   </action>
   ...
   </action-mappings>
   ]]></source>

                <p>
                    Using the module parameter with a hyperlink tag is even
                    simpler:
                </p>

                <source><![CDATA[
    <html:link module="/moduleB" path="/index.do"/>
    ]]></source>

                <p>
                    That's all there is to it! Happy module-switching!
                </p>

            </subsection>

            <a name="dd_config"/>
            <subsection name="5.4 The Web Application Deployment Descriptor">

                <p>
                    The final step in setting up the application is to
                    configure the
                    application deployment descriptor (stored in file
                    <code>WEB-INF/web.xml</code>
                    ) to include all the framework or Taglib components that
                    are required.
                    Using the deployment descriptor for the example
                    application as a guide,
                    we see that the following entries need to be created or
                    modified.
                </p>

            </subsection>

            <a name="dd_config_servlet"/>
            <subsection name="5.4.1 Configure the ActionServlet Instance">

                <p>
                    Add an entry defining the action servlet itself, along
                    with the
                    appropriate initialization parameters.
                    Such an entry might look like this:
                </p>

                <source><![CDATA[
<servlet>
    <servlet-name>action</servlet-name>
    <servlet-class>
        org.apache.struts.action.ActionServlet
    </servlet-class>
    <init-param>
        <param-name>config</param-name>
        <param-value>
         /WEB-INF/struts-config.xml
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
]]></source>

                <p>
                    The initialization parameters supported by the action
                    servlet are
                    described below.
                    (You can also find these details in the
                    <a href="../apidocs/org/apache/struts/action/ActionServlet.html">
                        Javadocs</a>
                    for the ActionServlet class.)
                    Square brackets describe the default values that are
                    assumed if you do
                    not provide a value for that initialization parameter.
                </p>

                <ul>

                    <li>
                        <strong>chainConfig</strong>
                        - Comma-separated list of either
                        context-relative or classloader path(s) to load
                        commons-chain catalog
                        definitions from. If none specified, the default
                        catalog that is
                        provided with the framework will be used. (Since
                        version 1.3)
                    </li>

                    <li>
                        <strong>config</strong>
                        - Context-relative path to the XML resource
                        containing the configuration information for the
                        default module.
                        This may also be a comma-delimited list of
                        configuration files.
                        Each file is loaded in turn, and its objects are
                        appended to the
                        internal data structure. [/WEB-INF/struts-config.xml].
                        <br/>
                        <strong>WARNING</strong>
                        - If you define
                        an object of the same name in more than one
                        configuration file,
                        the last one loaded quietly wins.
                        <br/>
                        <strong>WARNING</strong>
                        - Plugins are not designed 
                        to be loaded more than once in the same module.
                        The set of configuration files for a module 
                        should load a plugin only once.
                    </li>

                    <li>
                        <strong>config/${module}</strong>
                        - Context-relative path to the XML
                        resource containing the configuration information for
                        the application
                        module that will use the specified prefix
                        (/${module}).
                        This can be repeated as many times as required for
                        multiple
                        application modules. (Since version 1.1)
                    </li>

                    <li>
                        <strong>configFactory</strong>
                        - The Java class name of the
                        ModuleConfigFactory used to create the implementation
                        of the
                        ModuleConfig interface. (Since version 1.3)
                        [org.apache.struts.config.impl.DefaultModuleConfigFactory]
                    </li>

                    <li>
                        <strong>convertNull</strong>
                        - Force simulation of the version 1.0
                        behavior when populating forms.
                        If set to "true", the numeric Java wrapper class types
                        (like
                        <code>java.lang.Integer</code>
                        ) will default to null (rather than 0).
                        (Since version 1.1) [false]
                    </li>

                    <li>
                        <strong>rulesets</strong>
                        - Comma-delimited list of fully qualified
                        classnames of additional
                        <code>org.apache.commons.digester.RuleSet</code>
                        instances that
                        should be added to the
                        <code>Digester</code>
                        that will be processing
                        <code>struts-config.xml</code>
                        files.
                        By default, only the
                        <code>RuleSet</code>
                        for the standard
                        configuration elements is loaded. (Since version 1.1)
                    </li>

                    <li>
                        <strong>validating</strong>
                        - Should we use a validating XML parser to
                        process the configuration file (strongly recommended)?
                        [true]
                    </li>

                </ul>

                <p>
                    <strong>WARNING</strong>
                    - The framework will not
                    operate correctly if you define more than one
                    <code>&lt;servlet&gt;</code>
                    element for a controller
                    servlet, or a subclass of the standard controller servlet
                    class.
                    The controller servlet
                    <strong>MUST</strong>
                    be a web application
                    wide singleton.
                </p>

            </subsection>

            <a name="dd_config_mapping"/>
            <subsection name="5.4.2 Configure the ActionServlet Mapping">

                <p>
                    <strong>Note:</strong>
                    The material in this section is not specific to
                    Struts.
                    The configuration of servlet mappings is defined in the
                    Java Servlet
                    Specification.
                    This section describes the most common means of
                    configuring a
                    application.
                </p>

                <p>
                    There are two common approaches to defining the URLs that
                    will
                    be processed by the controller servlet -- prefix matching
                    and extension
                    matching.
                    An appropriate mapping entry for each approach will be
                    described below.
                </p>

                <p>
                    Prefix matching means that you want all URLs that start
                    (after the context
                    path part) with a particular value to be passed to this
                    servlet.
                    Such an entry might look like this:
                </p>

                <source><![CDATA[
<servlet-mapping>
    <servlet-name>action</servlet-name>
    <url-pattern>/do/*</url-pattern>
</servlet-mapping>
]]></source>

                <p>
                    which means that a request URI to match the
                    <code>/logon</code>
                    path
                    described earlier might look like this:
                </p>

                <source>
                    http://www.mycompany.com/myapplication/do/logon</source>

                <p>
                    where
                    <code>/myapplication</code>
                    is the context path under which your
                    application is deployed.
                </p>

                <p>
                    Extension mapping, on the other hand, matches request URIs
                    to the
                    action servlet based on the fact that the URI ends with a
                    period
                    followed by a defined set of characters.
                    For example, the JSP processing servlet is mapped
                    to the
                    <code>*.jsp</code>
                    pattern so that it is called to process
                    every JSP page that is requested.
                    To use the
                    <code>*.do</code>
                    extension (which implies "do something"),
                    the mapping entry would look like this:
                </p>

                <source><![CDATA[
<servlet-mapping>
    <servlet-name>action</servlet-name>
    <url-pattern>*.do</url-pattern>
</servlet-mapping>
]]></source>

                <p>
                    and a request URI to match the
                    <code>/logon</code>
                    path described
                    earlier might look like this:
                </p>

                <source>
                    http://www.mycompany.com/myapplication/logon.do</source>

                <p>
                    <strong>WARNING</strong>
                    - The framework will not
                    operate correctly if you define more than one
                    <code>&lt;servlet-mapping&gt;</code>
                    element for the controller
                    servlet.
                </p>

                <p>
                    <strong>WARNING</strong>
                    - If you are using
                    the new module support since version 1.1, you should be
                    aware
                    that
                    <strong>only</strong>
                    extension mapping is supported.
                </p>

            </subsection>

            <a name="dd_config_taglib_uri"/>
            <subsection
                    name="5.4.3.1 Configure the Struts JSP Tag Libraries (Servlet 2.3/2.4)">

                <p>
                    The Servlet 2.3 and 2.4 specifications simplify the
                    deployment and configuration of tag libraries.
                    All that's now required to install the Struts tag
                    libraries is to copy
                    <code>struts-taglib.jar</code>
                    into your
                    <code>/WEB-INF/lib</code>
                    directory and reference the tags in
                    your code like this:
                </p>

                <source>
                    &lt;%@ taglib
                    uri="http://struts.apache.org/tags-html"
                    prefix="html" %&gt;
                </source>

                <p>
                    Note that you
                    <strong>must use the full uri</strong>
                    defined in the various
                    tlds (see the
                    <a href="5_4_3_Configure_the_Struts_Tag_Libraries">
                        example configuration</a>
                    for reference)
                    so that the container knows where to find the tag's class
                    files.
                    You don't have to alter your
                    <code>web.xml</code>
                    file or copy tlds into any
                    application directories.
                </p>

                <p>
                    Of course, the configuration techniques use for older
                    containers do still work.
                </p>

            </subsection>

            <a name="config_add"/>
            <subsection name="5.5 Add Framework Components To Your Application">

                <p>
                    To use the framework, you must copy
                    <code>struts-core-*.jar</code>
                    (and all of the
                    <code>commons-*.jar</code>
                    files) into your
                    <code>WEB-INF/lib</code>
                    directory. To use Struts Taglib,
                    you must also copy the 
                    <code>struts-taglib-*.jar.</code>
                    Likewise, to use other optional components, like
                    Extras, Tiles, or the Validator, copy the corresponding 
                    <code>struts-*.jar.</code>
                </p>

                <div class="notice">
                    <h4 class="center">
                        Sidebar: Sharing JAR Files Across Web Applications
                    </h4>

                    <p>
                        Many servlet containers and application servers
                        provide facilities
                        for sharing JAR files across multiple web applications
                        that depend
                        on them. For example, Tomcat 4.1 allows you to put JAR
                        files into
                        the
                        <code>$CATALINA_HOME/shared/lib</code>
                        or
                        <code>$CATALINA_HOME/common/lib</code>
                        directories, and the classes
                        in those JAR files will be available in all
                        applications, without
                        the need to place them in every web application's
                        <code>/WEB-INF/lib</code>
                        directory. Usually, the sharing is
                        accomplished by creating a separate class loader that
                        is the parent
                        of the class loader (created by your container) for
                        each individual
                        web application.
                    </p>

                    <p>
                        If you have multiple web applications based on the framework, 
                        it is tempting
                        to consider taking advantage of this container
                        feature, and placing
                        <code>struts.jar</code>
                        and the various
                        <code>commons-*.jar</code>
                        files in the shared directory, rather than in each web
                        application.
                        However, there are several potential, and actual,
                        problems with this approach:
                    </p>

                    <ul>
                        <li>
                            Classes loaded from the shared class loader cannot
                            see classes
                            in the web application's class loader, unless they
                            are specifically
                            programmed to use the Thread context class loader.

                            For example, the framework dynamically loads your
                            action and form bean
                            classes, and normally would not be able to find
                            those classes.
                            The framework has been programmed to deal with
                            this in
                            <em>most</em>
                            scenarios, but it has not been thoroughly audited
                            to ensure that
                            it works in
                            <em>all</em>
                            scenarios. The Commons libraries that
                            the framework uses have
                            <strong>NOT</strong>
                            been audited to catch all
                            possible scenarios where this might become a
                            problem.

                        </li>
                        <li>
                            When a class is loaded from a shared class loader,
                            static variables
                            used within that class become global as well. This
                            can cause
                            inter-webapp conflicts when the underlying code
                            assumes that the
                            statics are global only within a particular web
                            applicaiton (which
                            would be true if the class was loaded from the
                            webapp class loader).

                            There are many cases where the framework, and the
                            Commons libraries it
                            relies on, use static variables to maintain
                            information that is
                            presumed to be visible only within a single web
                            application.
                            Sharing these JAR files can cause unwanted
                            interactions, and
                            probably cause incorrect behavior.

                        </li>
                        <li>
                            When JAR files are shared like this, it is not
                            possible to update
                            the JAR file versions employed by a single web
                            application without
                            updating all of them. In addition, because
                            updating a Struts version
                            normally requires recompilation of the
                            applications that use it,
                            you will have to recompile all of your
                            applications as well, instead
                            of being able to manage them independently.
                        </li>
                    </ul>

                    <p>
                        In spite of these difficulties, it is possible that
                        sharing the
                        Struts and Commons JAR files
                        <em>might</em>
                        appear to work for you.
                        However, this is
                        <strong>NOT</strong>
                        a supported configuration.
                    </p>

                    <p>
                        If you file a bug report for
                        <code>ClassNotFoundException</code>
                        or
                        <code>NoClassDefFoundError</code>
                        exceptions, or similar situations
                        where it appears that the wrong version of a class is
                        being loaded,
                        the bug report will
                        <strong>NOT</strong>
                        be processed unless the
                        problem exists with the JAR files in their recommended
                        location,
                        in the
                        <code>/WEB-INF/lib</code>
                        subdirectory of your webapp.
                    </p>
                </div>

            </subsection>
            <a name="config_logging"/>
            <subsection name="5.6 Logging">

                <p>
                    Since version 1.0, the logging functionality was fairly
                    limited. You could
                    set a debugging detail level with a servlet initialization
                    parameter, and
                    all log messages were written to wherever
                    <code>ServletContext.log()</code>
                    output is sent by your servlet container. With Struts 1.1,
                    however, all
                    logging messages written by the framework, as well as the
                    commons libraries
                    that it utilizes, flow through an abstract wrapper called
                    <a href="http://commons.apache.org/logging">
                        Commons Logging,</a>
                    which can be used as a wrapper around any logging
                    implementation. The most
                    common implementations used are simple logging to
                    <code>System.err,</code>
                    the
                    <a href="http://jakarta.apache.org/log4j/">Apache
                        Log4J</a>
                    package,
                    or the built-in logging capabilities of JDK 1.4 or later
                    in the
                    <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
                        java.util.logging</a>
                    package.
                </p>

                <p>
                    This section does not attempt to fully explain how Commons
                    Logging is
                    configured and used. Instead, it focuses on pertinent
                    details of using
                    Commons Logging in connection with the Struts
                    Framework. For complete documentation
                    on using Commons Logging, consult the documentation for
                    the logging system
                    you are using, plus the Commons Logging
                    <a href="http://commons.apache.org/logging/commons-logging-1.0.3/docs/api/">
                        Javadocs.</a>
                </p>

                <p>
                    Commons Logging provides fine-grained control over the
                    logging messages
                    created by a
                    <code>Log</code>
                    instance. By convention, the
                    <code>Log</code>
                    instances for the framework (and the Commons packages in
                    general) are named the
                    fully qualified class name of the class whose messages are
                    being logged.
                    Therefore, log messages created by the
                    <code>RequestProcessor</code>
                    class are, naturally
                    enough, directed to a logger named
                    <code>org.apache.struts.action.RequestProcessor.</code>
                </p>

                <p>
                    The advantage of this approach is that you can configure
                    the level of detail
                    in the output you want from each class, individually.
                    However, it would be
                    a burden to be required to maintain such settings for
                    every possible class,
                    so the logging environment supports the notion of logging
                    <em>hierarchies</em>
                    as well. If a detail level configuration for a
                    particular class has not been set, the logging system
                    looks up the hierarchy
                    until it finds a configuration setting to use, or else
                    uses the default
                    detail level if no configuration for any level of the
                    hierarchy has been
                    explicitly set. In the case of our messages from
                    <code>RequestProcessor,</code>
                    the logging system will look for explicit settings of the
                    following loggers,
                    in this order, until it finds one:
                </p>

                <ul>
                    <li>
                        <code>org.apache.struts.action.RequestProcessor</code>
                    </li>
                    <li>
                        <code>org.apache.struts.action</code>
                    </li>
                    <li>
                        <code>org.apache.struts</code>
                    </li>
                    <li>
                        <code>org.apache</code>
                    </li>
                    <li>
                        <code>org</code>
                    </li>
                    <li>The default logging detail level for your log
                        implementation.</li>
                </ul>

                <p>
                    In a similar manner, the detail level for messages from
                    <code>PropertyUtils</code>
                    (from the Commons BeanUtils library) is set by
                    a search for configuration settings for:
                </p>

                <ul>
                    <li>
                        <code>
                            org.apache.commons.beanutils.PropertyUtils</code>
                    </li>
                    <li>
                        <code>org.apache.commons.beanutils</code>
                    </li>
                    <li>
                        <code>org.apache.commons</code>
                    </li>
                    <li>
                        <code>org.apache</code>
                    </li>
                    <li>
                        <code>org</code>
                    </li>
                    <li>The default logging detail level for your log
                        implementation.</li>
                </ul>

                <p>
                    You can seamlessly integrate logging from your own
                    components into the same
                    logging implementation that the framework and the Commons
                    libraries use, by
                    following the instructions in
                    <a href="building_controller.html#4_11_Commons_Logging_Interface">
                        Section 4.11</a>
                    . If you do
                    this, you are strongly encouraged to follow the same
                    naming convention for
                    loggers (based on the class name of the messages being
                    logged) for
                    maximum configuration flexibility.
                </p>

            </subsection>


            <subsection>

                <p>
                    For more about putting it all together, see the
                    <a href="../faqs/apps.html">
                        Building Applications HowTo.</a>
                </p>

                <p class="right">
                    Next:
                    <a href="./release-notes.html">Release Notes</a>
                </p>

            </subsection>

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