Clover coverage report - Code Coverage for tapestry release 3.1-alpha-1
Coverage timestamp: Mon Feb 21 2005 09:16:14 EST
file stats: LOC: 273   Methods: 0
NCLOC: 42   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.util.List;
 18   
 
 19   
 import org.apache.tapestry.IMarkupWriter;
 20   
 import org.apache.tapestry.IRender;
 21   
 import org.apache.tapestry.IRequestCycle;
 22   
 import org.apache.tapestry.form.IFormComponent;
 23   
 
 24   
 /**
 25   
  *  Interface used to track validation errors in forms and
 26   
  *  {@link IFormComponent}s (including {@link org.apache.tapestry.form.AbstractTextField}
 27   
  *  and its subclasses).
 28   
  *
 29   
  *  <p>In addition,
 30   
  *  controls how fields that are in error are presented (they can be
 31   
  *  marked in various ways by the delegate; the default implementation
 32   
  *  adds two red asterisks to the right of the field).
 33   
  *
 34   
  *  <p>The interface is designed so that a single instance can be shared
 35   
  *  with many instances of {@link IFormComponent}.
 36   
  *
 37   
  *  <p>Starting with release 1.0.8, this interface was extensively revised
 38   
  *  (in a non-backwards compatible way) to move the tracking of errors and
 39   
  *  invalid values (during a request cycle) to the delegate.  It has evolved from
 40   
  *  a largely stateless conduit for error messages into a very stateful tracker
 41   
  *  of field state.
 42   
  *
 43   
  *  <p>Starting with release 1.0.9, this interface was <em>again</em>
 44   
  *  reworked, to allow tracking of errors in {@link IFormComponent form components},
 45   
  *  and to allow unassociated (with any field) errors
 46   
  *  to be tracked.
 47   
  *
 48   
  *  <p><b>Fields vs. Form Components</b><br>
 49   
  *  For most simple forms, these terms are pretty much synonymous.
 50   
  *  Your form will render normally, and each form component will render
 51   
  *  only once.  Some of your form components will be {@link ValidField}
 52   
  *  components and handle most of
 53   
  *  their validation internally (with the help of {@link IValidator} objects).
 54   
  *  In addition, your form listener may do additional validation and notify
 55   
  *  the validation delegate of additional errors, some of which
 56   
  *  are associated with a particular field, some of which are unassociated
 57   
  *  with any particular field.
 58   
  * 
 59   
  *  <p>
 60   
  *  But what happens if you use a {@link org.apache.tapestry.components.Foreach} or
 61   
  *  {@link org.apache.tapestry.form.ListEdit} inside your form?
 62   
  *  Some of your components will render multiple times.  In this case you will have
 63   
  *  multiple <em>fields</em>.  Each field will have a unique field name (you can see this
 64   
  *  in the generated HTML).  It is this field name that the delegate keys off of, which
 65   
  *  means that some fields generated by a component may have errors and some may not, it
 66   
  *  all works fine (with one exception).
 67   
  *
 68   
  *  <p><b>The Exception</b><br>
 69   
  *  The problem is that a component doesn't know its field name until its
 70   
  *  <code>render()</code> method is invoked (at which point, it allocates a unique field
 71   
  *  name from the {@link org.apache.tapestry.IForm#getElementId(org.apache.tapestry.form.IFormComponent)}.
 72   
  *  This is not a problem for the field or its
 73   
  *  {@link IValidator}, but screws things up for the {@link FieldLabel}.
 74   
  *
 75   
  *  <p>Typically, the label is rendered <em>before</em> the corresponding form component.
 76   
  *  Form components leave their last assigned field name in their
 77   
  *  {@link IFormComponent#getName() name property}.  So if the form component is in any kind of
 78   
  *  loop, the {@link FieldLabel} will key its name,
 79   
  *  {@link IFormComponent#getDisplayName() display name} and error status off of
 80   
  *  its last renderred value.  So the moral of the story is don't use
 81   
  *  {@link FieldLabel} in this situation.
 82   
  *
 83   
  *
 84   
  *  @author Howard Lewis Ship
 85   
  *
 86   
  **/
 87   
 
 88   
 public interface IValidationDelegate
 89   
 {
 90   
     /**
 91   
      *  Invoked before other methods to configure the delegate for the given
 92   
      *  form component.  Sets the current field based on
 93   
      *  the {@link IFormComponent#getName() name} of the form component
 94   
      *  (which is almost always a {@link ValidField}).
 95   
      *
 96   
      *  <p>The caller should invoke this with a parameter of null to record
 97   
      *  unassociated global errors (errors not associated with any particular field).
 98   
      *
 99   
      *  @since 1.0.8
 100   
      *
 101   
      **/
 102   
 
 103   
     public void setFormComponent(IFormComponent component);
 104   
 
 105   
     /**
 106   
      *  Returns true if the current component is in error (that is, had bad input
 107   
      *  submitted by the end user).
 108   
      *
 109   
      *  @since 1.0.8
 110   
      *
 111   
      **/
 112   
 
 113   
     public boolean isInError();
 114   
 
 115   
     /**
 116   
      *  Returns the string submitted by the client as the value for
 117   
      *  the current field.
 118   
      *
 119   
      *  @since 1.0.8
 120   
      *
 121   
      **/
 122   
 
 123   
     public String getFieldInputValue();
 124   
 
 125   
     /**
 126   
      *  Returns a {@link List} of {@link IFieldTracking}, in default order
 127   
      *  (the order in which fields are renderred). A caller should
 128   
      *  not change the values (the List is immutable).
 129   
      *  May return null if no fields are in error.
 130   
      *
 131   
      *  @since 1.0.8
 132   
      **/
 133   
 
 134   
     public List getFieldTracking();
 135   
 
 136   
     /**
 137   
      *  Resets any tracking information for the current field.  This will
 138   
      *  clear the field's inError flag, and set its error message and invalid input value
 139   
      *  to null.
 140   
      *
 141   
      *  @since 1.0.8
 142   
      *
 143   
      **/
 144   
 
 145   
     public void reset();
 146   
 
 147   
     /**
 148   
      *  Clears all tracking information.
 149   
      *
 150   
      *  @since 1.0.10
 151   
      *
 152   
      **/
 153   
 
 154   
     public void clear();
 155   
 
 156   
     /**
 157   
      *  Records the user's input for the current form component.  Input should
 158   
      *  be recorded even if there isn't an explicit error, since later form-wide
 159   
      *  validations may discover an error in the field.
 160   
      *
 161   
      *  @since 3.0
 162   
      *
 163   
      **/
 164   
 
 165   
     public void recordFieldInputValue(String input);
 166   
 
 167   
     /**
 168   
      *  The error notification method, invoked during the rewind phase
 169   
      *  (that is, while HTTP parameters are being extracted from the request
 170   
      *  and assigned to various object properties).
 171   
      *
 172   
      *  <p>Typically, the delegate simply invokes
 173   
      *  {@link #record(String, ValidationConstraint)} or
 174   
      *  {@link #record(IRender, ValidationConstraint)}, but special
 175   
      *  delegates may override this behavior to provide (in some cases)
 176   
      *  different error messages or more complicated error renderers.
 177   
      *
 178   
      **/
 179   
 
 180   
     public void record(ValidatorException ex);
 181   
 
 182   
     /**
 183   
      *  Records an error in the current field, or an unassociated error
 184   
      *  if there is no current field.
 185   
      *
 186   
      *  @param message message to display (@see RenderString}
 187   
      *  @param constraint the constraint that was violated, or null if not known
 188   
      *
 189   
      *  @since 1.0.9
 190   
      **/
 191   
 
 192   
     public void record(String message, ValidationConstraint constraint);
 193   
 
 194   
     /**
 195   
      *  Records an error in the current component, or an unassociated error.
 196   
      *  The maximum flexibility recorder.
 197   
      *
 198   
      *  @param errorRenderer object that will render the error message (@see RenderString}
 199   
      *  @param constraint the constraint that was violated, or null if not known
 200   
      *
 201   
      **/
 202   
 
 203   
     public void record(IRender errorRenderer, ValidationConstraint constraint);
 204   
 
 205   
     /**
 206   
      *  Invoked before the field is rendered.  If the field is in error,
 207   
      *  the delegate may decorate the field in some way (to highlight its
 208   
      *  error state).
 209   
      *
 210   
      **/
 211   
 
 212   
     public void writePrefix(
 213   
         IMarkupWriter writer,
 214   
         IRequestCycle cycle,
 215   
         IFormComponent component,
 216   
         IValidator validator);
 217   
 
 218   
     /**
 219   
      *  Invoked just before the &lt;input&gt; element is closed.
 220   
      *  The delegate can write additional attributes.  This is often used
 221   
      *  to set the CSS class of the field so that it can be displayed
 222   
      *  differently, if in error (or required).
 223   
      *
 224   
      *  @since 1.0.5
 225   
      **/
 226   
 
 227   
     public void writeAttributes(
 228   
         IMarkupWriter writer,
 229   
         IRequestCycle cycle,
 230   
         IFormComponent component,
 231   
         IValidator validator);
 232   
 
 233   
     /**
 234   
      *  Invoked after the form component is rendered, so that the
 235   
      *  delegate may decorate the form component (if it is in error).
 236   
      *
 237   
      **/
 238   
 
 239   
     public void writeSuffix(
 240   
         IMarkupWriter writer,
 241   
         IRequestCycle cycle,
 242   
         IFormComponent component,
 243   
         IValidator validator);
 244   
 
 245   
     /**
 246   
      *  Invoked by a {@link FieldLabel} just before writing the name
 247   
      *  of the form component.
 248   
      *
 249   
      **/
 250   
 
 251   
     public void writeLabelPrefix(
 252   
         IFormComponent component,
 253   
         IMarkupWriter writer,
 254   
         IRequestCycle cycle);
 255   
 
 256   
     /**
 257   
      *  Invoked by a {@link FieldLabel} just after writing the name
 258   
      *  of the form component.
 259   
      *
 260   
      **/
 261   
 
 262   
     public void writeLabelSuffix(
 263   
         IFormComponent component,
 264   
         IMarkupWriter writer,
 265   
         IRequestCycle cycle);
 266   
 
 267   
     /**
 268   
      *   Returns true if any form component has errors.
 269   
      *
 270   
      **/
 271   
 
 272   
     public boolean getHasErrors();
 273   
 }