    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005//     http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5;
    014
    015import org.apache.tapestry5.corelib.components.Loop;
    016
    017import java.util.List;
    018
    019/**
    020 * Tracks information related to user input validations. This information is: <ul> <li>The input values provided by the
    021 * user. <li>Any validation exceptions associated with input fields. </ul>
    022 *
    023 * The tracker must differentiate between components (which will implement the {@link Field} interfaces) and fields. It
    024 * is a one to many relationship, because each field may be called upon to render itself multiple times within a
    025 * request, because of {@link Loop} or other similar components.
    026 *
    027 * Internally, the tracker indexes its information in terms of the {@linkplain Field#getControlName() control name} for
    028 * each rendering of the component (the mechanics of Tapestry ensures that this is unique within the form).
    029 *
    030 * Validation trackers must be serializable, as they will almost always be stored into the HttpSession.
    031 *
    032 * Trackers are used by only a single form within a single page; they are not threadsafe.
    033 */
    034public interface ValidationTracker
    035{
    036    /**
    037     * Called by a field to record the exact input from the user, prior to any validation. If the form is redisplayed
    038     * (to present errors), the input value will be sent back to the user for correction.
    039     *
    040     * @param field
    041     *         the field recording the input
    042     * @param input
    043     *         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     * Returns just the errors that are not associated with any fields.
    096     *
    097     * @since 5.4
    098     */
    099    List<String> getUnassociatedErrors();
    100
    101    /**
    102     * Clears all information stored by the tracker.
    103     */
    104    void clear();
    105}