ActionForm


1   /*
2    * $Id: ActionForm.java 54929 2004-10-16 16:38:42Z germuska $ 
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  
19  
20  package org.apache.struts.action;
21  
22  
23  import java.io.Serializable  ;
24  import javax.servlet.ServletRequest  ;
25  import javax.servlet.http.HttpServletRequest  ;
26  
27  import org.apache.struts.upload.MultipartRequestHandler;
28  
29  
30  /**
31   * <p>An <strong>ActionForm</strong> is a JavaBean optionally associated with
32   * one or more <code>ActionMappings</code>. Such a bean will have had its
33   * properties initialized from the corresponding request parameters before
34   * the corresponding <code>Action.execute</code> method is called.</p>
35   *
36   * <p>When the properties of this bean have been populated, but before the
37   * <code>execute</code> method of the <code>Action</code> is called, this bean's
38   * <code>validate</code> method will be called, which gives the bean a chance
39   * to verify that the properties submitted by the user are correct and valid.
40   * If this method finds problems, it returns an error messages object that
41   * encapsulates those problems, and the controller servlet will return control
42   * to the corresponding input form. Otherwise, the <code>validate</code>
43   * method returns <code>null</code>, indicating that everything is acceptable
44   * and the corresponding <code>Action.execute</code> method should be
45   * called.</p>
46   *
47   * <p>This class must be subclassed in order to be instantiated. Subclasses
48   * should provide property getter and setter methods for all of the bean
49   * properties they wish to expose, plus override any of the public or
50   * protected methods for which they wish to provide modified functionality.
51   * </p>
52   *
53   * <p>Because ActionForms are JavaBeans, subclasses should also implement
54   * <code>Serializable</code>, as required by the JavaBean specification.
55   * Some containers require that an object meet all JavaBean requirements
56   * in order to use the introspection API upon which ActionForms rely.</p>
57   *
58   * @version $Rev: 54929 $ $Date: 2004-10-16 17:38:42 +0100 (Sat, 16 Oct 2004) $
59   */
60  
61  public abstract class ActionForm implements Serializable   {
62  
63  
64      // ----------------------------------------------------- Instance Variables
65  
66  
67      /**
68       * <p>The servlet instance to which we are attached.</p>
69       */
70      protected transient ActionServlet servlet = null;
71  
72  
73      /**
74       * <p>The MultipartRequestHandler for this form, can be
75       * <code>null</code>.</p>
76       */
77      protected transient MultipartRequestHandler multipartRequestHandler;
78  
79  
80      // ------------------------------------------------------------- Properties
81  
82  
83      /**
84       * <p>Return the servlet instance to which we are attached.</p>
85       */
86      protected ActionServlet getServlet() {
87  
88          return (this.servlet);
89  
90      }
91  
92  
93      /**
94       * <p>Return the controller servlet instance to which we are attached.
95       * as an <code>ActionServletWrapper</code>.</p>
96       *
97       * @see org.apache.struts.action.ActionServletWrapper
98       * @since Struts 1.0.1
99       */
100     public ActionServletWrapper getServletWrapper() {
101 
102         return new ActionServletWrapper(getServlet());
103 
104     }
105 
106 
107     /**
108      * <p>Return the <code>MultipartRequestHandler</code> for this form
109      * The reasoning behind this is to give form bean developers
110      * control over the lifecycle of their multipart requests
111      * through the use of the <code>finish</code> and/or <code>rollback</code>
112      * methods of <code>MultipartRequestHandler</code>.  This method will return
113      * <code>null</code> if this form's enctype is not
114      * "multipart/request-data".</p>
115      *
116      * @see org.apache.struts.upload.MultipartRequestHandler
117      */
118     public MultipartRequestHandler getMultipartRequestHandler() {
119         return multipartRequestHandler;
120     }
121 
122 
123     /**
124      * <p>Set the servlet instance to which we are attached (if
125      * <code>servlet</code> is non-null), or release any allocated resources
126      * (if <code>servlet</code> is null).</p>
127      *
128      * @param servlet The new controller servlet, if any
129      */
130     public void setServlet(ActionServlet servlet) {
131 
132         this.servlet = servlet;
133             // :FIXME: Should this be releasing resources?
134 
135     }
136 
137 
138     /**
139      * <p>Set the Handler provides to use in dealing with file uploads.</p>
140      *
141      * @param multipartRequestHandler The Handler to use for fileuploads.
142      */
143     public void setMultipartRequestHandler(MultipartRequestHandler multipartRequestHandler) {
144 
145         this.multipartRequestHandler = multipartRequestHandler;
146 
147     }
148 
149     // --------------------------------------------------------- Public Methods
150 
151 
152     /**
153      * <p>Reset all bean properties to their default state.  This method is
154      * called before the properties are repopulated by the controller.</p>
155      *
156      * <p>The default implementation attempts to forward to the HTTP
157      * version of this method.</p>
158      *
159      * @param mapping The mapping used to select this instance
160      * @param request The servlet request we are processing
161      */
162     public void reset(ActionMapping mapping, ServletRequest   request) {
163 
164         try {
165             reset(mapping, (HttpServletRequest  ) request);
166         } catch (ClassCastException   e) {
167             ;//FFIXME: Why would this every happen except a null
168         }
169 
170     }
171 
172 
173     /**
174      * <p>Reset bean properties to their default state, as needed.  This method is
175      * called before the properties are repopulated by the controller.</p>
176      *
177      * <p>The default implementation does nothing. In practice, the only properties
178      * that need to be reset are those which represent checkboxes on a session-scoped
179      * form. Otherwise, properties can be given initial values where the field is
180      * declared. </p>
181      *
182      * <p>If the form is stored in session-scope so that values can be collected
183      * over multiple requests (a "wizard"), you must be very careful of which
184      * properties, if any, are reset. As mentioned, session-scope checkboxes
185      * must be reset to false for any page where this property is set. This is
186      * because the client does not submit a checkbox value when it is clear (false).
187      * If a session-scoped checkbox is not proactively reset, it can never be set
188      * to false.</p>
189      *
190      * <p>This method is <strong>not</strong> the appropriate place to initialize
191      * form value for an "update" type page (this should be done in a setup Action).
192      * You mainly need to worry about setting checkbox values to false; most of the
193      * time you can leave this method unimplemented.
194      * </p>
195      *
196      * @param mapping The mapping used to select this instance
197      * @param request The servlet request we are processing
198      */
199     public void reset(ActionMapping mapping, HttpServletRequest   request) {
200 
201         ;       // Default implementation does nothing
202 
203     }
204 
205 
206     /**
207      * <p>Validate the properties that have been set for this non-HTTP request,
208      * and return an <code>ActionErrors</code> object that encapsulates any
209      * validation errors that have been found. If no errors are found, return
210      * <code>null</code> or an <code>ActionErrors</code> object with no
211      * recorded error messages.</p>
212      *
213      * <p>The default implementation attempts to forward to the HTTP version of
214      * this method.</p>
215      *
216      * @param mapping The mapping used to select this instance
217      * @param request The servlet request we are processing
218      */
219     public ActionErrors validate(ActionMapping mapping,
220                                  ServletRequest   request) {
221 
222         try {
223             return (validate(mapping, (HttpServletRequest  ) request));
224         } catch (ClassCastException   e) {
225             return (null);
226         }
227 
228     }
229 
230 
231     /**
232      * <p>Validate the properties that have been set for this HTTP request,
233      * and return an <code>ActionErrors</code> object that encapsulates any
234      * validation errors that have been found. If no errors are found,
235      * return <code>null</code> or an <code>ActionErrors</code> object with
236      * no recorded error messages.</p>
237      *
238      * <p>The default implementation performs no validation and returns
239      * <code>null</code>. Subclasses must override this method to provide
240      * any validation they wish to perform.</p>
241      *
242      * @see DynaActionForm
243      *
244      * @param mapping The mapping used to select this instance
245      * @param request The servlet request we are processing
246      */
247     public ActionErrors validate(ActionMapping mapping,
248                                  HttpServletRequest   request) {
249 
250         return (null);
251 
252     }
253 
254 
255 }
256
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags