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
015package org.apache.tapestry5.services;
016
017import org.apache.tapestry5.Field;
018import org.apache.tapestry5.FieldValidator;
019import org.apache.tapestry5.Validator;
020import org.apache.tapestry5.corelib.components.BeanEditForm;
021import org.apache.tapestry5.ioc.Messages;
022import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
023
024import 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)
031public 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}