husted      2002/06/24 04:14:44

  Modified:    doc/userGuide introduction.xml building_view.xml
                        building_model.xml building_controller.xml
  Log:
  Various 1.1-orientated changes. Refer to execute method throughout. Refer to "Action 
Mappings" configuration file as "Struts" configuration file. Minor organizational 
enhancements. Still need to insert material regarding new 1.1 features.
  
  Revision  Changes    Path
  1.11      +139 -136  jakarta-struts/doc/userGuide/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/doc/userGuide/introduction.xml,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- introduction.xml  23 Jun 2002 14:06:17 -0000      1.10
  +++ introduction.xml  24 Jun 2002 11:14:44 -0000      1.11
  @@ -25,7 +25,7 @@
   
       <ul>
         <li><a href="http://www.ietf.org/rfc/rfc2616.txt?number=2616";>The HTTP 
Request/Response sequence</a></li>
  -      <li><a href="http://java.sun.com/products/jsp/product.html";>Java 
Servlets</a></li>
  +      <li><a href="http://java.sun.com/products/servlet/";>Java Servlets</a></li>
         <li><a href="http://java.sun.com/products/javabeans/";>JavaBeans</a></li>
         <li><a 
href="http://java.sun.com/docs/books/tutorial/essential/attributes/properties.html";>Properties</a>
 files and 
         <a 
href="http://java.sun.com/docs/books/tutorial/i18n/resbundle/concept.html";>ResourceBundles</a></li>
  @@ -34,8 +34,8 @@
         <li><a href="http://www.w3.org/XML/";>Extensible Markup Language</a></li>
       </ul>
   
  -       <p>If you are not already familiar with these technologies, the best 
starting point 
  -         <a href="http://java.sun.com/webservices/docs/1.0/tutorial/index.html";>The 
Java Web Services Tutorial</a>
  +       <p>If you are not already familiar with these technologies, the best overall 
starting point is 
  +         <a 
href="http://java.sun.com/webservices/docs/1.0/tutorial/index.html";><b>The Java Web 
Services Tutorial</b></a>
            for the Java Web Services Developer Pack.
          </p>
   
  @@ -83,9 +83,13 @@
   
           <p>
             Of course, there is nothing new under the Sun ... and many have been 
quick to point out that
  -          JSP's Model 2 follows the classic Model-View-Controller design pattern 
abstracted from the 
  -          venerable Smalltalk Model/View/Controller framework. It is now 
commonplace to use the terms
  -          Model 2 and MVC interchangeably.
  +          JSP's Model 2 follows the classic 
  +          <a 
href="http://java.sun.com/blueprints/patterns/j2ee_patterns/model_view_controller/";>Model-View-Controller</a>
 
  +          design pattern abstracted from the venerable 
  +          <a 
href="http://st-www.cs.uiuc.edu/users/smarch/st-docs/mvc.html";>Smalltalk MVC 
framework</a>. 
  +          Java Web developers now tend to use the terms Model 2 and MVC 
interchangeably. In this guide, we use 
  +          the MVC paradigm to describe the Struts architechture, which might be 
best termed a Model 2/MVC 
  +          design.
           </p>
   
           <p>
  @@ -115,8 +119,132 @@
   
         </section>
         
  +    <section name="1.2.1 The Model: System State and Business Logic JavaBeans" 
href="modelConcepts">
  +      
  +      <p>
  +        The <i>Model</i> portion of an MVC-based system can be often be divided into
  +        two major subsystems -- the <b>internal state</b> of the system 
  +        and the <b>actions</b> that can be taken to change that state.
  +      </p>
  +
  +       <p>In grammatical terms, we might think about
  +        state information as <b>nouns</b> (things) and actions as <b>verbs</b>
  +        (changes to the state of those things).
  +      </p>
  +        
  +      <p>
  +        Many applications represent the internal state of the
  +        system as a set of one or more JavaBeans. The bean properties represent
  +        the details of the system' state.  Depending on your application's 
complexity,
  +        these beans may be self contained (and know how to persist their own state),
  +        or they may be facades that know how to retrieve the system's state from 
another 
  +        component. This component may be a database, a search engine, an Entity 
Enterprise 
  +        JavaBean, a LDAP server, or something else entirely.
  +      </p>
  +        
  +      <p>
  +        Large-scale applications will often represent the set of possible
  +        business operations as methods that can be called on the bean or beans 
  +        maintaining the state information.  For example, you might have a shopping
  +        cart bean, stored in session scope for each current user, with properties
  +        that represent the current set of items that the user has decided to
  +        purchase. This bean might also have a <code>checkOut()</code> method
  +        that authorizes the user's credit card and sends the order to the
  +        warehouse to be picked and shipped. Other systems will represent the
  +        available operations separately, perhaps as Session Enterprise JavaBeans
  +        (Session EJBs).
  +      </p>
  +        
  +      <p>
  +        In a smaller scale application, on the other hand, the available
  +        operations might be embedded within the <code>Action</code> classes that are
  +        part of the Struts control layer. This can be useful when the logic is very
  +        simple or where reuse of the business logic in other environments is not
  +        contemplated.
  +      </p>
  +  
  +      <p>
  +        The Struts framework architecture is flexible enough to support most any 
  +        approach to accessing the Model, but we <b>strongly</b> recommend that you 
  +        separate the business logic ("how it's done") from the role that 
  +        <code>Action</code> classes play ("what to do"). 'nuff said.
  +      </p>    
  +  
  +      <p>
  +        For more about adapting your application's Model to Struts, see the
  +        <a href="building_model.html">Building Model Components</a> chapter.
  +      </p>
   
  -      <section name="1.3 Struts Framework Overview" href="overview">
  +   </section>
  +
  +    <section name="1.2.2 The View: JSP Pages and Presentation Components" 
href="presentationConcepts">     
  +
  +      <p>
  +        The <i>View</i> portion of a Struts-based application is most often 
  +        constructed using JavaServer Pages (JSP) technology.  JSP pages can
  +        contain static HTML (or XML) text called "template text", plus the
  +        ability to insert dynamic content based on the interpretation (at page
  +        request time) of special action tags.  The JSP environment includes a
  +        set of standard action tags, such as <code>&lt;jsp:useBean&gt;</code>
  +        whose purpose is described in the <a 
href="http://java.sun.com/products/jsp/download.html";>JavaServer Pages 
Specification</a>.  
  +        In addition to the built-in actions, there is a standard facility to 
  +        define your own tags, which are organized into "custom tag libraries."
  +      </p>
  +          
  +      <p>
  +        Struts includes a set of custom custom tag libraries that facilitate
  +        creating user interfaces that are fully internationalized, and that
  +        interact gracefully with <code>ActionForm</code> beans that are part
  +        of the <i>Model</i> portion of the system.  
  +      </p>
  +
  +      <p>
  +        For more about the Struts taglibs and using presentation pages 
  +        with the framework, see the 
  +        "<a href="building_view.html">Building View Components</a>" chapter. 
  +        Additional documentation regarding the taglibs is also available in 
  +        the Developer Guides (see menu).
  +      </p>
  +    </section>
  +    
  +    <section name="1.2.3 The Controller: ActionServlet and ActionMapping" 
href="controllerConcepts">
  +      
  +      <p>
  +        The <i>Controller</i> portion of the application is focused on receiving
  +        requests from the client (typically a user running a web browser), deciding
  +        what business logic function is to be performed, and then delegating
  +        responsibility for producing the next phase of the user interface to
  +        an appropriate View component.  In Struts, the primary component of the
  +        Controller is a servlet of class <code>ActionServlet</code>. This servlet
  +        is configured by defining a set of <code>ActionMappings</code>. 
  +        An ActionMapping defines a <code>path</code> that is matched against the 
  +        request URI of the incoming request, and usually specifies the
  +        fully qualified class name of an Action class. All Actions
  +        are subclassed from <code>org.apache.struts.action.Action</code>. Actions 
  +        encapsulate the business logic, interpret the outcome, and ultimately 
dispatch
  +        control to the appropriate View component to create the response.
  +      </p>
  +        
  +      <p>
  +        Struts also supports the ability to use <code>ActionMapping</code>
  +        classes that have additional properties beyond the standard ones required
  +        to operate the framework. This allows you to store additional information
  +        specific to your application, but still utilize the remaining features of
  +        the framework. In addition, Struts lets you define logical "names" to which
  +        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 rendered).
  +      </p>
  +
  +      <p>
  +        For more about the Struts control layer, see the
  +        <a href="building_controller.html">Building Controller Components</a> 
chapter.
  +      </p>
  +
  +      </section>
  +      
  +      <section name="1.3 Struts Control Flow" href="flow">
         
           <p>
             The Struts framework provides several components that make up the 
<b>Control</b> 
  @@ -137,7 +265,7 @@
           </p>
   
           <p>
  -          The <b>Model</b> layer in a MVC application can be project-specific. 
Struts is 
  +          The <b>Model</b> layer in a MVC application is often project-specific. 
Struts is 
             designed to makes it easy to access the business-end of your application, 
             but leaves that part of the programming to other products, like 
             <a href="http://java.sun.com/products/jdbc/index.html";>JDBC</a>, 
  @@ -243,7 +371,7 @@
           </p>
            
           <ul>
  -        <li>The controller servlet either retrieves or creates the ActinForm bean 
instance.</li>
  +        <li>The controller servlet either retrieves or creates the ActionForm bean 
instance.</li>
           <li>The controller servlet passes the bean to the Action object.</li>
           <li>If the request is being used to to submit an input page, the Action 
object 
           can examine the data. If necessary, the data can be sent back to the input 
  @@ -321,136 +449,11 @@
             <a href="http://www.apache.org/LICENSE-1.1";>ASF license</a> for 
specifics. 
            </p>
             
  -    </section>
  -
  -    <section name="1.4 The Model: System State and Business Logic JavaBeans" 
href="modelConcepts">
  -      
  -      <p>
  -        The <i>Model</i> portion of an MVC-based system can be often be divided into
  -        two major subsystems -- the <b>internal state</b> of the system 
  -        and the <b>actions</b> that can be taken to change that state.
  -      </p>
  -
  -       <p>In grammatical terms, we might think about
  -        state information as <b>nouns</b> (things) and actions as <b>verbs</b>
  -        (changes to the state of those things).
  -      </p>
  -        
  -      <p>
  -        Many applications represent the internal state of the
  -        system as a set of one or more JavaBeans. The bean properties represent
  -        the details of the system' state.  Depending on your application's 
complexity,
  -        these beans may be self contained (and know how to persist their own state),
  -        or they may be facades that know how to retrieve the system's state from 
another 
  -        component. This component may be a database, a search engine, an Entity 
Enterprise 
  -        JavaBean, a LDAP server, or something else entirely.
  -      </p>
  -        
  -      <p>
  -        Large-scale applications will often represent the set of possible
  -        business operations as methods that can be called on the bean or beans 
  -        maintaining the state information.  For example, you might have a shopping
  -        cart bean, stored in session scope for each current user, with properties
  -        that represent the current set of items that the user has decided to
  -        purchase. This bean might also have a <code>checkOut()</code> method
  -        that authorizes the user's credit card and sends the order to the
  -        warehouse to be picked and shipped. Other systems will represent the
  -        available operations separately, perhaps as Session Enterprise JavaBeans
  -        (Session EJBs).
  -      </p>
  -        
  -      <p>
  -        In a smaller scale application, on the other hand, the available
  -        operations might be embedded within the <code>Action</code> classes that are
  -        part of the Struts control layer. This can be useful when the logic is very
  -        simple or where reuse of the business logic in other environments is not
  -        contemplated.
  -      </p>
  -  
  -      <p>
  -        The Struts framework architecture is flexible enough to support most any 
  -        approach to accessing the Model, but we <b>strongly</b> recommend that you 
  -        separate the business logic ("how it's done") from the role that 
  -        <code>Action</code> classes play ("what to do"). 'nuff said.
  -      </p>    
  -  
  -      <p>
  -        For more about adapting your application's Model to Struts, see the
  -        <a href="building_model.html">Building Model Components</a> chapter.
  -      </p>
  -
  -   </section>
  -
  -    <section name="1.5 The View: JSP Pages and Presentation Components" 
href="presentationConcepts">     
  -
  -      <p>
  -        The <i>View</i> portion of a Struts-based application is most often 
  -        constructed using JavaServer Pages (JSP) technology.  JSP pages can
  -        contain static HTML (or XML) text called "template text", plus the
  -        ability to insert dynamic content based on the interpretation (at page
  -        request time) of special action tags.  The JSP environment includes a
  -        set of standard action tags, such as <code>&lt;jsp:useBean&gt;</code>
  -        whose purpose is described in the <a 
href="http://java.sun.com/products/jsp/download.html";>JavaServer Pages 
Specification</a>.  
  -        In addition to the built-in actions, there is a standard facility to 
  -        define your own tags, which are organized into "custom tag libraries."
  -      </p>
  -          
  -      <p>
  -        Struts includes a set of custom custom tag libraries that facilitate
  -        creating user interfaces that are fully internationalized, and that
  -        interact gracefully with <code>ActionForm</code> beans that are part
  -        of the <i>Model</i> portion of the system.  
  -      </p>
  -
  -      <p>
  -        For more about the Struts taglibs and using presentation pages 
  -        with the framework, see the 
  -        "<a href="building_view.html">Building View Components</a>" chapter. 
  -        Additional documentation regarding the taglibs is also available in 
  -        the Developer Guides (see menu).
  -      </p>
  -    </section>
  -    
  -    <section name="1.6 The Controller: ActionServlet and ActionMapping" 
href="controllerConcepts">
  -      
  -      <p>
  -        The <i>Controller</i> portion of the application is focused on receiving
  -        requests from the client (typically a user running a web browser), deciding
  -        what business logic function is to be performed, and then delegating
  -        responsibility for producing the next phase of the user interface to
  -        an appropriate View component.  In Struts, the primary component of the
  -        Controller is a servlet of class <code>ActionServlet</code>. This servlet
  -        is configured by defining a set of <code>ActionMappings</code>. 
  -        An ActionMapping defines a <code>path</code> that is matched against the 
  -        request URI of the incoming request, and usually specifies the
  -        fully qualified class name of an Action class. All Actions
  -        are subclassed from <code>org.apache.struts.action.Action</code>. Actions 
  -        encapsulate the business logic, interpret the outcome, and ultimately 
dispatch
  -        control to the appropriate View component to create the response.
  -      </p>
  -        
  -      <p>
  -        Struts also supports the ability to use <code>ActionMapping</code>
  -        classes that have additional properties beyond the standard ones required
  -        to operate the framework. This allows you to store additional information
  -        specific to your application, but still utilize the remaining features of
  -        the framework. In addition, Struts lets you define logical "names" to which
  -        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 rendered).
  -      </p>
  -
  -      <p>
  -        For more about the Struts control layer, see the
  -        <a href="building_controller.html">Building Controller Components</a> 
chapter.
  -      </p>
  -      
         <p align="center">
           Next: <a href="building_model.html">Building Model Components</a>
         </p>
  -      </section>
  -      
  +     
  +    </section>
         
       </chapter>
       </body>
  
  
  
  1.12      +18 -17    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.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- building_view.xml 23 Jun 2002 17:55:55 -0000      1.11
  +++ building_view.xml 24 Jun 2002 11:14:44 -0000      1.12
  @@ -17,9 +17,10 @@
         <section name="3.1 Overview" href="overview">
           
           <p>
  -          This chapter focuses on the task of building the <i>View</i> components
  -        of the application, which will primarily be created using JavaServer Pages
  -        (JSP) technology.  In particular, Struts provides support for building
  +        This chapter focuses on the task of building the <i>View</i> components
  +        for use with the Struts framework. Many applications rely on JavaServer 
Pages
  +        (JSP) technology to create the presentation layer. The Struts distribution 
  +        includes a comprehensive JSP tag library that provides support for building
           internationalized applications, as well as for interacting with input forms.
           Several other topics related to the View components are briefly discussed.
         </p>
  @@ -42,8 +43,8 @@
         </p>
           
         <p>
  -        Struts builds upon the Java platform to provide assistance
  -        for building internationalized and localized applications.  The key concepts
  +        Struts builds upon the standard classes available on the Java platform to 
  +        build internationalized and localized applications. The key concepts
           to become familiar with are:
         </p>
         
  @@ -162,7 +163,7 @@
         <blockquote> 
           <b>Note:</b> While the examples given here use JSP and custom tags, 
           the ActionForm beans and the other Struts controller components are 
  -        view neutral. Struts can be used with Velocity Templates, XLST, and 
  +        View neutral. Struts can be used with Velocity Templates, XLST, and 
           any other presentation technology that can be rendered via a Java 
           servlet. See the 
           <a href="../resources/index.html">
  @@ -323,7 +324,7 @@
                 automatically, using the specified Java class name.
                 <li>The form bean can also be specified in the Struts configuration 
file, 
                 in which case the Name and Type can be omitted 
  -              here. See "<a href="building_controller.html#config">The Action 
Mappings 
  +              here. See "<a href="building_controller.html#config">The Struts  
                 Configuration File</a>" for details.)</li>
                 </li>
             <li>The text tag renders an HTML
  @@ -331,7 +332,7 @@
                 the number of character positions to occupy on the browser's screen
                 has been specified as well.  When this page is executed, the current
                 value of the <code>username</code> property of the corresponding bean
  -              (that is, the value returned by <code>getUsername()</code>).</li>
  +              (that is, the value returned by <code>getUsername</code>).</li>
             <li>The password tag is used similarly.
                 The difference is that the browser will echo asterisk characters,
                 instead of the input value, as the user types their password.</li>.
  @@ -397,7 +398,7 @@
             methods it exposes to manipulate files in file uploading.  Also look at 
the
             Javadocs for ActionServlet and ActionMapping for the various parameters
             you can specify to change how files are uploaded.  Basically in your
  -          perform() method in your action class you would call <code>((UploadForm) 
form).getMyFile()</code>
  +          <code>execute</code> method in your action class you would call 
<code>((UploadForm) form).getMyFile()</code>
             to retrieve the FormFile and do what you want with it.
           </p>        
                 
  @@ -484,16 +485,16 @@
   </pre>
           
           <p>
  -          The validate() method is called by the controller servlet after the bean
  +          The <code>validate</code> method is called by the controller servlet 
after the bean
             properties have been populated, but before the corresponding action 
class's
  -          <code>perform()</code> method is invoked. The <code>validate()</code> 
method
  +          <code>perform</code> method is invoked. The <code>validate</code> method
             has the following options:
           </p>
           
           <ul>
             <li>Perform the appropriate validations and find no problems -- Return 
either
                 <code>null</code> or a zero-length ActionErrors instance, and the 
controller 
  -              servlet will proceed to call the <code>perform()</code> method of the 
  +              servlet will proceed to call the <code>perform</code> method of the 
                 appropriate <code>Action</code> class.</li>
             <li>Perform the appropriate validations and find problems -- Return an 
ActionErrors
                 instance containing <code>ActionError</code>'s, which are classes 
that contain
  @@ -507,12 +508,12 @@
             
           <p>
             As mentioned earlier, this feature is entirely optional.  The default 
implementation
  -          of the validate() method returns <code>null</code>, and the controller 
servlet
  +          of the <code>validate</code> method returns <code>null</code>, and the 
controller servlet
             will assume that any required validation is done by the action class.
           </p>
           <p>
             One common approach is to perform simple, prima facia validations using 
the 
  -          ActionForm validate() method, and then handle the "business logic" 
validation 
  +          ActionForm <code>validate</code> method, and then handle the "business 
logic" validation 
             from the Action. 
           </p>
           <p>
  @@ -617,12 +618,12 @@
           </ul>
           <p>
             Another approach to this would be to use the Struts Template Tag library. 
See the         
  -          Developer's Guide for details.
  +          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/";>
  +          enhancements and new capabilities. Tiles is bundled with Struts 1.1 and 
also 
  +          available from <a href="http://www.lifl.fr/~dumoulin/tiles/";>
             Cedric Dumoulin's Web site</a>.
           </p>
         </section>
  
  
  
  1.8       +8 -8      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.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- building_model.xml        23 Jun 2002 18:57:19 -0000      1.7
  +++ building_model.xml        24 Jun 2002 11:14:44 -0000      1.8
  @@ -46,7 +46,7 @@
         <ul>
           <li><b>page</b> - Beans that are visible within a single JSP page,
               for the lifetime of the current request.  (Local variables of
  -            the <code>service()</code> method)</li>
  +            the <code>service</code> method)</li>
           <li><b>request</b> - Beans that are visible within a single JSP page,
               as well as to any page or servlet that is included in this page,
               or forwarded to by this page.  (Request attributes)</li>
  @@ -96,7 +96,7 @@
           several forms, or even an entire application.
          </p>
          <p>
  -        If you declare such beans in your <code>ActionMapping</code>
  +        If you declare such beans in your Struts 
           configuration file (see "<a href="building_controller.html#config">
           Building the Controller Components</a>"), the Struts  controller servlet 
           will automatically perform the following services for you, before 
  @@ -114,7 +114,7 @@
               JSP action <code>&lt;jsp:setProperty&gt;</code> when you use the
               asterisk wildcard to select all properties.</li>
           <li>The updated <code>ActionForm</code> bean will be passed to the
  -            Action Class <code>perform()</code> method when it is called,
  +            Action Class <code>execute</code> method when it is called,
               making these values immediately available.</li>
         </ul>
           
  @@ -136,11 +136,11 @@
               href="./building_view.html#form_validation">Action Form Validation</a>" 
               for details. Of course, you can also ignore the ActionForm validation 
               and provide your own in the Action object.</li>            
  -        <li>Define a property (with associated <code>getXxx()</code> and
  -            <code>setXxx()</code> methods) for each field that is present
  +        <li>Define a property (with associated <code>getXxx</code> and
  +            <code>setXxx</code> methods) for each field that is present
               in the form.  The field name and property name must match according
               to the usual JavaBeans conventions.  For example, an input field named
  -            <code>username</code> will cause the <code>setUsername()</code> method
  +            <code>username</code> will cause the <code>setUsername</code> method
               to be called.</li>
           <li>Buttons and other controls on your form can also be defined as 
properties. 
               This can help determine which button or control was selected when the 
  @@ -225,7 +225,7 @@
           rearranging things so that your <code>Action</code> classes (part of the
           Controller role, as described below) translate all required information
           from the HTTP request being processed into property setter calls on your
  -        business logic beans, after which a call to an <code>execute()</code> method
  +        business logic beans, after which a call to an <code>execute</code> method
           can be made.  Such a business logic class can be reused in environments
           other than the web application for which they were initially constructed.
         </p>
  @@ -263,7 +263,7 @@
           [org.apache.struts.util.GenericDataSource]
           that works well with the datasource manager. If another component 
           is not specified, the Generic DataSource pool is used by default.
  -        See <a  href="building_controller.html#config">The Action Mappings 
  +        See <a  href="building_controller.html#config">The Struts  
           Configuration File</a> section and the Utilities Developer Guide for 
           more detail. 
         </p>
  
  
  
  1.16      +38 -19    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.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- building_controller.xml   23 Jun 2002 01:04:18 -0000      1.15
  +++ building_controller.xml   24 Jun 2002 11:14:44 -0000      1.16
  @@ -24,6 +24,9 @@
         </p>
         
         <ul>
  +        <li>Write an <code>ActionForm</code> class to mediate between the Model 
  +            and the View, as described in <a href="building_model.html">Building 
  +            Model Components</a>.</li>
           <li>Write an <code>Action</code> class for each logical request that may 
               be received (extend <code>org.apache.struts.action.Action</code>).</li>
           <li>Configure a ActionMapping (in XML) for each logical request that may 
  @@ -42,17 +45,17 @@
         </p>
   
   <pre>
  -public ActionForward perform(ActionMapping mapping,
  +public ActionForward execute(ActionMapping mapping,
                                ActionForm form,
                                ServletRequest request,
                                ServletResponse response)
  -  throws IOException, ServletException;
  +  throw Exception;
   
  -public ActionForward perform(ActionMapping mapping,
  +public ActionForward execute(ActionMapping mapping,
                                ActionForm form,
                                HttpServletRequest request,
                                HttpServletResponse response)
  -  throws IOException, ServletException;
  +  throws Exception;
   </pre>
         
         <p>
  @@ -60,11 +63,11 @@
         </p>
         <p>
           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 
  +        its <code>execute()</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:
  +        in its <code>execute()</code> method:
         </p>
         <ul>
           <li>Validate the current state of the user's session (for example, checking
  @@ -114,7 +117,7 @@
           <li>The beans that represent the Model of your system may throw exceptions
               due to problems accessing databases or other resources.
               You should trap all such exceptions
  -            in the logic of your <code>perform()</code> method, and record them in 
the
  +            in the logic of your <code>execute()</code> method, and record them in 
the
               application's log (along with the corresponding stack trace) by
               calling:<br />
               <code>servlet.log("Error message text", exception);</code></li>
  @@ -146,10 +149,24 @@
         <p>
           The example application included with Struts stretches this design
           principle somewhat, because the business logic itself is embedded in the
  -        <code>Action</code> classes.  This should be considered something of a
  +        <code>Action</code> classes. This should be considered something of a
           bug in the design of the sample application, rather than an intrinsic
           feature of the Struts architecture, or an approach to be emulated.
         </p>
  +
  +      <p>
  +        In Struts 1.0, Actions called a <code>perform</code> method instead of the 
now 
  +        preferred <code>execute</code> method. These methods use the same 
parameters and 
  +        differ only in which exceptions they throw. The elder <code>perform</code> 
method 
  +        throws <code>SerlvetException</code> and <code>IOException</code>. The new 
<code>execute</code> method 
  +        simply throws <code>Exception</code>. The change was to facilitate the 
Declarative 
  +        Exception handling feature introduced in Struts 1.1.
  +    </p>
  +    <p>
  +        The <code>perform</code> method may still be used in Struts 1.1 but is 
deprecated. 
  +        The Struts 1.1 method simply calls the new <code>execute</code> method and 
wraps 
  +        any <code>Exception</code> thrown as a <code>ServletException</code>. 
  +    </p>
       </section>
           
       <section name="4.3 The ActionMapping Implementation" href="actionmapping">
  @@ -184,24 +201,25 @@
                  
       </section>
       
  -    <section name="4.4 The Action Mappings Configuration File" href="config">
  +    <section name="4.4 The Struts Configuration File" href="config">
         
         <p>
           How does the controller servlet learn about the mappings you want?  It
           would be possible (but tedious) to write a small Java class that simply
           instantiated new <code>ActionMapping</code> instances, and called all of
  -        the appropriate setter methods.  To make this process easier, Struts 
includes
  -        a Digester module that is capable of reading an XML-based description of
  -        the desired mappings, creating the appropriate objects along the way.
  -        See the <a href="../api/index.html">API documentation</a> for more 
information
  -        about Digester.
  +        the appropriate setter methods.  To make this process easier, Struts uses 
the 
  +        Jakarta-Digester component to parse an XML-based description of
  +        the desired mappings and create the appropriate objects initialized to the 
  +        appropriate default values. 
  +        See the <a href="http://jakarta.apache.org/commons";>Jakarta Commons web 
site</a> 
  +        for more information about the Digester.
         </p>
           
         <p>
           The developer's responsibility is to create an XML file named
           <code>struts-config.xml</code>, and place it in the WEB-INF directory of 
your
           application. This format of this document is constrained by it's definition 
in 
  -        "struts-config_1_0.dtd".  The outermost XML element must be 
<code>&lt;struts-config&gt;</code>.       
  +        "struts-config_1_1.dtd". The outermost XML element must be 
<code>&lt;struts-config&gt;</code>.       
         </p>
         
         <p>
  @@ -210,7 +228,8 @@
           
           <blockquote>
             <b>&lt;form-beans&gt;</b><br />
  -            This section contains your form bean definitions.  You use a 
&lt;form-bean&gt; element
  +            This section contains your form bean definitions.  Form beans are 
descriptors that 
  +            are used to create ActionForm instances at runtime. You use a 
&lt;form-bean&gt; element
               for each form bean, which has the following important attributes:
               <ul>
                 <li>
  @@ -220,15 +239,15 @@
                   this form bean will be stored.
                 </li>
                 <li>
  -                <b>type</b>: The fully-qualified Java classname of your form bean.
  +                <b>type</b>: The fully-qualified Java classname of the ActionForm 
subclass to use with this form bean.
                 </li>
               </ul>
           </blockquote>
           <blockquote>
             <b>&lt;action-mappings&gt;</b><br />
               This section contains your action definitions.  You use an 
&lt;action&gt; element
  -            for each of your actions you would like to define.  Each action element 
requires
  -            the following attributes to be defined:
  +            for each of the mappings you would like to define.  Most action 
elements will 
  +            define at least the following attributes:
               
               <ul>
                 <li>
  
  
  

--
To unsubscribe, e-mail:   <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>

Reply via email to