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    
015    package org.apache.tapestry.form.validator;
016    
017    import org.apache.tapestry.form.FormComponentContributor;
018    import org.apache.tapestry.form.IFormComponent;
019    import org.apache.tapestry.form.ValidationMessages;
020    import 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     */
030    public 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        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        boolean getAcceptsNull();
061    
062        /**
063         * Returns true if this field is required. Returns false otherwise.
064         */
065    
066        boolean isRequired();
067    }