001    // Copyright 2004, 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.valid;
016    
017    import org.apache.tapestry.IRender;
018    import org.apache.tapestry.form.IFormComponent;
019    
020    /**
021     * Defines the interface for an object that tracks input fields. This interface
022     * is now poorly named, in that it tracks errors that may <em>not</em> be
023     * associated with a specific field.
024     * <p>
025     * For each field, a flag is stored indicating if the field is, in fact, in
026     * error. The input supplied by the client is stored so that if the form is
027     * re-rendered (as is typically done when there are input errors), the value
028     * entered by the user can be displayed back to the user. An error message
029     * renderer is stored; this is an object that can render the error message (it
030     * is usually a {@link org.apache.tapestry.valid.RenderString}&nbsp;wrapper
031     * around a simple string).
032     * 
033     * @author Howard Lewis Ship
034     * @since 1.0.8
035     */
036    
037    public interface IFieldTracking
038    {
039    
040        /**
041         * Returns true if the field is in error (that is, if it has an error
042         * message {@link #getErrorRenderer() renderer}.
043         */
044    
045        boolean isInError();
046    
047        /**
048         * Returns the field component. This may return null if the error is not
049         * associated with any particular field. Note: may return null after the
050         * field tracking object is serialized and deserialized (the underlying
051         * component reference is transient); this metehod is primarily used for
052         * testing.
053         */
054    
055        IFormComponent getComponent();
056    
057        /**
058         * Returns an object that will render the error message. The renderer
059         * <em>must</em> implement a simple <code>toString()</code> that does
060         * not produce markup, but is a simple message.
061         * 
062         * @see ValidatorException#ValidatorException(String, IRender,
063         *      ValidationConstraint)
064         * @since 1.0.9
065         */
066    
067        IRender getErrorRenderer();
068    
069        /**
070         * Returns the invalid input recorded for the field. This is stored so that,
071         * on a subsequent render, the smae invalid input can be presented to the
072         * client to be corrected.
073         */
074    
075        String getInput();
076    
077        /**
078         * Returns the name of the field, that is, the name assigned by the form
079         * (this will differ from the component's id when any kind of looping
080         * operation is in effect).
081         */
082    
083        String getFieldName();
084    
085        /**
086         * Returns the validation constraint that was violated by the input. This
087         * may be null if the constraint isn't known.
088         */
089    
090        ValidationConstraint getConstraint();
091    }