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