001 // Copyright 2006, 2008 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry5;
016
017 import org.apache.tapestry5.corelib.components.Loop;
018
019 import java.util.List;
020
021 /**
022 * Tracks information related to user input validations. This information is: <ul> <li>The input values provided by the
023 * user. <li>Any validation exceptions associated with input fields. </ul>
024 * <p/>
025 * The tracker must differentiate between components (which will implement the {@link Field} interfaces) and fields. It
026 * is a one to many relationship, because each field may be called upon to render itself multiple times within a
027 * request, because of {@link Loop} or other similar components.
028 * <p/>
029 * Internally, the tracker indexes its information in terms of the {@linkplain Field#getControlName() control name} for
030 * each rendering of the component (the mechanics of Tapestry ensures that this is unique within the form).
031 * <p/>
032 * Validation trackers must be serializable, as they will almost always be stored into the HttpSession.
033 * <p/>
034 * Trackers are used by only a single form within a single page; they are not threadsafe.
035 */
036 public interface ValidationTracker
037 {
038 /**
039 * Called by a field to record the exact input from the user, prior to any validation. If the form is redisplayed
040 * (to present errors), the input value will be sent back to the user for correction.
041 *
042 * @param field the field recording the input
043 * @param input the value obtained from the forms submission
044 */
045 void recordInput(Field field, String input);
046
047 /**
048 * Returns a previously recorded input value.
049 */
050 String getInput(Field field);
051
052 /**
053 * Records an error message for a field. The error message is primarily derived from a {@link ValidationException}
054 * thrown by a {@link Validator} or {@link Translator}.
055 *
056 * @param field
057 * @param errorMessage
058 */
059 void recordError(Field field, String errorMessage);
060
061 /**
062 * Records an error message that is not associated with any specific field. This often reflects some amount of
063 * cross-form validation.
064 *
065 * @param errorMessage
066 */
067 void recordError(String errorMessage);
068
069 /**
070 * For a given field, determines if the field is "in error", meaning that an error message has been previously
071 * recorded for the field.
072 *
073 * @param field
074 * @return true if an error message is present
075 */
076 boolean inError(Field field);
077
078 /**
079 * Returns a previously recorded error message.
080 */
081 String getError(Field field);
082
083 /**
084 * Returns true if any field contains an error.
085 */
086 boolean getHasErrors();
087
088 /**
089 * Returns a list of all error messages. The messages are stored in the order that they were added to the tracker,
090 * except that unassociated errors (unassociated with any field) are listed first.
091 */
092 List<String> getErrors();
093
094 /**
095 * Clears all information stored by the tracker.
096 */
097 void clear();
098 }