1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
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
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
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
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 ;
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
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 }