husted 01/11/03 19:07:34 Modified: doc/userGuide introduction.xml index.xml building_view.xml building_model.xml building_controller.xml Log: Several stylistic changes. Add caution regarding using nested beans with ActionForms. Add section regarding rendering text. Revision Changes Path 1.8 +1 -1 jakarta-struts/doc/userGuide/introduction.xml Index: introduction.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/introduction.xml,v retrieving revision 1.7 retrieving revision 1.8 diff -u -r1.7 -r1.8 --- introduction.xml 2001/11/03 12:24:25 1.7 +++ introduction.xml 2001/11/04 03:07:34 1.8 @@ -355,7 +355,7 @@ control should be forwarded so that an action method can ask for the "Main Menu" page (for example), without knowing what the actual name of the corresponding JSP page is. These features greatly assist you in separating - the control logic (what to do) with the view logic (how it's done). + the control logic (what to do) with the view logic (how it's rendered). </p> <p align="center"> 1.5 +1 -0 jakarta-struts/doc/userGuide/index.xml Index: index.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- index.xml 2001/10/05 11:19:29 1.4 +++ index.xml 2001/11/04 03:07:34 1.5 @@ -50,6 +50,7 @@ <li><a href="building_view.html#custom_tags">3.4.1 Application-Specific Custom Tags</a></li> <li><a href="building_view.html#includes">3.4.2 Page Composition With Includes</a></li> <li><a href="building_view.html#image_rendering">3.4.3 Image Rendering Components</a></li> + <li><a href="building_view.html#text_rendering">3.4.4 Rendering Text</a></li> </ul></li> </ul></li> <li><a href="building_controller.html">4. Building Controller Components</a> 1.6 +59 -21 jakarta-struts/doc/userGuide/building_view.xml Index: building_view.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_view.xml,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- building_view.xml 2001/10/19 05:51:09 1.5 +++ building_view.xml 2001/11/04 03:07:34 1.6 @@ -80,10 +80,11 @@ </ul> <p> - Please note that the i18n support in Struts is currently limited to the - <b>presentation</b> of internationalized information to the user. - Support for various Locale specific <b>input methods</b> is left up - to the client device, which is usually a web browser. + Please note that the i18n support in a framework like Struts is limited to the + <b>presentation</b> of internationalized text and images to the user. + Support for Locale specific <b>input methods</b> (used with languages + such as Japanese, Chinese, and Korean) is left up to the client device, which + is usually a web browser. </p> <p> @@ -138,13 +139,24 @@ The important thing is for the resource bundle to be found on the class path for your application. Another approach is to store the <code>MyResources.properties</code> file in your application's - class folder. You can then simply specify "myResources" as the - application value. + <code>classes</code> folder. You can then simply specify "myResources" as the + application value. Just be careful it is not deleted if your + build script deletes classes as part of a "clean" target. </p> + <p> + If it does, here is an Ant task to run when compiling your application + that copies the contents of a <code>src/conf</code> + directory to the <code>classes</code> directory: + </p> + <pre> + <!-- Copy any configuration files --> + <copy todir="classes"> + <fileset dir="src/conf"/> + </copy> + </pre> </section> - <section name="3.3 Forms and FormBean Interactions" href="form_beans"> - + <section name="3.3 Forms and FormBean Interactions" href="form_beans"> <p> At one time or another, most web developers have built forms using the standard capabilities of HTML, such as the <code><input></code> @@ -189,8 +201,9 @@ files. Struts handles these "multipart" forms in a way identical to building normal forms. In the next section, we will cover using Struts to create a simple login form, and also a simple mulitpart form. - </p> - + </p> + </section> + <section name="3.3.1 Building Forms With Struts" href="forms"> <p> @@ -366,9 +379,9 @@ </pre> <hr/> <p> - Look at the <a href="../api/index.html">javadocs</a> for FormFile to see the + Look at the <a href="../api/index.html">Javadocs</a> for FormFile to see the methods it exposes to manipulate files in file uploading. Also look at the - javadocs for ActionServlet and ActionMapping for the various parameters + Javadocs for ActionServlet and ActionMapping for the various parameters you can specify to change how files are uploaded. Basically in your peform() method in your action class you would call <code>((UploadForm) form).getMyFile()</code> to retrieve the FormFile and do what you want with it. @@ -440,7 +453,6 @@ specified request parameter, and defines the result as a page scope attribute of type String or String[].</li> </ul> - </section> <section name="3.3.4 Automatic Form Validation" href="form_validation"> @@ -485,12 +497,16 @@ will assume that any required validation is done by the action class. </p> <p> - One common approach is to perform simple validations using the validate() method, and - also provide further "business logic" validation as part of your Action object. + One common approach is to perform simple, prima facia validations using the + ActionForm validate() method, and then handle the "business logic" validation + from the Action. </p> - + <p> + An optional package for performing ActionForm validations is available in the + Nightly Build and from <a href="http://home.earthlink.net/~dwinterfeldt/"> + David Winterfeldt's Web site</a>. + </p> </section> - </section> <section name="3.4 Other Presentation Techniques" href="other_presentations"> @@ -501,6 +517,7 @@ reuse, reduce maintenance efforts, and/or reduce errors. Several options are discussed in the following sections. </p> + </section> <section name="3.4.1 Application-Specific Custom Tags" href="custom_tags"> @@ -569,9 +586,9 @@ <ul> <li>An <code><%@ include file="xxxxx" %></code> directive can include a file that contains - java code or jsp tags. The code in the included file can even reference + Java code or JSP tags. The code in the included file can even reference variables declared earlier in the outer jsp page. The code is inlined into - the other jsp before it is compiled so it can definately contain more than + the other JavaServer Page before it is compiled so it can definately contain more than just HTML.</li> <li>The include <i>action</i> (<code><jsp:include page="xxxxx" flush="true" /></code>) is processed at request time, and is handled @@ -588,6 +605,12 @@ Another approach to this would be to use the Struts Template Tag library. See the Developer's Guide for details. </p> + <p> + Tiles is an alternative to the original Template Tag library, offering several + enhancements and new capabilities. Tiles is available in the + Nightly Build, and from <a href="http://www.lifl.fr/~dumoulin/tiles/"> + Cedric Dumoulin's Web site</a>. + </p> </section> <section name="3.4.3 Image Rendering Components" href="image_rendering"> @@ -610,12 +633,27 @@ can have the applet make its own connection to the server to receive these parameters.</li> </ul> - + </section> + + <section name="3.4.4 Rendering Text" href="text_rendering"> + + <p> + Some applications require dynamically generated text or markup, + such as XML. If a complete page is being rendered, and can be output + using a PrintWriter, this is very easy to do from an Action: + </p> + <pre> + response.setContentType("text/plain"); // or text/xml + PrintWriter writer = response.getWriter(); + // use writer to render text + return(null); + </pre> + <p align="center"> Next: <a href="building_controller.html">Building Controller Components</a> </p> </section> - </section> + </chapter> </body> </document> 1.4 +17 -2 jakarta-struts/doc/userGuide/building_model.xml Index: building_model.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_model.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- building_model.xml 2001/10/19 05:51:09 1.3 +++ building_model.xml 2001/11/04 03:07:34 1.4 @@ -85,7 +85,7 @@ than the <i>Model</i>. </p> <p> - The Struts framework generally assumes that you have created an + The Struts framework generally assumes that you have defined an <code>ActionForm</code> bean (that is, a Java class extending the <code>ActionForm</code> class) for each input form required in your application. <code>ActionForm</code> beans are sometimes just called @@ -135,12 +135,22 @@ to the usual JavaBeans conventions. For example, an input field named <code>username</code> will cause the <code>setUsername()</code> method to be called.</li> + <li>Think of your ActionForm beans as a firewall between HTTP and the Action. + Use the validate method to ensure all required properties are present, and + that they contain reasonable values. An ActionForm that fails validation + will not even be presented to the Action for handling.</li> <li>You may also place a bean instance on your form, and use nested property references. For example, you might have a "customer" bean on your Action Form, and then refer to the property "customer.name" in your JSP view. This would correspond to the methods <code>customer.getName()</code> and <code>customer.setName(string Name)</code> on your customer bean. See the Tag Library Developer Guides for more about nested syntax.</li> + <li><i>Caution:</i> If you nest an existing bean instance on your form, think + about the properties it exposes. Any public property on an ActionForm that + accepts a single String value can be set with a query string. It may be + useful to place such beans inside a thin "wrapper" that exposes only the + properties required. This wrapper can also provide a filter to be + sure runtime properties are not set to inappropriate values.</li> </ul> <p> @@ -222,7 +232,7 @@ <p> Struts can define the datasources for an application from within its standard - configuration file. A simple JDBC connection pool is also provided. See <a + configuration file. A <b>simple</b> JDBC connection pool is also provided. See <a href="building_controller.html#config">The Action Mappings Configuration File</a> section and the Utilities Developer Guide for details. </p> @@ -259,6 +269,11 @@ } </pre> + <p> + Note that the Struts generic connection pool is an <b>optional</b> component. Many + Struts applications use other connection pools for better performance, + especially with high-volume production systems. + </p> <p align="center"> Next: <a href="building_view.html">Building View Components</a> </p> 1.7 +27 -22 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.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- building_controller.xml 2001/10/19 05:51:09 1.6 +++ building_controller.xml 2001/11/04 03:07:34 1.7 @@ -24,14 +24,10 @@ </p> <ul> - <li>Write an <code>Action</code> class (that is, an extension of the - <code>Action</code> class) for each logical request - that may be received.</li> - <li>[Optionally] Write an <code>ActionMapping</code> class (that is, an - extension of the <code>ActionMapping</code> class) that defines the class - names and other information associated with each possible mapping.</li> - <li>Write the action mapping configuration file (in XML) that is used - to configure the controller servlet. This file is usually named + <li>Write an <code>Action</code> class for each logical request that may + be received (extend <code>org.apache.action.Action</code>).</li> + <li>Configure a ActionMapping (in XML) for each logical request that may + be submitted. The XML configuration file is usually named <code>struts-config.xml</code>.</li> <li>Update the web application deployment descriptor file (in XML) for your application to include the necessary Struts components.</li> @@ -60,31 +56,31 @@ </pre> <p> - Most people would only use the "HttpServletRequest" version. + Most projects would only use the "HttpServletRequest" version. </p> <p> - The goal of an <code>Action</code> class is to process this request, - and then to return an <code>ActionForward</code> object that identifies - the JSP page (if any) to which control should be forwarded to generate - the corresponding response. In the <i>MVC/Model 2</i> design pattern, - a typical <code>Action</code> class will implement the following - logic in its <code>perform()</code> method: + The goal of an <code>Action</code> class is to process a request, via + its <code>perform()</code> method, and return an <code>ActionForward</code> object + that identifies where control should be forwarded (e.g. a JSP) to provide + the appropriate response. In the <i>MVC/Model 2</i> design pattern, + a typical <code>Action</code> class will often implement logic like the following + in its <code>perform()</code> method: </p> <ul> <li>Validate the current state of the user's session (for example, checking that the user has successfully logged on). If the <code>Action</code> - class finds that no logon exists, the request should be forwarded to + class finds that no logon exists, the request can be forwarded to the JSP page that displays the username and password prompts for - logging on. This could occur because a user tried to enter your + logging on. This could occur because a user tried to enter an application "in the middle" (say, from a bookmark), or because the session has timed out, and the servlet container created a new one.</li> - <li>If validation has not yet occurred, - validate the form bean properties as necessary. If a problem is found, + <li>If validation is not complete, + validate the form bean properties as needed. If a problem is found, store the appropriate error message keys as a request attribute, and forward control back to the input form so that the errors can be corrected.</li> <li>Perform the processing required to deal with this request (such as - saving a row into a database). This can be done by code embedded within + saving a row into a database). This can be done by logic code embedded within the <code>Action</code> class itself, but should generally be performed by calling an appropriate method of a business logic bean.</li> <li>Update the server-side objects that will be used to create the next @@ -140,6 +136,12 @@ it is embedded inside a component (the <code>Action</code> class) that is tied to being executed in a web application environment. </p> + + <p> + An <code>Action</code> can be factored into several local methods, so long as all + properties needed are passed in the method signatures. The JVM + handles such properties using the stack, and so they are thread-safe. + </p> <p> The example application included with Struts stretches this design @@ -167,7 +169,6 @@ that this action will use</li> <li><b>path</b> - The request URI path that is matched to select this mapping. See below for examples of how matching works.</li> - <li><b>unknown</b> - Set to <code>true</code> if this action should be configured as the default for this application, to handle all requests not handled by another action. Only one action can be @@ -175,6 +176,10 @@ <li><b>validate</b> - Set to <code>true</code> if the <code>validate()</code> method of the action associated with this mapping should be called.</li> + <li><b>forward</b> - The request URI path to which control is passed + when his mapping is invoked. This is an alternative to declaring + a <b>type</b> property. </li> + </ul> </section> @@ -557,7 +562,7 @@ <p> Next, you must add an entry defining the Struts tag library. There are currently four - taglibs that struts is packaged with. + taglibs that Struts is packaged with. </p> <p> The struts-bean taglib contains tags useful in accessing
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>