husted 2002/12/01 12:22:41 Modified: doc/userGuide building_controller.xml Log: Move sections 4.6.2 through 4.7.4.2 and 4.8 to a new chapter ("Configuring Applications") to be uploaded later. Add references to new chapter, but no content changes. Revision Changes Path 1.48 +12 -625 jakarta-struts/doc/userGuide/building_controller.xml Index: building_controller.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_controller.xml,v retrieving revision 1.47 retrieving revision 1.48 diff -u -r1.47 -r1.48 --- building_controller.xml 30 Nov 2002 14:30:27 -0000 1.47 +++ building_controller.xml 1 Dec 2002 20:22:41 -0000 1.48 @@ -525,7 +525,7 @@ </section> - <section name="4.6 The Struts Configuration File" href="config"> + <section name="4.6 Writing Action Mappings" href="config"> <p> How does the controller servlet learn about the mappings you want? It @@ -545,8 +545,12 @@ application. This format of this document is described by the Document Type Definition (DTD) maintained at <a href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd">http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd</a>. - The User Guide touches on the most important elements and attributes available to the - Struts configuration file, but developers are referred to the DTD for more detail. + This chapter covers the configuration elements that you will typically + write as part of developing your application. + There are several other elements that can be placed in the + struts-config file to customize your application. + See chapter 7 for more about the other elements in the Struts + configuration file. </p> <p> The controller uses an internal copy of this document to parse the configuration; @@ -713,614 +717,13 @@ classes, all of these classes would also need to be modified. Of course, you can define whatever local forward properties makes sense for your own application. </p> - - </section> - - <section name="4.6.2 Controller Configuration" href="controller_config"> - <p> - The <controller> element allows you to configure the ActionServlet. Many of the controller - parameters were previously defined by servlet init. parameters in your web.xml file but have been - moved to this section of struts-config.xml. For full details on available parameters see the - struts-config_1_1.dtd. - </p> - <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><![CDATA[ - <controller - processorClass="org.apache.struts.action.RequestProcessor" - debug="0" - contentType="text/html"/>; - ]]></pre> - </section> - - <section name="4.6.3 Message Resources Configuration" href="resources_config"> - - <p> - Struts has builtin support for internationalization (I18N). - You can define one or more <code><message-resources></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> - - <blockquote> - <ul> - <li> - <b>className</b> - Classname of configuration bean. - [org.apache.struts.config.MessageResourcesConfig] (optional) - </li> - <li> - <b>factory</b> - Classname of MessageResourcesFactory. - [org.apache.struts.util.PropertyMessageResourcesFactory] (optional) - </li> - <li> - <b>key</b> - ServletContext attribute key to store this bundle. - [org.apache.struts.action.MESSAGE] (optional) - </li> - <li> - <b>null</b> - Set to <code>false</code> to display missing resource keys - in your application like '<i>???keyname???</i>' instead of <code>null</code>. - [true] (optional) - </li> - <li> - <b>parameter</b> - Name of the resource bundle. (required) - </li> - </ul> - </blockquote> - <p>Example configuration:</p> -<pre> -<message-resources -parameter="MyWebAppResources" -null="false" /> -</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 '<i>???keyname???</i>'. - </p> - - </section> - - <section name="4.6.4 PlugIn Configuration" href="plugin_config"> - - <p> - Struts PlugIns are configured using the <code><plug-in></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><set-property></code> element is available. - </p> - - <p> - This is an example using the Tiles plugin: - </p> - -<pre> -<plug-in className="org.apache.struts.tiles.TilesPlugin" > -<set-property - property="definitions-config" - value="/WEB-INF/tiles-defs.xml"/> -</plug-in> -</pre> - - </section> - - <section name="4.6.5 Other Configuration Objects" href="other_config"> - - <p> - Besides the objects related to defining ActionMappings, the Struts configuration may - contain elements that create other useful objects. - </p> - + <p> - The <code><data-sources></code> section, which specifies data sources that your application can use. - This is how you would specify a basic data source for your application inside of struts-config.xml: + The Struts configuration file includes several other elements that you + can use to customize your application. + See chapter 7 for details. </p> -<pre><![CDATA[ -<struts-config> -<data-sources> -<!-- configuration for GenericDataSource wrapper --> -<data-source> - <set-property - property="autoCommit" - value="false"/> - <set-property - property="description" - value="Example Data Source Configuration"/> - <set-property - property="driverClass" - value="org.postgresql.Driver"/> - <set-property - property="maxCount" - value="4"/> - <set-property - property="minCount" - value="2"/> - <set-property - property="password" - value="mypassword"/> - <set-property - property="url" - value="jdbc:postgresql://localhost/mydatabase"/> - <set-property - property="user" - value="myusername"/> -</data-source> - -<!-- configuration for commons BasicDataSource --> -<data-source type="org.apache.commons.dbcp.BasicDataSource"> - <set-property - property="driverClassName" - value="org.postgresql.Driver" /> - <set-property - property="url" - value="jdbc:postgresql://localhost/mydatabase" /> - <set-property - property="maxActive" - value="10" /> - <set-property - property="maxWait" - value="5000" /> - <set-property - property="defaultAutoCommit" - value="false" /> - <set-property - property="defaultReadOnly" - value="false" /> - -</data-source> -</data-sources> -</struts-config> -]]></pre> - - <p> - For information on how to retrieve the data source, see the - <a href="building_model.html#databases">Accessing Relational Databases</a> section. - </p> - - <p> - <i>Note: Since Struts is now using commons-dbcp for all it's - data-source needs, the query you provide for the pingQuery - attribute must return at least one row.</i> - </p> - - <p> - <b>Example:</b> <code>SELECT COUNT(*) FROM VALIDTABLE</code> - </p> - - <p> - Just be sure you to replace "VALIDTABLE" with the name of a valid table in your database. - </p> - - </section> - - <section name="4.7 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="4.7.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><![CDATA[ -<servlet> - <servlet-name>action</servlet-name> - <servlet-class> - org.apache.struts.action.ActionServlet - </servlet-class> - <init-param> - <param-name>application</param-name> - <param-value> - org.apache.struts.example.ApplicationResources - </param-value> - </init-param> - <init-param> - <param-name>config</param-name> - <param-value> - /WEB-INF/struts-config.xml - </param-value> - </init-param> - <init-param> - <param-name>debug</param-name> - <param-value>2</param-value> - </init-param> - <init-param> - <param-name>mapping</param-name> - <param-value> - org.apache.struts.example.ApplicationMapping - </param-value> - </init-param> - <load-on-startup>2</load-on-startup> -</servlet> -]]></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. - [/WEB-INF/struts-config.xml].</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>debug</strong> - TThe 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]</li> - <li><strong>detail</strong> - The debugging detail level for the Digester - we utilize to process the application module configuration files. Accepts - values 0 (off) and 1 (least serious) through 6 (most serious). [0]</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 <b>deprecated</b>.</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 <message-resources> 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 <controller> 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 <controller> element.</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 <message-resources> 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 <form-bean> 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 <forward> 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>Action.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 <controller> 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 <action> element, or globally for a module by using the - "type" attribute of the <action-mappings> 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 <controller> 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 <controller> 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 <controller> 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 <message-resources> 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 <controller> element.</em></li> - </ul> - </section> - - <section name="4.7.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> - <servlet-mapping> - <servlet-name>action</servlet-name> - <url-pattern>/do/*</url-pattern> - </servlet-mapping> -</pre> - - <p> - which means that a request URI to match the <code>/logon</code> path - described earlier might look like this:</p> - -<pre> -http://www.mycompany.com/myapplication/do/logon -</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> - <servlet-mapping> - <servlet-name>action</servlet-name> - <url-pattern>*.do</url-pattern> - </servlet-mapping> -</pre> - - <p> - and a request URI to match the <code>/logon</code> path described - earlier might look like this: - </p> - -<pre> -http://www.mycompany.com/myapplication/logon.do -</pre> - - <p><font color="red"><strong>WARNING</strong></font> - Struts will not - operate correctly if you define more than one - <code><servlet-mapping></code> element for the controller - servlet.</p> - - <p><font color="red"><strong>WARNING</strong></font> - 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="4.7.3 Configure the Struts Tag Library" href="dd_config_taglib"> - <p> - Next, you must add an entry defining the Struts tag library. There are six taglibs - included with the Struts distribution. - </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-template taglib contains tags that define a template mechanism. - </p> - <p> - The struts-tiles taglib contains tags used for combining various view components, - called "tiles", into a final composite view. This is similar to struts-template in that - it's used for view composition, but tiles is a more full featured set of tags. - </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> -<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> -</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="4.7.3.1 Configure the Struts Tag Library (Servlet 2.3)" href="dd_config_taglib_23"> - <p> - <b>Servlet 2.3 Users only:</b> The Servlet 2.3 specification simplifies the - deployment and configuration of tag libraries. The instructions above will work - on older containers as well as 2.3 containers (Struts only requires a servlet 2.2 container); - however, if you're using a 2.3 container such as Tomcat 4.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: - <br/> - <code><%@ taglib uri="http://jakarta.apache.org/struts/tags-html-1.0" prefix="html" %></code> - <br/> - Note that you <b>must use the full uri</b> 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="4.7.4 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="4.7.4.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. Modules to the rescue! - </p> - <p> - With the advent of modules, a given module has it's - 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="4.7.4.2 Informing the Controller" href="module_config-inform_conroller"> - <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> - ... - <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> - ... -</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 symmety of having all my Struts module files being named struts-<module>.xml) - </p> - </section> <section name="4.7.4.3 Using Actions for Pages" href="module_config-use_actions"> @@ -1414,23 +817,7 @@ </p> </section> - <section name="4.8 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> - <b>Servlet 2.3 Users:</b> See <a href="#dd_config_taglib_23">section 4.7.3.1</a> - for how to avoid copying the tlds into your application. - </p> - - </section> - - <section name="4.9 Commons Logging Interface" href="logging"> + <section name="4.8 Commons Logging Interface" href="logging"> <p> Struts doesn't configure logging itself -- it's all done by commons-logging under the covers. The default algorithm is a search:
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>