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 }