configuration.html

struts api,学习使用struts必备的文档

</div>
<h2 id="data-source_config">5.2.4 Data Source Configuration</h2>
<div class="indent">

    <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&gt;</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>&lt;data-source&gt;</code> element does not pre-define a slate of
    properties.
    Instead, the generic <code>&lt;set-property&gt;</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>
&lt;data-source type="org.apache.commons.dbcp.BasicDataSource"&gt;
&lt;!-- ... set-property elements ... --&gt;
&lt;/data-source&gt;
</code>
</pre>

    <p>
    Since Struts 1.2.0, the GenericDataSource has been removed, and it is
    recommended that you use the Commons BasicDataSource or other DataSource
    implementations 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 <code>&lt;data-sources&gt;</code> element and using the
    DataSource with an Action, see the
    <a href="../faqs/database.html">Accessing a Database HowTo</a>.
    </p>

</div>
<h2 id="dd_config_modules">5.3 Configuring your application for modules</h2>
<div class="indent">

    <p>
    Very little is required in order to start taking advantage of the Struts
    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>

</div>
<h2 id="module_config-files">5.3.1 Module Configuration Files</h2>
<div class="indent">

    <p>
    Back in Struts 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 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>

</div>
<h2 id="module_config-inform_controller">5.3.2 Informing the Controller</h2>
<div class="indent">

    <p>
    Since Struts 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 Struts 1.1, but the parameter can be extended.
    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 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>

<pre>
<code>
    ...
    &lt;init-param&gt;
        &lt;param-name&gt;config&lt;/param-name&gt;
        &lt;param-value&gt;/WEB-INF/conf/struts-default.xml&lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;init-param&gt;
        &lt;param-name&gt;config/module1&lt;/param-name&gt;
        &lt;param-value&gt;/WEB-INF/conf/struts-module1.xml&lt;/param-value&gt;
    &lt;/init-param&gt;
    ...
</code>
</pre>

    <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 Struts module configuration files being
    named <code>struts-<em>module</em>.xml</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>

</div>
<h2 id="module_config-switching">5.3.3 Switching Modules</h2>
<div class="indent">

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

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

<pre>
<code>
    ...
    &lt;action-mappings&gt;
    &lt;action path="/toModule"
    type="org.apache.struts.actions.SwitchAction"/&gt;
    ...
    &lt;/action-mappings&gt;
    ...
</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>
    Here's an example of a global forward:
    </p>

<pre>
<code>
&lt;global-forwards&gt;
    &lt;forward       name="toModuleB"
        contextRelative="true"
                   path="/moduleB/index.do"
               redirect="true"/&gt;
   ...
&lt;/global-forwards&gt;
</code>
</pre>

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

<pre>
<code>
   &lt;action-mappings&gt;
   &lt;action ... &gt;
       &lt;forward       name="success"
           contextRelative="true"
                      path="/moduleB/index.do"
                  redirect="true"/&gt;
   &lt;/action&gt;
   ...
   &lt;/action-mappings&gt;
   </code>
</pre>

   <p>
    Or, you can use
    <code>org.apache.struts.actions.SwitchAction</code>:
   </p>

   <pre>
<code>
   &lt;action-mappings&gt;
   &lt;action path="/toModule"
           type="org.apache.struts.actions.SwitchAction"/&gt;
   ...
   &lt;/action-mappings&gt;
   </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>
    Using the module parameter with a hyperlink tag is even simpler:
    </p>

    <pre>
<code>
    &lt;html:link module="/moduleB" path="/index.do"/&gt;
    </code>
</pre>

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

</div>
<h2 id="dd_config">5.4 The Web Application Deployment Descriptor</h2>
<div class="indent">

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

</div>
<h2 id="dd_config_servlet">5.4.1 Configure the ActionServlet Instance</h2>
<div class="indent">

    <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>
&lt;servlet&gt;
    &lt;servlet-name&gt;action&lt;/servlet-name&gt;
    &lt;servlet-class&gt;
        org.apache.struts.action.ActionServlet
    &lt;/servlet-class&gt;
    &lt;init-param&gt;
        &lt;param-name&gt;config&lt;/param-name&gt;
        &lt;param-value&gt;
         /WEB-INF/struts-config.xml
        &lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
&lt;/servlet&gt;
</code>
</pre>

    <p>
    The initialization parameters supported by the action 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>

        <li>
        <strong>configFactory</strong> - The Java class name of the 
        <code>ModuleConfigFactory</code> used to create the implementation of the 
        <code>ModuleConfig</code> interface. 
         [org.apache.struts.config.impl.DefaultModuleConfigFactory]
        </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>

</div>
<h2 id="dd_config_mapping">5.4.2 Configure the ActionServlet Mapping</h2>
<div class="indent">

    <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