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