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.commons.MessageFormatter;
016import org.apache.tapestry5.services.FormSupport;
017
018/**
019 * Used by a {@link Field} to enforce a <strong>constraint</strong> related to a form submission. Validators themselves
020 * are stateless singletons.
021 *
022 * Validators are usually encapsulated inside a {@link FieldValidator}.
023 *
024 * @see FieldValidationSupport
025 * @see org.apache.tapestry5.services.FieldValidatorDefaultSource
026 */
027public interface Validator<C, T>
028{
029    /**
030     * Returns the type of constraint value used with this validator. Constraint values are used to parameterize a
031     * validator, for example a "maxLength" validator will have a constraint value of type int (the maximum length
032     * allowed). For constraints that do not have a constraint value, this method returns null.
033     */
034    Class<C> getConstraintType();
035
036    /**
037     * Returns the value type associated with this validator. {@link #validate(Field, Object, MessageFormatter, Object)}
038     * will only be invoked when the value is assignable to the validator's value type.
039     */
040    Class<T> getValueType();
041
042    /**
043     * Returns the message key, within the validation messages, normally used by this validator. This is used to provide
044     * the {@link MessageFormatter} passed to {@link #validate(Field, Object, MessageFormatter, Object)} (unless
045     * overridden).
046     *
047     * @return a message key
048     */
049    String getMessageKey();
050
051    /**
052     * Invoked after the client-submitted value has been {@link org.apache.tapestry5.Translator translated} to check
053     * that the value conforms to expectations (often, in terms of minimum or maximum value). If and only if the value
054     * is approved by all Validators is the value applied by the field.
055     *
056     * @param field           the field for which a client submitted value is being validated
057     * @param constraintValue the value used to constrain
058     * @param formatter       Validation messages, in the appropriate locale
059     * @param value           the translated value supplied by the user
060     * @throws ValidationException if the value violates the constraint
061     */
062    void validate(Field field, C constraintValue, MessageFormatter formatter, T value) throws ValidationException;
063
064    /**
065     * Returns true if the validator should be invoked for null or blank (empty string) values. This is generally false,
066     * but is true for validators that enforce that a non-blank value is required.  This is the basis of the {@link
067     * org.apache.tapestry5.Field#isRequired()} property.
068     */
069    boolean isRequired();
070
071    /**
072     * Hook used by components to allow the validator to contribute additional attributes or (more often) client-side
073     * JavaScript (via the {@link FormSupport#addValidation(Field, String, String, Object)}).
074     *
075     * @param field           the field which is currently being rendered
076     * @param constraintValue the value used to constrain input
077     * @param formatter       validation message, in the appropriate locale
078     * @param writer          markup writer, allowing additional attributes to be written into the active element
079     * @param formSupport     used to add JavaScript
080     */
081    void render(Field field, C constraintValue, MessageFormatter formatter, MarkupWriter writer,
082                FormSupport formSupport);
083}