Clover coverage report - Code Coverage for tapestry release 4.0-alpha-3
Coverage timestamp: Mon May 16 2005 09:05:49 EDT
file stats: LOC: 236   Methods: 0
NCLOC: 29   Classes: 1
30 day Evaluation Version distributed via the Maven Jar Repository. Clover is not free. You have 30 days to evaluate it. Please visit http://www.thecortex.net/clover 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.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 (which
 84   
      * is almost always a {@link ValidField}).
 85   
      * <p>
 86   
      * The caller should invoke this with a parameter of null to record unassociated global errors
 87   
      * (errors not associated with any particular field).
 88   
      * 
 89   
      * @since 1.0.8
 90   
      */
 91   
 
 92   
     public void setFormComponent(IFormComponent component);
 93   
 
 94   
     /**
 95   
      * Returns true if the current component is in error (that is, had bad input submitted by the
 96   
      * end user).
 97   
      * 
 98   
      * @since 1.0.8
 99   
      */
 100   
 
 101   
     public boolean isInError();
 102   
 
 103   
     /**
 104   
      * Returns the string submitted by the client as the value for the current field.
 105   
      * 
 106   
      * @since 1.0.8
 107   
      */
 108   
 
 109   
     public String getFieldInputValue();
 110   
 
 111   
     /**
 112   
      * Returns a {@link List}of {@link IFieldTracking}, in default order (the order in which
 113   
      * fields are renderred). A caller should not change the values (the List is immutable). May
 114   
      * return null if no fields are in error.
 115   
      * 
 116   
      * @since 1.0.8
 117   
      */
 118   
 
 119   
     public List getFieldTracking();
 120   
 
 121   
     /**
 122   
      * Resets any tracking information for the current field. This will clear the field's inError
 123   
      * flag, and set its error message and invalid input value to null.
 124   
      * 
 125   
      * @since 1.0.8
 126   
      */
 127   
 
 128   
     public void reset();
 129   
 
 130   
     /**
 131   
      * Clears all tracking information.
 132   
      * 
 133   
      * @since 1.0.10
 134   
      */
 135   
 
 136   
     public void clear();
 137   
 
 138   
     /**
 139   
      * Records the user's input for the current form component. Input should be recorded even if
 140   
      * there isn't an explicit error, since later form-wide validations may discover an error in the
 141   
      * field.
 142   
      * 
 143   
      * @since 3.0
 144   
      */
 145   
 
 146   
     public void recordFieldInputValue(String input);
 147   
 
 148   
     /**
 149   
      * The error notification method, invoked during the rewind phase (that is, while HTTP
 150   
      * parameters are being extracted from the request and assigned to various object properties).
 151   
      * <p>
 152   
      * Typically, the delegate simply invokes {@link #record(String, ValidationConstraint)}or
 153   
      * {@link #record(IRender, ValidationConstraint)}, but special delegates may override this
 154   
      * behavior to provide (in some cases) different error messages or more complicated error
 155   
      * renderers.
 156   
      */
 157   
 
 158   
     public void record(ValidatorException ex);
 159   
 
 160   
     /**
 161   
      * Records an error in the current field, or an unassociated error if there is no current field.
 162   
      * 
 163   
      * @param message
 164   
      *            message to display (@see RenderString}
 165   
      * @param constraint
 166   
      *            the constraint that was violated, or null if not known
 167   
      * @since 1.0.9
 168   
      */
 169   
 
 170   
     public void record(String message, ValidationConstraint constraint);
 171   
 
 172   
     /**
 173   
      * Records an error in the current component, or an unassociated error. The maximum flexibility
 174   
      * recorder.
 175   
      * 
 176   
      * @param errorRenderer
 177   
      *            object that will render the error message (@see RenderString}
 178   
      * @param constraint
 179   
      *            the constraint that was violated, or null if not known
 180   
      */
 181   
 
 182   
     public void record(IRender errorRenderer, ValidationConstraint constraint);
 183   
 
 184   
     /**
 185   
      * Invoked before the field is rendered. If the field is in error, the delegate may decorate the
 186   
      * field in some way (to highlight its error state).
 187   
      */
 188   
 
 189   
     public void writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component,
 190   
             IValidator validator);
 191   
 
 192   
     /**
 193   
      * Invoked just before the &lt;input&gt; element is closed. The delegate can write additional
 194   
      * attributes. This is often used to set the CSS class of the field so that it can be displayed
 195   
      * differently, if in error (or required).
 196   
      * 
 197   
      * @since 1.0.5
 198   
      */
 199   
 
 200   
     public void writeAttributes(IMarkupWriter writer, IRequestCycle cycle,
 201   
             IFormComponent component, IValidator validator);
 202   
 
 203   
     /**
 204   
      * Invoked after the form component is rendered, so that the delegate may decorate the form
 205   
      * component (if it is in error).
 206   
      */
 207   
 
 208   
     public void writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component,
 209   
             IValidator validator);
 210   
 
 211   
     /**
 212   
      * Invoked by a {@link FieldLabel}just before writing the name of the form component.
 213   
      */
 214   
 
 215   
     public void writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle);
 216   
 
 217   
     /**
 218   
      * Invoked by a {@link FieldLabel}just after writing the name of the form component.
 219   
      */
 220   
 
 221   
     public void writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle);
 222   
 
 223   
     /**
 224   
      * Returns true if any form component has errors.
 225   
      */
 226   
 
 227   
     public boolean getHasErrors();
 228   
 
 229   
     /**
 230   
      * Returns the {@link IFieldTracking}&nbsp;for the current component, if any. Useful when
 231   
      * displaying error messages for individual fields.
 232   
      * 
 233   
      * @since 3.0.2
 234   
      */
 235   
     public IFieldTracking getCurrentFieldTracking();
 236   
 }