    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}