    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    }