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    }