001// Copyright 2005 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.tapestry.form.validator;
016
017import org.apache.tapestry.form.IFormComponent;
018import org.apache.tapestry.form.FormComponentContributor;
019import org.apache.tapestry.form.ValidationMessages;
020import org.apache.tapestry.valid.ValidatorException;
021
022/**
023 * An object that can be "attached" to a {@link org.apache.tapestry.form.IFormComponent} to perform
024 * server-side validation ({@link #validate(IFormComponent, ValidationMessages, Object)}) as well
025 * as generate cleint-side validation (in the form of JavaScript submit listeners).
026 * 
027 * @author Paul Ferraro
028 * @since 4.0
029 */
030public interface Validator extends FormComponentContributor
031{
032    /**
033     * Invoked to validate input for the field. A
034     * {@link org.apache.tapestry.form.translator.Translator} will have already converted the
035     * submitted user input string into an object.
036     * 
037     * @param field
038     *            the form element component being validated, often used to determine the
039     *            {@link IFormComponent#getDisplayName() user presentable name} for the field, used
040     *            in error messages.
041     * @param messages
042     *            access to the pre-defined validation messages, in the appropriate locale
043     * @param object
044     *            the client-side representation of the field's data. May be null if the client did
045     *            not provide a value for the field (most Validators should check for null and
046     *            perform no check if null).
047     * @throws ValidatorException
048     *             if the object violates the constraint represented by this Validator.
049     */
050
051    public void validate(IFormComponent field, ValidationMessages messages, Object object)
052            throws ValidatorException;
053
054    /**
055     * Returns true if this validator accepts null as the object parameter to validate(). When the
056     * object is null, validators that can't accept null are skipped. It is rare for a validator to
057     * return true.
058     */
059
060    public boolean getAcceptsNull();
061
062    /**
063     * Returns true if this field is required. Returns false otherwise.
064     */
065
066    public boolean isRequired();
067}