|
|||||||||||||||||||
30 day Evaluation License registered to hlship@comcast.net Your 30 day evaluation period has expired. Please visit http://www.cenqua.com to obtain a licensed version of Clover | |||||||||||||||||||
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 can | |
58 | * see this in the generated HTML). It is this field name that the delegate keys off of, which means | |
59 | * that some fields generated by a component may have errors and some may not, it all works fine | |
60 | * (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 | * Records the user's input for the current form component. Input should be recorded even if | |
139 | * there isn't an explicit error, since later form-wide validations may discover an error in the | |
140 | * field. | |
141 | * | |
142 | * @since 3.0 | |
143 | */ | |
144 | ||
145 | public void recordFieldInputValue(String input); | |
146 | ||
147 | /** | |
148 | * The error notification method, invoked during the rewind phase (that is, while HTTP | |
149 | * parameters are being extracted from the request and assigned to various object properties). | |
150 | * <p> | |
151 | * Typically, the delegate simply invokes {@link #record(String, ValidationConstraint)}or | |
152 | * {@link #record(IRender, ValidationConstraint)}, but special delegates may override this | |
153 | * behavior to provide (in some cases) different error messages or more complicated error | |
154 | * renderers. | |
155 | */ | |
156 | ||
157 | public void record(ValidatorException ex); | |
158 | ||
159 | /** | |
160 | * Records an error in the current field, or an unassociated error if there is no current field. | |
161 | * | |
162 | * @param message | |
163 | * message to display (@see RenderString} | |
164 | * @param constraint | |
165 | * the constraint that was violated, or null if not known | |
166 | * @since 1.0.9 | |
167 | */ | |
168 | ||
169 | public void record(String message, ValidationConstraint constraint); | |
170 | ||
171 | /** | |
172 | * Records an error in the current component, or an unassociated error. The maximum flexibility | |
173 | * recorder. | |
174 | * | |
175 | * @param errorRenderer | |
176 | * object that will render the error message (@see RenderString} | |
177 | * @param constraint | |
178 | * the constraint that was violated, or null if not known | |
179 | */ | |
180 | ||
181 | public void record(IRender errorRenderer, ValidationConstraint constraint); | |
182 | ||
183 | /** | |
184 | * Invoked before the field is rendered. If the field is in error, the delegate may decorate the | |
185 | * field in some way (to highlight its error state). | |
186 | * | |
187 | * @param writer | |
188 | * the writer to which output should be sent | |
189 | * @param cycle | |
190 | * the active request cycle | |
191 | * @param component | |
192 | * the component being decorated | |
193 | * @param validator | |
194 | * the validator for the component, or null if the component does have (or doesn't | |
195 | * support) a validator | |
196 | */ | |
197 | ||
198 | public void writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, | |
199 | IValidator validator); | |
200 | ||
201 | /** | |
202 | * Invoked just before the <input> element is closed. The delegate can write additional | |
203 | * attributes. This is often used to set the CSS class of the field so that it can be displayed | |
204 | * differently, if in error (or required). * | |
205 | * | |
206 | * @param writer | |
207 | * the writer to which output should be sent | |
208 | * @param cycle | |
209 | * the active request cycle | |
210 | * @param component | |
211 | * the component being decorated | |
212 | * @param validator | |
213 | * the validator for the component, or null if the component does have (or doesn't | |
214 | * support) a validator | |
215 | * @since 1.0.5 | |
216 | */ | |
217 | ||
218 | public void writeAttributes(IMarkupWriter writer, IRequestCycle cycle, | |
219 | IFormComponent component, IValidator validator); | |
220 | ||
221 | /** | |
222 | * Invoked after the form component is rendered, so that the delegate may decorate the form | |
223 | * component (if it is in error). * | |
224 | * | |
225 | * @param writer | |
226 | * the writer to which output should be sent | |
227 | * @param cycle | |
228 | * the active request cycle | |
229 | * @param component | |
230 | * the component being decorated | |
231 | * @param validator | |
232 | * the validator for the component, or null if the component does have (or doesn't | |
233 | * support) a validator | |
234 | */ | |
235 | ||
236 | public void writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, | |
237 | IValidator validator); | |
238 | ||
239 | /** | |
240 | * Invoked by a {@link FieldLabel} just before writing the name of the form component. | |
241 | */ | |
242 | ||
243 | public void writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle); | |
244 | ||
245 | /** | |
246 | * Invoked by a {@link FieldLabel} just after writing the name of the form component. | |
247 | */ | |
248 | ||
249 | public void writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle); | |
250 | ||
251 | /** | |
252 | * Returns true if any form component has errors. | |
253 | */ | |
254 | ||
255 | public boolean getHasErrors(); | |
256 | ||
257 | /** | |
258 | * Returns the {@link IFieldTracking} for the current component, if any. Useful when | |
259 | * displaying error messages for individual fields. | |
260 | * | |
261 | * @since 3.0.2 | |
262 | */ | |
263 | public IFieldTracking getCurrentFieldTracking(); | |
264 | ||
265 | /** | |
266 | * Returns a list of {@link org.apache.tapestry.IRender} objects, each of which will render on | |
267 | * error message for a field tracked by the delegate, plus any unassociated (with any field) | |
268 | * errors. These objects can be rendered or converted to a string (via toString()). | |
269 | * | |
270 | * @return non-empty List of {@link org.apache.tapestry.IRender}. | |
271 | */ | |
272 | ||
273 | public List getErrorRenderers(); | |
274 | } |
|