Source code: org/apache/struts/action/ActionForm.java
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 09:38:42 -0700 (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 }