    001    // Copyright 2006, 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.services;
    016
    017    import org.apache.tapestry5.Field;
    018    import org.apache.tapestry5.FieldValidator;
    019    import org.apache.tapestry5.Validator;
    020    import org.apache.tapestry5.corelib.components.BeanEditForm;
    021    import org.apache.tapestry5.ioc.Messages;
    022    import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    023
    024    import java.util.Locale;
    025
    026    /**
    027     * Used to create {@link org.apache.tapestry5.FieldValidator}s for a particular {@link org.apache.tapestry5.Field}
    028     * component.
    029     */
    030    @UsesMappedConfiguration(Validator.class)
    031    public interface FieldValidatorSource
    032    {
    033        /**
    034         * Creates the validator. The error message associated with the field validator usually comes from the
    035         * global message catalog (using the validator's {@link Validator#getMessageKey() message key}). However,
    036         * if the container component of the field defines a message key <code><i>id</i>-<i>validator</i> (where id is the simple
    037         * id of the field component, and validator is the validatorType), then that message is used instead. This allows
    038         * you to override the message for a particular validation of a particular field.
    039         *
    040         * @param field
    041         *            the field for which a validator is to be created
    042         * @param validatorType
    043         *            used to select the {@link org.apache.tapestry5.Validator} that forms the core of the
    044         *            {@link org.apache.tapestry5.FieldValidator}
    045         * @param constraintValue
    046         *            a value used to configure the validator, or null if the validator is not configurarable
    047         * @return the field validator for the field
    048         */
    049        FieldValidator createValidator(Field field, String validatorType, String constraintValue);
    050
    051        /**
    052         * Full featured version of {@link #createValidator(Field, String, String)} used in situations where the container
    053         * of the field is not necesarrilly the place to look for override messages, and the id of the field is not the key
    054         * to use when checking. The {@link BeanEditForm} is an example of this.
    055         *
    056         * @param field
    057         *            the field for which a validator is to be created
    058         * @param validatorType
    059         *            used to select the {@link org.apache.tapestry5.Validator} that forms the core of the
    060         *            {@link org.apache.tapestry5.FieldValidator}
    061         * @param constraintValue
    062         *            a value used to configure the validator, or null if the validator is not configurable
    063         * @param overrideId
    064         *            the base id used when searching for validator message overrides (this would normally be
    065         *            the field component's simple id)
    066         * @param overrideMessages
    067         *            the message catalog to search for override messages (this would normally be the catalog
    068         *            for the container of the field component)
    069         * @param locale
    070         *            ignored, starting in 5.3 (it is allowed to pass null). Locale was needed in release 5.2 and earlier.
    071         * @return the field validator for the field
    072         */
    073        FieldValidator createValidator(Field field, String validatorType, String constraintValue, String overrideId,
    074                Messages overrideMessages, Locale locale);
    075
    076        /**
    077         * Creates a set of validators. The specification is a string used to identify and configure the individual
    078         * validators. The specification is a comma-separated list of terms. Each term is a validator type name and an
    079         * optional constraint value (seperated by an equals sign).
    080         *
    081         * @param field
    082         * @param specification
    083         * @return a composite field validator
    084         */
    085        FieldValidator createValidators(Field field, String specification);
    086    }