Save This Page
Home » tapestry-src-5.0.19 » org.apache.tapestry5 » [javadoc | source]
    1   // Copyright 2006, 2008 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.tapestry5;
   16   
   17   import org.apache.tapestry5.corelib.components.Loop;
   18   
   19   import java.util.List;
   20   
   21   /**
   22    * Tracks information related to user input validations. This information is: <ul> <li>The input values provided by the
   23    * user. <li>Any validation exceptions associated with input fields. </ul>
   24    * <p/>
   25    * The tracker must differentiate between components (which will implement the {@link Field} interfaces) and fields. It
   26    * is a one to many relationship, because each field may be called upon to render itself multiple times within a
   27    * request, because of {@link Loop} or other similar components.
   28    * <p/>
   29    * Internally, the tracker indexes its information in terms of the {@linkplain Field#getControlName() control name} for
   30    * each rendering of the component (the mechanics of Tapestry ensures that this is unique within the form).
   31    * <p/>
   32    * Validation trackers must be serializable, as they will almost always be stored into the HttpSession.
   33    * <p/>
   34    * Trackers are used by only a single form within a single page; they are not threadsafe.
   35    */
   36   public interface ValidationTracker
   37   {
   38       /**
   39        * Called by a field to record the exact input from the user, prior to any validation. If the form is redisplayed
   40        * (to present errors), the input value will be sent back to the user for correction.
   41        *
   42        * @param field the field recording the input
   43        * @param input the value obtained from the forms submission
   44        */
   45       void recordInput(Field field, String input);
   46   
   47       /**
   48        * Returns a previously recorded input value.
   49        */
   50       String getInput(Field field);
   51   
   52       /**
   53        * Records an error message for a field. The error message is primarily derived from a {@link ValidationException}
   54        * thrown by a {@link Validator} or {@link Translator}.
   55        *
   56        * @param field
   57        * @param errorMessage
   58        */
   59       void recordError(Field field, String errorMessage);
   60   
   61       /**
   62        * Records an error message that is not associated with any specific field. This often reflects some amount of
   63        * cross-form validation.
   64        *
   65        * @param errorMessage
   66        */
   67       void recordError(String errorMessage);
   68   
   69       /**
   70        * For a given field, determines if the field is "in error", meaning that an error message has been previously
   71        * recorded for the field.
   72        *
   73        * @param field
   74        * @return true if an error message is present
   75        */
   76       boolean inError(Field field);
   77   
   78       /**
   79        * Returns a previously recorded error message.
   80        */
   81       String getError(Field field);
   82   
   83       /**
   84        * Returns true if any field contains an error.
   85        */
   86       boolean getHasErrors();
   87   
   88       /**
   89        * Returns a list of all error messages. The messages are stored in the order that they were added to the tracker,
   90        * except that unassociated errors (unassociated with any field) are listed first.
   91        */
   92       List<String> getErrors();
   93   
   94       /**
   95        * Clears all information stored by the tracker.
   96        */
   97       void clear();
   98   }

Save This Page
Home » tapestry-src-5.0.19 » org.apache.tapestry5 » [javadoc | source]