01: // Copyright 2006, 2007 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 org.apache.tapestry.ioc.MessageFormatter;
18: import org.apache.tapestry.services.ValidationMessagesSource;
19:
20: /**
21: * Used by a {@link Field} to enforce a <strong>constraint</strong> related to a form submission.
22: * Validators themselves are stateless singletons.
23: * <p>
24: * Validators are usually encapsulated inside a {@link FieldValidator}.
25: */
26: public interface Validator<C, T> {
27: /**
28: * Returns the type of constraint value used with this validator. Constraint values are used to
29: * parameterize a validator, for example a "maxLength" validator will have a constraint value of
30: * type int (the maximum length allowed). For constraints that do not have a constraint value,
31: * this method returns null.
32: */
33: Class<C> getConstraintType();
34:
35: /**
36: * Returns the value type associated with this validator.
37: * {@link #validate(Field, Object, MessageFormatter, Object)} will only be invoked when the
38: * value is assignable to the validator's value type.
39: */
40: Class<T> getValueType();
41:
42: /**
43: * Returns the message key, within the validiation messages, normally used by this validator.
44: * This is used to provide the {@link MessageFormatter} passed to
45: * {@link #validate(Field, Object, MessageFormatter, Object)} (unless overridden).
46: *
47: * @see ValidationMessagesSource
48: * @return a message key
49: */
50: String getMessageKey();
51:
52: /**
53: * Invoked after the client-submitted value has been {@link Translator translated} to check that
54: * the value conforms to expectations (often, in terms of minimum or maximum value). If and only
55: * if the value is approved by all Validators is the value applied by the field.
56: *
57: * @param field
58: * the field for which a client submitted value is being validated
59: * @param constraintValue
60: * the value used to constrain
61: * @param formatter
62: * Validation messages, in the appropriate locale
63: * @param value
64: * the translated value supplied by the user
65: * @throws ValidationException
66: * if the value violates the constraint
67: */
68: void validate(Field field, C constraintValue,
69: MessageFormatter formatter, T value)
70: throws ValidationException;
71:
72: /**
73: * Returns true if the validator should be invoked for null or blank (empty string) values. This
74: * is generally false.
75: */
76: boolean invokeIfBlank();
77:
78: /**
79: * Hook used by components to allow the validator to contribute additional attribute or (more
80: * often) client-side JavaScript (via the {@link PageRenderSupport}).
81: *
82: * @param field
83: * the field which is currently being rendered
84: * @param constraintValue
85: * the value used to constrain input
86: * @param formatter
87: * validation message, in the appropriate locale
88: * @param writer
89: * markup writer, allowing additional attributes to be written into the active
90: * element
91: * @param pageRenderSupport
92: * used to generate client-side JavaScript to support validation
93: */
94: void render(Field field, C constraintValue,
95: MessageFormatter formatter, MarkupWriter writer,
96: PageRenderSupport pageRenderSupport);
97: }
|