    001// Copyright 2006, 2008, 2013 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
    015package org.apache.tapestry5;
    016
    017import org.apache.tapestry5.corelib.components.Loop;
    018
    019import 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 */
    036public 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
    043     *         the field recording the input
    044     * @param input
    045     *         the value obtained from the forms submission
    046     */
    047    void recordInput(Field field, String input);
    048
    049    /**
    050     * Returns a previously recorded input value.
    051     */
    052    String getInput(Field field);
    053
    054    /**
    055     * Records an error message for a field. The error message is primarily derived from a {@link ValidationException}
    056     * thrown by a {@link Validator} or {@link Translator}.
    057     *
    058     * @param field
    059     * @param errorMessage
    060     */
    061    void recordError(Field field, String errorMessage);
    062
    063    /**
    064     * Records an error message that is not associated with any specific field. This often reflects some amount of
    065     * cross-form validation.
    066     *
    067     * @param errorMessage
    068     */
    069    void recordError(String errorMessage);
    070
    071    /**
    072     * For a given field, determines if the field is "in error", meaning that an error message has been previously
    073     * recorded for the field.
    074     *
    075     * @param field
    076     * @return true if an error message is present
    077     */
    078    boolean inError(Field field);
    079
    080    /**
    081     * Returns a previously recorded error message.
    082     */
    083    String getError(Field field);
    084
    085    /**
    086     * Returns true if any field contains an error.
    087     */
    088    boolean getHasErrors();
    089
    090    /**
    091     * Returns a list of all error messages. The messages are stored in the order that they were added to the tracker,
    092     * except that unassociated errors (unassociated with any field) are listed first.
    093     */
    094    List<String> getErrors();
    095
    096    /**
    097     * Returns just the errors that are not associated with any fields.
    098     *
    099     * @since 5.4
    100     */
    101    List<String> getUnassociatedErrors();
    102
    103    /**
    104     * Clears all information stored by the tracker.
    105     */
    106    void clear();
    107}