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