File: configuration.xml

package info (click to toggle)
libstruts1.2-java 1.2.9-4
links: PTS
area: main
in suites: squeeze
size: 47,756 kB
ctags: 29,808
sloc: xml: 90,345; java: 71,107; jsp: 31,692; makefile: 9; sh: 2
file content (1315 lines) | stat: -rw-r--r-- 45,240 bytes
parent folder | download | duplicates (5)
<?xml version="1.0"?>
<document url="configuration.html">

<properties>
    <title>The Struts User's Guide - Configuring Applications</title>
    <author>Craig R. McClanahan</author>
    <author>Mike Schachter</author>
    <author>Ted Husted</author>
    <author>Martin Cooper</author>
    <author>Ed Burns</author>
    <author>Donald Ball</author>
    <author>Eddie Bush</author>
    <author>Yann Cebron</author>
    <author>David Graham</author>
    <author>Tim O'Brien</author>
</properties>

<body>
<section name="5. Configuring Applications" href="config_apps"/>

<section name="5.1 Overview" href="config-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 Struts application.
    These include components in the Struts configuration file
    and in the Web Application Deployment Descriptor.
    </p>

 </section>

 <section name="5.2 The Struts configuration file"  href="struts-config">

    <p>
    The <a href="building_controller.html#config">Building Controller
    Components</a> chapter covered writing the form-bean and action-mapping
    portions of the Struts configuration file.
    These elements usually play an important role in the development of a
    Struts application.
    The other elements in Struts configuration file tend to be static:
    you set them once and leave them alone.
    </p>

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

    <ul>

        <li>
            controller
        </li>

        <li>
            message-resources
        </li>

        <li>
            plug-in
        </li>

        <li>
            data-sources
        </li>

    </ul>

 </section>

 <section name="5.2.1 Controller Configuration" href="controller_config">

    <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="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd">
    struts-config_1_1.dtd</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>className</strong> - Classname of configuration bean.
        [org.apache.struts.config.ControllerConfig] (optional)
        </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 (and when the
        <code>contextRelative</code> property is <code>false</code>).
        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] (optional)
        </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.action.RequestProcessor] (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>

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

</section>

<section name="5.2.2 Message Resources Configuration" href="resources_config">

    <p>
    Struts 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>parameter</strong> - Name of the resource bundle. (required)
        </li>

    </ul>

    

    <p>Example configuration:</p>

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

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

</section>

<section name="5.2.3 PlugIn Configuration" href="plugin_config">

    <p>
    Struts PlugIns are configured using the <code>&lt;plug-in&gt;</code>
    element within the Struts 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>

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

</section>

<section name="5.2.4 Data Source Configuration" href="data-source_config">

    <p>
    Besides the objects related to defining ActionMappings, the Struts
    configuration may contain elements that create other useful objects.
    </p>

    <p>
    The <code>&lt;data-sources></code> section can be used to specify
    a collection of DataSources [javax.sql.DataSource] for the use of your
    application.
    Typically, a DataSource represents a connection pool to a database
    or other persistent store.
    As a convenience, the Struts DataSource manager can be used to
    instantiate whatever standard pool your application may need.
    Of course, if your persistence layer provides for its own connections,
    then you do not need to specify a <code>data-sources</code> element.
    </p>

    <p>
    Since DataSource implementations vary in what properties need to be
    set, unlike other Struts configuration elements, the
    <code>data-source</code> element does not pre-define a slate of
    properties.
    Instead, the generic <code>set-property</code> feature is used to set
    whatever properties your implementation may require.
    Typically, these settings would include:
    </p>

    <ul>

    <li>
    A driver class name
    </li>

    <li>
    A url to access the driver
    </li>

    <li>
    A description
    </li>

    </ul>

    <p>
    And other sundry properties.
    </p>

<pre><code><![CDATA[
<data-source type="org.apache.commons.dbcp.BasicDataSource">
<!-- ... set-property elements ... -->
</data-source>
]]></code></pre>

    <p>
    In Struts 1.2.0, the GenericDataSource has been removed, and it is
    recommended that you use the Commons BasicDataSource or other DataSource
    implementation instead. In practice, if you need to use the DataSource 
    manager, you should use whatever DataSource implementation works best 
    with your container or database.
    </p>

    <p>
    For examples of specifying a data-sources element and using the
    DataSource with an Action, see the
    <a href="../faqs/database.html">Accessing a Database HowTo</a>.
    </p>

</section>

<section
    name="5.3 Configuring your application for modules"
    href="dd_config_modules">

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

    <ol>

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

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

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

    </ol>

</section>

<section name="5.3.1 Module Configuration Files" href="module_config-files">

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

    <p>
    In Struts 1.1, you have two options: you can list
    <a href="#dd_config_servlet">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>

</section>

<section
    name="5.3.2 Informing the Controller"
    href="module_config-inform_controller">

    <p>
    In struts 1.0, you listed your configuration file as an initialization
    parameter to the action servlet in web.xml.
    This is still done in 1.1, but it's augmented a little.
    In order to tell the Struts machinery about your different modules, you
    specify multiple config initialization parameters, with a slight twist.
    You'll still use "config" to tell the action servlet about your "default"
    module, however, for each additional module, you will
    list an initialization parameter named "config/module", where module is
    the name of your module (this gets used when determining which URIs fall
    under a given module, so choose something meaningful!).
    For example:
    </p>

<pre><code><![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>
    ...
]]></code></pre>

    <p>
    This says I have two modules.
    One happens to be the "default" module, which has no "/module" in it's
    name, and one named "module1" (config/module1).
    I've told the controller it can find their respective configurations
    under /WEB-INF/conf (which is where I put all my configuration files).
    Pretty simple!
    </p>

    <p>
    (My struts-default.xml would be equivalent to what most folks call
    struts-config.xml.
    I just like the symmetry of having all my Struts module files being
    named struts-&lt;module&gt;.xml)
    </p>

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

</section>


<section name="5.3.3 Switching Modules" href="module_config-switching">

    <p>
    There are two basic methods to switching from one module to another.
    You can either use a forward (global or local) and specify the
    contextRelative attribute with a value of true, or you can use
    the built-in <code>org.apache.struts.actions.SwitchAction</code>.
    </p>

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

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

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

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

    <p>
     Finally, you could use
     <code>org.apache.struts.actions.SwitchAction</code>,
     like so:
    </p>

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

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

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

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

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

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

</section>

<section name="5.4 The Web Application Deployment Descriptor" href="dd_config">

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

</section>

<section
    name="5.4.1 Configure the Action Servlet Instance"
    href="dd_config_servlet">

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

<pre><code><![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>
]]></code></pre>

    <p>
    The initialization parameters supported by the controller servlet are
    described below.
    (You can also find these details in the
    <a href="../api/index.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>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.

        </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 Struts 1.1)
        </li>

        <li>
        <strong>convertNull</strong> - Force simulation of the Struts 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 Struts 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 Struts 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>
     The following parameters may still be used with the Struts 1.1 release
     but are <strong>deprecated</strong>.
     </p>

     <ul>

        <li>
        <strong>application</strong> - Java class name of the application
        resources bundle base class.
        [NONE]
        <em>DEPRECATED - Configure this using the "parameter" attribute
        of the &lt;message-resources&gt; element.</em>
        </li>

        <li><strong>bufferSize</strong> - The size of the input buffer used
        when processing file uploads.
        [4096]
        <em>DEPRECATED - Configure this using the "bufferSize" attribute
        of the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>content</strong> - Default content type and character encoding
        to be set on each response; may be overridden by a forwarded-to
        servlet or JSP page.
        [text/html]
        <em>DEPRECATED - Configure this using the "contentType" attribute
        of the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>debug</strong> - The debugging detail level that controls
        how much information is logged for this servlet.
        Accepts values 0 (off) and from 1 (least serious) through 6
        (most serious). [0]
        <em>DEPRECATED - Configure the logging detail level in your
        underlying logging implementation.</em>
        </li>

        <li>
        <strong>factory</strong> - The Java class name of the
        <code>MessageResourcesFactory</code> used to create the application
        <code>MessageResources</code> object.
        [org.apache.struts.util.PropertyMessageResourcesFactory]
        <em>DEPRECATED - Configure this using the "factory" attribute
        of the &lt;message-resources&gt; element.</em>
        </li>

        <li>
        <strong>formBean</strong> - The Java class name of the ActionFormBean
        implementation to use
        [org.apache.struts.action.ActionFormBean].
        <em>DEPRECATED - Configure this using the "className" attribute
        of each &lt;form-bean&gt; element.</em>
        </li>

        <li>
        <strong>forward</strong> - The Java class name of the ActionForward
        implementation to use
        [org.apache.struts.action.ActionForward].
        Two convenient classes you may wish to use are:
        <ul>

            <li>
            <em>org.apache.struts.action.ForwardingActionForward</em> -
            Subclass of <code>org.apache.struts.action.ActionForward</code>
            that defaults the <code>redirect</code> property to
            <code>false</code> (same as the ActionForward default value).
            </li>

            <li>
            <em>org.apache.struts.action.RedirectingActionForward</em> -
            Subclass of <code>org.apache.struts.action.ActionForward</code>
            that defaults the <code>redirect</code> property to
            <code>true</code>.
            </li>

        </ul>
        <em>DEPRECATED - Configure this using the "className" attribute of
        each &lt;forward&gt; element.</em>
        </li>

        <li>
        <strong>locale</strong> - If set to <code>true</code>, and there is a
        user session, identify and store an appropriate
        <code>java.util.Locale</code> object (under the standard key
        identified by <code>Globals.LOCALE_KEY</code>) in the user's session
        if there is not a Locale object there already.
        [true]
        <em>DEPRECATED - Configure this using the "locale" attribute of
        the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>mapping</strong> - The Java class name of the ActionMapping
        implementation to use
        [org.apache.struts.action.ActionMapping].
        Two convenient classes you may wish to use are:

        <ul>

            <li>
            <em>org.apache.struts.action.RequestActionMapping</em> - Subclass
            of <code>org.apache.struts.action.ActionMapping</code> that
            defaults the <code>scope</code> property to "request".
            </li>

            <li>
            <em>org.apache.struts.action.SessionActionMapping</em> - Subclass
            of <code>org.apache.struts.action.ActionMapping</code> that
            defaults the <code>scope</code> property to "session".
            (Same as the ActionMapping default value).
            </li>

        </ul>

        <em>DEPRECATED - Configure this using the "className" attribute of
        each &lt;action&gt; element, or globally for a module by using the
        "type" attribute of the &lt;action-mappings&gt; element.</em>
        </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]
        <em>DEPRECATED - Configure this using the "maxFileSize" attribute of
        the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>multipartClass</strong> - The fully qualified name of the
        MultipartRequestHandler implementation class to be used for processing
        file uploads.
        If set to <code>none</code>, disables Struts multipart request
        handling.
        [org.apache.struts.upload.CommonsMultipartRequestHandler]
        <em>DEPRECATED - Configure this using the "multipartClass" attribute
        of the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>nocache</strong> - If set to <code>true</code>, add HTTP
        headers to every response intended to defeat browser caching of
        any response we generate or forward to.
        [false]
        <em>DEPRECATED - Configure this using the "nocache" attribute of
        the &lt;controller&gt; element.</em>
        </li>

        <li>
        <strong>null</strong> - If set to <code>true</code>, set our
        application resources to return <code>null</code> if an unknown
        message key is used.
        Otherwise, an error message including the offending message key will
        be returned.
        [true]
        <em>DEPRECATED - Configure this using the "null" attribute of
        the &lt;message-resources&gt; element.</em>
        </li>

        <li>
        <strong>tempDir</strong> - The temporary working directory to use when
        processing file uploads.
        [The working directory provided to this web application as a servlet
        context attribute]
        <em>DEPRECATED - Configure this using the "tempDir" attribute of
        the &lt;controller&gt; element.</em>
        </li>

     </ul>

     <p>
       <strong>WARNING</strong> - Struts 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>

</section>

<section
    name="5.4.2 Configure the Action Servlet Mapping"
    href="dd_config_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 Struts
    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>

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

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

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

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

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

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

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

        <p>
        <strong>WARNING</strong> - Struts 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 in Struts 1.1, you should be aware
        that <strong>only</strong> extension mapping is supported.
        </p>

</section>

<section
    name="5.4.3 Configure the Struts Tag Libraries"
    href="dd_config_taglib">

        <p>
        Next, you must add an entry defining the Struts tag library.
        </p>

        <p>
        The struts-bean taglib contains tags useful in accessing beans and their
        properties,  as well as defining new beans (based on these accesses)
        that are accessible to the remainder of the page via scripting
        variables and page scope attributes.
        Convenient mechanisms to create new beans based on the value of request
        cookies, headers, and parameters are also provided.
        </p>

        <p>
        The struts-html taglib contains tags used to create struts input forms,
        as well as other tags generally useful in the creation of HTML-based
        user interfaces.
        </p>

        <p>
        The struts-logic taglib contains tags that are useful in managing
        conditional generation of output text,
        looping over object collections for repetitive generation of output
        text,  and application flow management.
        </p>

        <p>
        The struts-tiles taglib contains tags used for combining various view
        components, called "tiles", into a final composite view.
        </p>

        <p>
        The struts-nested taglib is an extension of other struts taglibs that
        allows the use of nested beans.
        </p>

        <p>
        Below is how you would define all taglibs for use within your
        application.
        In practice, you would only specify the taglibs that your application
        uses:
        </p>

<pre><code><![CDATA[
<taglib>
  <taglib-uri>
    /tags/struts-bean
  </taglib-uri>
  <taglib-location>
    /WEB-INF/struts-bean.tld
  </taglib-location>
</taglib>
<taglib>
  <taglib-uri>
    /tags/struts-html
  </taglib-uri>
  <taglib-location>
    /WEB-INF/struts-html.tld
  </taglib-location>
</taglib>
<taglib>
  <taglib-uri>
    /tags/struts-logic
  </taglib-uri>
  <taglib-location>
    /WEB-INF/struts-logic.tld
  </taglib-location>
</taglib>
<taglib>
  <taglib-uri>
    /tags/struts-tiles
  </taglib-uri>
  <taglib-location>
    /WEB-INF/struts-tiles.tld
  </taglib-location>
</taglib>
]]></code></pre>

    <p>
    This tells the JSP system where to find the tag library descriptor
    for this library (in your application's WEB-INF directory, instead of
    out on the Internet somewhere).
    </p>

</section>

<section
    name="5.4.3.1 Configure the Struts Tag Libraries (Servlet 2.3/2.4)"
    href="dd_config_taglib_23">

    <p>
    <strong>Servlet 2.3/2.4 Users only:</strong> The Servlet 2.3 and 2.4 specifications simplify
    the deployment and configuration of tag libraries.
    The instructions above will work on older containers as well as 2.3 and 2.4
    containers (Struts only requires a servlet 2.2 container);
    however, if you're using a 2.3/2.4 container such as Tomcat 4.x/5.x,
    you can take advantage of a simplified deployment.
    </p>

    <p>
    All that's required to install the struts tag libraries is to copy
    struts.jar into your /WEB-INF/lib directory and reference the tags in
    your code like this:
    </p>

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

    <p>
    Note that you <strong>must use the full uri</strong> defined in the various struts
    tlds so that the container knows where to find the tag's class files.
    You don't have to alter your web.xml file or copy tlds into any
    application directories.
    </p>

</section>

<section
    name="5.5 Add Struts Components To Your Application"
    href="config_add">

    <p>
    To use Struts, you must copy the .tld files that you require into
    your <code>WEB-INF</code> directory, and copy <code>struts.jar</code>
    (and all of the <code>commons-*.jar</code> files) into your
    <code>WEB-INF/lib</code> directory.
    </p>

    <p>
    <strong>Servlet 2.3/2.4 Users:</strong> See
    <a href="#dd_config_taglib_23">section 5.4.3.1</a>
    for how to avoid copying the tlds into your application.
    </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 Struts-based web applications, 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, Struts dynamically loads your action and form bean
            classes, and normally would not be able to find those classes.
            Struts 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
            Struts 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 Struts, and the Commons libraries it
            relies on, use static variables to maintain information that is
            presumed to be visible only within a single web applicaiton.
            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>

</section>

<section
    name="5.6 Logging in Struts Based Applications"
    href="config_logging">

  <p>
  In Struts 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 Struts itself, as well as the commons librarires
  that it utilizes, flow through an abstract wrapper called
  <a href="http://jakarta.apache.org/commons/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 a Struts based environment.  For complete documentation
  on using Commons Logging, consult the documentation for the logging system
  you are using, plus the Commons Logging
  <a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/package-summary.html#package_description">
  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 Struts (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 RequestProcessor 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 Struts and the Commons libraries use, by
  following the instructions in
  <a href="building_controller.html#logging">Section 4.10</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>

</section>


<section>

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

</section>

  
  </body>
</document>