View Javadoc

1   /*
2    * $Id: ActionForm.java 421119 2006-07-12 04:49:11Z wsmoak $
3    *
4    * Copyright 2000-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.struts.action;
19  
20  import org.apache.struts.upload.MultipartRequestHandler;
21  
22  import javax.servlet.ServletRequest;
23  import javax.servlet.http.HttpServletRequest;
24  
25  import java.io.Serializable;
26  
27  /***
28   * <p>An <strong>ActionForm</strong> is a JavaBean optionally associated with
29   * one or more <code>ActionMappings</code>. Such a bean will have had its
30   * properties initialized from the corresponding request parameters before the
31   * corresponding <code>Action.execute</code> method is called.</p>
32   *
33   * <p>When the properties of this bean have been populated, but before the
34   * <code>execute</code> method of the <code>Action</code> is called, this
35   * bean's <code>validate</code> method will be called, which gives the bean a
36   * chance to verify that the properties submitted by the user are correct and
37   * valid. If this method finds problems, it returns an error messages object
38   * that encapsulates those problems, and the controller servlet will return
39   * control to the corresponding input form. Otherwise, the
40   * <code>validate</code> method returns <code>null</code>, indicating that
41   * everything is acceptable and the corresponding <code>Action.execute</code>
42   * method should be called.</p>
43   *
44   * <p>This class must be subclassed in order to be instantiated. Subclasses
45   * should provide property getter and setter methods for all of the bean
46   * properties they wish to expose, plus override any of the public or
47   * protected methods for which they wish to provide modified functionality.
48   * </p>
49   *
50   * <p>Because ActionForms are JavaBeans, subclasses should also implement
51   * <code>Serializable</code>, as required by the JavaBean specification. Some
52   * containers require that an object meet all JavaBean requirements in order
53   * to use the introspection API upon which ActionForms rely.</p>
54   *
55   * @version $Rev: 421119 $ $Date: 2005-11-12 08:14:24 -0500 (Sat, 12 Nov 2005)
56   *          $
57   */
58  public abstract class ActionForm implements Serializable {
59      // ----------------------------------------------------- Instance Variables
60  
61      /***
62       * <p>The servlet instance to which we are attached.</p>
63       */
64      protected transient ActionServlet servlet = null;
65  
66      /***
67       * <p>The MultipartRequestHandler for this form, can be
68       * <code>null</code>.</p>
69       */
70      protected transient MultipartRequestHandler multipartRequestHandler;
71  
72      // ------------------------------------------------------------- Properties
73  
74      /***
75       * <p>Return the servlet instance to which we are attached.</p>
76       *
77       * @return The servlet instance to which we are attached.
78       */
79      protected ActionServlet getServlet() {
80          return (this.servlet);
81      }
82  
83      /***
84       * <p>Return the controller servlet instance to which we are attached. as
85       * an <code>ActionServletWrapper</code>.</p>
86       *
87       * @return An instance of {@link ActionServletWrapper}
88       * @see ActionServletWrapper
89       * @since Struts 1.0.1
90       */
91      public ActionServletWrapper getServletWrapper() {
92          return new ActionServletWrapper(getServlet());
93      }
94  
95      /***
96       * <p>Return the <code>MultipartRequestHandler</code> for this form The
97       * reasoning behind this is to give form bean developers control over the
98       * lifecycle of their multipart requests through the use of the
99       * <code>finish</code> and/or <code>rollback</code> methods of
100      * <code>MultipartRequestHandler</code>.  This method will return
101      * <code>null</code> if this form's enctype is not "multipart/form-data".
102      * </p>
103      *
104      * @return The {@link org.apache.struts.upload.MultipartRequestHandler}
105      *         for this form.
106      * @see org.apache.struts.upload.MultipartRequestHandler
107      */
108     public MultipartRequestHandler getMultipartRequestHandler() {
109         return multipartRequestHandler;
110     }
111 
112     /***
113      * <p>Set the servlet instance to which we are attached (if
114      * <code>servlet</code> is non-null).</p>
115      *
116      * @param servlet The new controller servlet, if any
117      */
118     public void setServlet(ActionServlet servlet) {
119         this.servlet = servlet;
120 
121         // :FIXME: Should this be releasing resources?
122     }
123 
124     /***
125      * <p>Set the Handler provided for use in dealing with file uploads.</p>
126      *
127      * @param multipartRequestHandler The Handler to use for fileuploads.
128      */
129     public void setMultipartRequestHandler(
130         MultipartRequestHandler multipartRequestHandler) {
131         this.multipartRequestHandler = multipartRequestHandler;
132     }
133 
134     // --------------------------------------------------------- Public Methods
135 
136     /***
137      * <p>>Can be used to reset all bean properties to their default state.
138      * This method is called before the properties are repopulated by the
139      * controller.</p>
140      *
141      * <p>The default implementation attempts to forward to the HTTP version
142      * of this method.</p>
143      *
144      * @param mapping The mapping used to select this instance
145      * @param request The servlet request we are processing
146      */
147     public void reset(ActionMapping mapping, ServletRequest request) {
148         try {
149             reset(mapping, (HttpServletRequest) request);
150         } catch (ClassCastException e) {
151             ; // FIXME: Why would this ever happen except a null
152         }
153     }
154 
155     /***
156      * <p>Can be used to reset bean properties to their default state, as
157      * needed.  This method is called before the properties are repopulated by
158      * the controller.</p>
159      *
160      * <p>The default implementation does nothing. In practice, the only
161      * properties that need to be reset are those which represent checkboxes
162      * on a session-scoped form. Otherwise, properties can be given initial
163      * values where the field is declared. </p>
164      *
165      * <p>If the form is stored in session-scope so that values can be
166      * collected over multiple requests (a "wizard"), you must be very careful
167      * of which properties, if any, are reset. As mentioned, session-scope
168      * checkboxes must be reset to false for any page where this property is
169      * set. This is because the client does not submit a checkbox value when
170      * it is clear (false). If a session-scoped checkbox is not proactively
171      * reset, it can never be set to false.</p>
172      *
173      * <p>This method is <strong>not</strong> the appropriate place to
174      * initialize form value for an "update" type page (this should be done in
175      * a setup Action). You mainly need to worry about setting checkbox values
176      * to false; most of the time you can leave this method unimplemented.
177      * </p>
178      *
179      * @param mapping The mapping used to select this instance
180      * @param request The servlet request we are processing
181      */
182     public void reset(ActionMapping mapping, HttpServletRequest request) {
183         // Default implementation does nothing
184     }
185 
186     /***
187      * <p>Can be used to validate the properties that have been set for this
188      * non-HTTP request, and return an <code>ActionErrors</code> object that
189      * encapsulates any validation errors that have been found. If no errors
190      * are found, return <code>null</code> or an <code>ActionErrors</code>
191      * object with no recorded error messages.</p>
192      *
193      * <p>The default implementation attempts to forward to the HTTP version
194      * of this method.</p>
195      *
196      * @param mapping The mapping used to select this instance
197      * @param request The servlet request we are processing
198      * @return The set of validation errors, if validation failed; an empty
199      *         set or <code>null</code> if validation succeeded.
200      */
201     public ActionErrors validate(ActionMapping mapping, ServletRequest request) {
202         try {
203             return (validate(mapping, (HttpServletRequest) request));
204         } catch (ClassCastException e) {
205             return (null);
206         }
207     }
208 
209     /***
210      * <p>Can be used to validate the properties that have been set for this
211      * HTTP request, and return an <code>ActionErrors</code> object that
212      * encapsulates any validation errors that have been found. If no errors
213      * are found, return <code>null</code> or an <code>ActionErrors</code>
214      * object with no recorded error messages.</p>
215      *
216      * <p>The default implementation performs no validation and returns
217      * <code>null</code>. Subclasses must override this method to provide any
218      * validation they wish to perform.</p>
219      *
220      * @param mapping The mapping used to select this instance
221      * @param request The servlet request we are processing
222      * @return The set of validation errors, if validation failed; an empty
223      *         set or <code>null</code> if validation succeeded.
224      * @see DynaActionForm
225      */
226     public ActionErrors validate(ActionMapping mapping,
227         HttpServletRequest request) {
228         return (null);
229     }
230 }