Clover coverage report - Code Coverage for tapestry release 4.0-beta-2
Coverage timestamp: Sat Jul 9 2005 22:02:17 EDT
file stats: LOC: 274   Methods: 0
NCLOC: 30   Classes: 1
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 - - - -
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 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    }