|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
IValidationDelegate.java | - | - | - | - |
|
1 | // Copyright 2004, 2005 The Apache Software Foundation | |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 | // you may not use this file except in compliance with the License. | |
5 | // You may obtain a copy of the License at | |
6 | // | |
7 | // http://www.apache.org/licenses/LICENSE-2.0 | |
8 | // | |
9 | // Unless required by applicable law or agreed to in writing, software | |
10 | // distributed under the License is distributed on an "AS IS" BASIS, | |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 | // See the License for the specific language governing permissions and | |
13 | // limitations under the License. | |
14 | ||
15 | package org.apache.tapestry.valid; | |
16 | ||
17 | import java.io.Serializable; | |
18 | import java.util.List; | |
19 | ||
20 | import org.apache.tapestry.IMarkupWriter; | |
21 | import org.apache.tapestry.IRender; | |
22 | import org.apache.tapestry.IRequestCycle; | |
23 | import org.apache.tapestry.form.IFormComponent; | |
24 | ||
25 | /** | |
26 | * Interface used to track validation errors in forms and | |
27 | * {@link IFormComponent form element component}s (including | |
28 | * {@link org.apache.tapestry.form.AbstractTextField} and its subclasses). | |
29 | * <p> | |
30 | * In addition, controls how fields that are in error are presented (they can be <em>decorated</em> | |
31 | * in various ways by the delegate; the default implementation adds two red asterisks to the right | |
32 | * of the field). | |
33 | * <p> | |
34 | * Each {@link org.apache.tapestry.form.Form} must have its own validation delegate instance. | |
35 | * <p> | |
36 | * Starting with release 1.0.8, this interface was extensively revised (in a non-backwards | |
37 | * compatible way) to move the tracking of errors and invalid values (during a request cycle) to the | |
38 | * delegate. It has evolved from a largely stateless conduit for error messages into a very stateful | |
39 | * tracker of field state. | |
40 | * <p> | |
41 | * Starting with release 1.0.9, this interface was <em>again</em> reworked, to allow tracking of | |
42 | * errors in {@link IFormComponent form components}, and to allow unassociated errors to be | |
43 | * tracked. Unassociated errors are "global", they don't apply to any particular field. | |
44 | * <p> | |
45 | * <b>Fields vs. Form Element Components </b> <br> | |
46 | * For most simple forms, these terms are pretty much synonymous. Your form will render normally, | |
47 | * and each form element component will render only once. Some of your form components will be | |
48 | * {@link ValidField} components and handle most of their validation internally (with the help | |
49 | * of {@link IValidator} objects). In addition, your form listener may do additional | |
50 | * validation and notify the validation delegate of additional errors, some of which are associated | |
51 | * with a particular field, some of which are unassociated with any particular field. | |
52 | * <p> | |
53 | * But what happens if you use a {@link org.apache.tapestry.components.Foreach} or | |
54 | * {@link org.apache.tapestry.form.ListEdit} inside your form? Some of your components will | |
55 | * render multiple times. In this case you will have multiple <em>fields</em>. Each field will | |
56 | * have a unique field name (the | |
57 | * {@link org.apache.tapestry.form.FormSupport#getElementId(IFormComponent) element id}, which you | |
58 | * can see this in the generated HTML). It is this field name that the delegate keys off of, which | |
59 | * means that some fields generated by a component may have errors and some may not, it all works | |
60 | * fine (with one exception). | |
61 | * <p> | |
62 | * <b>The Exception </b> <br> | |
63 | * The problem is that a component doesn't know its field name until its <code>render()</code> | |
64 | * method is invoked (at which point, it allocates a unique field name from the | |
65 | * {@link org.apache.tapestry.IForm#getElementId(org.apache.tapestry.form.IFormComponent)}. This is | |
66 | * not a problem for the field or its {@link IValidator}, but screws things up for the | |
67 | * {@link FieldLabel}. | |
68 | * <p> | |
69 | * Typically, the label is rendered <em>before</em> the corresponding form component. Form | |
70 | * components leave their last assigned field name in their | |
71 | * {@link IFormComponent#getName() name property}. So if the form component is in any kind of loop, | |
72 | * the {@link FieldLabel}will key its name, {@link IFormComponent#getDisplayName() display name} | |
73 | * and error status off of its last renderred value. So the moral of the story is don't use | |
74 | * {@link FieldLabel}in this situation. | |
75 | * | |
76 | * @author Howard Lewis Ship | |
77 | */ | |
78 | ||
79 | public interface IValidationDelegate extends Serializable | |
80 | { | |
81 | /** | |
82 | * Invoked before other methods to configure the delegate for the given form component. Sets the | |
83 | * current field based on the {@link IFormComponent#getName() name} of the form component. | |
84 | * <p> | |
85 | * The caller should invoke this with a parameter of null to record unassociated global errors | |
86 | * (errors not associated with any particular field). | |
87 | * | |
88 | * @since 1.0.8 | |
89 | */ | |
90 | ||
91 | public void setFormComponent(IFormComponent component); | |
92 | ||
93 | /** | |
94 | * Returns true if the current field is in error (that is, had bad input submitted by the end | |
95 | * user). | |
96 | * | |
97 | * @since 1.0.8 | |
98 | */ | |
99 | ||
100 | public boolean isInError(); | |
101 | ||
102 | /** | |
103 | * Returns the string submitted by the client as the value for the current field. | |
104 | * | |
105 | * @since 1.0.8 | |
106 | */ | |
107 | ||
108 | public String getFieldInputValue(); | |
109 | ||
110 | /** | |
111 | * Returns a {@link List} of {@link IFieldTracking}, in default order (the order in which | |
112 | * fields are renderred). A caller should not change the values (the List is immutable). May | |
113 | * return null if no fields are in error. | |
114 | * | |
115 | * @since 1.0.8 | |
116 | */ | |
117 | ||
118 | public List getFieldTracking(); | |
119 | ||
120 | /** | |
121 | * Resets any tracking information for the current field. This will clear the field's inError | |
122 | * flag, and set its error message and invalid input value to null. | |
123 | * | |
124 | * @since 1.0.8 | |
125 | */ | |
126 | ||
127 | public void reset(); | |
128 | ||
129 | /** | |
130 | * Clears all tracking information. | |
131 | * | |
132 | * @since 1.0.10 | |
133 | */ | |
134 | ||
135 | public void clear(); | |
136 | ||
137 | /** | |
138 | * Clears all errors, but maintains user input. This is useful when a form has been submitted | |
139 | * for a semantic other than "process this data". A common example of this is a dependent drop | |
140 | * down list; selecting an option in one drop down list forces a refresh submit of the form, to | |
141 | * repopulate the options in a second, dependent drop down list. | |
142 | * <p> | |
143 | * In these cases, the user input provided in the request is maintained, but any errors should | |
144 | * be cleared out (to prevent unwanted error messages and decorations). | |
145 | * | |
146 | * @since 3.0.1 | |
147 | */ | |
148 | ||
149 | public void clearErrors(); | |
150 | ||
151 | /** | |
152 | * Records the user's input for the current form component. Input should be recorded even if | |
153 | * there isn't an explicit error, since later form-wide validations may discover an error in the | |
154 | * field. | |
155 | * | |
156 | * @since 3.0 | |
157 | */ | |
158 | ||
159 | public void recordFieldInputValue(String input); | |
160 | ||
161 | /** | |
162 | * The error notification method, invoked during the rewind phase (that is, while HTTP | |
163 | * parameters are being extracted from the request and assigned to various object properties). | |
164 | * <p> | |
165 | * Typically, the delegate simply invokes {@link #record(String, ValidationConstraint)}or | |
166 | * {@link #record(IRender, ValidationConstraint)}, but special delegates may override this | |
167 | * behavior to provide (in some cases) different error messages or more complicated error | |
168 | * renderers. | |
169 | */ | |
170 | ||
171 | public void record(ValidatorException ex); | |
172 | ||
173 | /** | |
174 | * Records an error in the current field, or an unassociated error if there is no current field. | |
175 | * | |
176 | * @param message | |
177 | * message to display (@see RenderString} | |
178 | * @param constraint | |
179 | * the constraint that was violated, or null if not known | |
180 | * @since 1.0.9 | |
181 | */ | |
182 | ||
183 | public void record(String message, ValidationConstraint constraint); | |
184 | ||
185 | /** | |
186 | * Convienience for recording a standard string messages against a field. | |
187 | * | |
188 | * @param field | |
189 | * the field to record the error message against, or null to record an unassociated | |
190 | * error | |
191 | * @param message | |
192 | * the error message to record | |
193 | * @since 4.0 | |
194 | */ | |
195 | ||
196 | public void record(IFormComponent field, String message); | |
197 | ||
198 | /** | |
199 | * Records an error in the current component, or an unassociated error. The maximum flexibility | |
200 | * recorder. | |
201 | * | |
202 | * @param errorRenderer | |
203 | * object that will render the error message (@see RenderString} | |
204 | * @param constraint | |
205 | * the constraint that was violated, or null if not known | |
206 | */ | |
207 | ||
208 | public void record(IRender errorRenderer, ValidationConstraint constraint); | |
209 | ||
210 | /** | |
211 | * Invoked before the field is rendered. If the field is in error, the delegate may decorate the | |
212 | * field in some way (to highlight its error state). | |
213 | * | |
214 | * @param writer | |
215 | * the writer to which output should be sent | |
216 | * @param cycle | |
217 | * the active request cycle | |
218 | * @param component | |
219 | * the component being decorated | |
220 | * @param validator | |
221 | * the validator for the component, or null if the component does have (or doesn't | |
222 | * support) a validator | |
223 | */ | |
224 | ||
225 | public void writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, | |
226 | IValidator validator); | |
227 | ||
228 | /** | |
229 | * Invoked just before the <input> element is closed. The delegate can write additional | |
230 | * attributes. This is often used to set the CSS class of the field so that it can be displayed | |
231 | * differently, if in error (or required). * | |
232 | * | |
233 | * @param writer | |
234 | * the writer to which output should be sent | |
235 | * @param cycle | |
236 | * the active request cycle | |
237 | * @param component | |
238 | * the component being decorated | |
239 | * @param validator | |
240 | * the validator for the component, or null if the component does have (or doesn't | |
241 | * support) a validator | |
242 | * @since 1.0.5 | |
243 | */ | |
244 | ||
245 | public void writeAttributes(IMarkupWriter writer, IRequestCycle cycle, | |
246 | IFormComponent component, IValidator validator); | |
247 | ||
248 | /** | |
249 | * Invoked after the form component is rendered, so that the delegate may decorate the form | |
250 | * component (if it is in error). * | |
251 | * | |
252 | * @param writer | |
253 | * the writer to which output should be sent | |
254 | * @param cycle | |
255 | * the active request cycle | |
256 | * @param component | |
257 | * the component being decorated | |
258 | * @param validator | |
259 | * the validator for the component, or null if the component does have (or doesn't | |
260 | * support) a validator | |
261 | */ | |
262 | ||
263 | public void writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, | |
264 | IValidator validator); | |
265 | ||
266 | /** | |
267 | * Invoked by a {@link FieldLabel} just before writing the name of the form component. | |
268 | */ | |
269 | ||
270 | public void writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle); | |
271 | ||
272 | /** | |
273 | * Invoked just before the <label> element is closed. The delegate can write additional | |
274 | * attributes. This is often used to set the CSS class of the label so that it can be displayed | |
275 | * differently, if in error (or required). Any attributes written here will be overriden by any | |
276 | * informal parameters specified in the {@link FieldLabel} implementation. | |
277 | * | |
278 | * @param writer | |
279 | * the writer to which output should be sent | |
280 | * @param cycle | |
281 | * the active request cycle | |
282 | * @param component | |
283 | * the component field that label decorates | |
284 | * @since 4.0.1 | |
285 | */ | |
286 | ||
287 | public void writeLabelAttributes(IMarkupWriter writer, IRequestCycle cycle, | |
288 | IFormComponent component); | |
289 | ||
290 | /** | |
291 | * Invoked by a {@link FieldLabel} just after writing the name of the form component. | |
292 | */ | |
293 | ||
294 | public void writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle); | |
295 | ||
296 | /** | |
297 | * Returns true if any form component has errors. | |
298 | */ | |
299 | ||
300 | public boolean getHasErrors(); | |
301 | ||
302 | /** | |
303 | * Returns the {@link IFieldTracking} for the current component, if any. Useful when | |
304 | * displaying error messages for individual fields. | |
305 | * | |
306 | * @since 3.0.2 | |
307 | */ | |
308 | public IFieldTracking getCurrentFieldTracking(); | |
309 | ||
310 | /** | |
311 | * Returns a list of {@link org.apache.tapestry.IRender} objects, each of which will render an | |
312 | * error message for a field tracked by the delegate, plus any unassociated errors (for which no | |
313 | * specific field is identified). These objects can be rendered or converted to a string (via | |
314 | * toString()). | |
315 | * | |
316 | * @return non-empty List of {@link org.apache.tapestry.IRender}. | |
317 | */ | |
318 | ||
319 | public List getErrorRenderers(); | |
320 | ||
321 | /** | |
322 | * Registers a field for automatic focus. The goal is for the first field that is in error to | |
323 | * get focus; failing that, the first required field; failing that, any field. | |
324 | * | |
325 | * @param field | |
326 | * the field requesting focus | |
327 | * @param priority | |
328 | * a priority level used to determine whether the registered field becomes the focus | |
329 | * field. Constants for this purpose are defined in {@link ValidationConstants}. | |
330 | * @since 4.0 | |
331 | */ | |
332 | ||
333 | public void registerForFocus(IFormComponent field, int priority); | |
334 | ||
335 | /** | |
336 | * Returns the field to focus upon, based on prior calls to | |
337 | * {@link #registerForFocus(IFormComponent, int)}. | |
338 | * | |
339 | * @return the field name, or null if no field should receive focus. | |
340 | * @since 4.0 | |
341 | */ | |
342 | public String getFocusField(); | |
343 | ||
344 | } |
|