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.commons.Messages;
019import org.apache.tapestry5.corelib.components.BeanEditForm;
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}