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
015package org.apache.tapestry.valid;
016
017import org.apache.tapestry.IRender;
018import 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
034public 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}