Clover coverage report - Code Coverage for tapestry release 4.0-beta-6
Coverage timestamp: Wed Sep 7 2005 18:41:34 EDT
file stats: LOC: 313   Methods: 0
NCLOC: 33   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
IValidationDelegate.java - - - -
coverage
 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}&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
 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    * Records an error in the current component, or an unassociated error. The maximum flexibility
 187    * recorder.
 188    *
 189    * @param errorRenderer
 190    * object that will render the error message (@see RenderString}
 191    * @param constraint
 192    * the constraint that was violated, or null if not known
 193    */
 194   
 195    public void record(IRender errorRenderer, ValidationConstraint constraint);
 196   
 197    /**
 198    * Invoked before the field is rendered. If the field is in error, the delegate may decorate the
 199    * field in some way (to highlight its error state).
 200    *
 201    * @param writer
 202    * the writer to which output should be sent
 203    * @param cycle
 204    * the active request cycle
 205    * @param component
 206    * the component being decorated
 207    * @param validator
 208    * the validator for the component, or null if the component does have (or doesn't
 209    * support) a validator
 210    */
 211   
 212    public void writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component,
 213    IValidator validator);
 214   
 215    /**
 216    * Invoked just before the &lt;input&gt; element is closed. The delegate can write additional
 217    * attributes. This is often used to set the CSS class of the field so that it can be displayed
 218    * differently, if in error (or required). *
 219    *
 220    * @param writer
 221    * the writer to which output should be sent
 222    * @param cycle
 223    * the active request cycle
 224    * @param component
 225    * the component being decorated
 226    * @param validator
 227    * the validator for the component, or null if the component does have (or doesn't
 228    * support) a validator
 229    * @since 1.0.5
 230    */
 231   
 232    public void writeAttributes(IMarkupWriter writer, IRequestCycle cycle,
 233    IFormComponent component, IValidator validator);
 234   
 235    /**
 236    * Invoked after the form component is rendered, so that the delegate may decorate the form
 237    * component (if it is in error). *
 238    *
 239    * @param writer
 240    * the writer to which output should be sent
 241    * @param cycle
 242    * the active request cycle
 243    * @param component
 244    * the component being decorated
 245    * @param validator
 246    * the validator for the component, or null if the component does have (or doesn't
 247    * support) a validator
 248    */
 249   
 250    public void writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component,
 251    IValidator validator);
 252   
 253    /**
 254    * Invoked by a {@link FieldLabel} just before writing the name of the form component.
 255    */
 256   
 257    public void writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle);
 258   
 259    /**
 260    * Invoked by a {@link FieldLabel} just after writing the name of the form component.
 261    */
 262   
 263    public void writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle);
 264   
 265    /**
 266    * Returns true if any form component has errors.
 267    */
 268   
 269    public boolean getHasErrors();
 270   
 271    /**
 272    * Returns the {@link IFieldTracking}&nbsp;for the current component, if any. Useful when
 273    * displaying error messages for individual fields.
 274    *
 275    * @since 3.0.2
 276    */
 277    public IFieldTracking getCurrentFieldTracking();
 278   
 279    /**
 280    * Returns a list of {@link org.apache.tapestry.IRender} objects, each of which will render an
 281    * error message for a field tracked by the delegate, plus any unassociated errors (for which no
 282    * specific field is identified). These objects can be rendered or converted to a string (via
 283    * toString()).
 284    *
 285    * @return non-empty List of {@link org.apache.tapestry.IRender}.
 286    */
 287   
 288    public List getErrorRenderers();
 289   
 290    /**
 291    * Registers a field for automatic focus. The goal is for the first field that is in error to
 292    * get focus; failing that, the first required field; failing that, any field.
 293    *
 294    * @param field
 295    * the field requesting focus
 296    * @param priority
 297    * a priority level used to determine whether the registered field becomes the focus
 298    * field. Constants for this purpose are defined in {@link ValidationConstants}.
 299    * @since 4.0
 300    */
 301   
 302    public void registerForFocus(IFormComponent field, int priority);
 303   
 304    /**
 305    * Returns the field to focus upon, based on prior calls to
 306    * {@link #registerForFocus(IFormComponent, int)}.
 307    *
 308    * @return the field name, or null if no field should receive focus.
 309    * @since 4.0
 310    */
 311    public String getFocusField();
 312   
 313    }