IValidationDelegate


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}&nbsp;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}&nbsp;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}&nbsp;components and handle most of their validation internally (with the help
49   * of {@link IValidator}&nbsp;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}&nbsp;or
54   * {@link org.apache.tapestry.form.ListEdit}&nbsp;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 &lt;input&gt; 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}&nbsp;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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags