01: // Copyright 2006 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // Unless required by applicable law or agreed to in writing, software
10: // distributed under the License is distributed on an "AS IS" BASIS,
11: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: // See the License for the specific language governing permissions and
13: // limitations under the License.
14:
15: package org.apache.tapestry;
16:
17: import java.util.List;
18:
19: import org.apache.tapestry.corelib.components.Loop;
20:
21: /**
22: * Tracks information related to user input validations. This information is:
23: * <ul>
24: * <li>The input values provided by the user.
25: * <li>Any validation exceptions associated with input fields.
26: * </ul>
27: * <p>
28: * The tracker must differentiate between components (which will implement the {@link Field}
29: * interfaces) and fields. It is a one to many relationship, because each field may be called upon
30: * to render itself multiple times within a request, because of {@link Loop} or other similar
31: * components.
32: * <p>
33: * Internally, the tracker indexes its information in terms of the {@link Field#getElementName()}
34: * for each rendering of the component (the mechanics of Tapestry ensures that this is unique within
35: * the form).
36: * <p>
37: * Validation trackers must be serializable, as they will almost always be stored into the
38: * HttpSession.
39: * <p>
40: * Trackers are used by only a single form within a single page; they are not threadsafe.
41: */
42: public interface ValidationTracker {
43: /**
44: * Called by a field to record the exact input from the user, prior to any validation. If the
45: * form is redisplayed (to present errors), the input value will be sent back to the user for
46: * correction.
47: *
48: * @param field
49: * the field recording the input
50: * @param input
51: * the value obtained from the forms submission
52: */
53: void recordInput(Field field, String input);
54:
55: /** Returns a previously recorded input value. */
56: String getInput(Field field);
57:
58: /**
59: * Records an error message for a field. The error message is primarily derived from a
60: * {@link ValidationException} thrown by a {@link Validator} or {@link Translator}.
61: *
62: * @param field
63: * @param errorMessage
64: */
65: void recordError(Field field, String errorMessage);
66:
67: /**
68: * Records an error message that is not associated with any specific field. This often reflects
69: * some amount of cross-form validation.
70: *
71: * @param errorMessage
72: */
73: void recordError(String errorMessage);
74:
75: /**
76: * For a given field, determines if the field is "in error", meaning that an error message has
77: * been previously recorded for the field.
78: *
79: * @param field
80: * @return true if an error message is present
81: */
82: boolean inError(Field field);
83:
84: /** Returns a previously recorded error message. */
85: String getError(Field field);
86:
87: /** Returns true if any field contains an error. */
88: boolean getHasErrors();
89:
90: /**
91: * Returns a list of all error messages. The messages are stored in the order that they were
92: * added to the tracker, except that unassociated errors (unassociated with any field) are
93: * listed first.
94: */
95: List<String> getErrors();
96:
97: /** Clears all information stored by the tracker. */
98: void clear();
99: }
|