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}