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} 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 * @return Whether or not field is in error.
045 */
046
047 boolean isInError();
048
049 /**
050 * Whether or not any errors found should cause field decoration / error
051 * renderers to render. This is set to false on form submissions (such as a
052 * refresh submit) where validation shouldn't cause errors to be rendererd.
053 *
054 * @return Whether or not to render errors, default is true.
055 */
056 boolean getRenderError();
057
058 /**
059 * Sets whether or not to render errors for this tracking. Gets
060 * set to false on form refresh submits.
061 *
062 * @param value Whether or not to render errors.
063 */
064 void setRenderError(boolean value);
065
066 /**
067 * Returns the field component. This may return null if the error is not
068 * associated with any particular field. Note: may return null after the
069 * field tracking object is serialized and deserialized (the underlying
070 * component reference is transient); this metehod is primarily used for
071 * testing.
072 *
073 * @return The associated component, or null if not specific to a component.
074 */
075
076 IFormComponent getComponent();
077
078 /**
079 * Returns an object that will render the error message. The renderer
080 * <em>must</em> implement a simple <code>toString()</code> that does
081 * not produce markup, but is a simple message.
082 *
083 * @return The {@link IRender} responsible for rendering the error, or null if none is set.
084 * @see ValidatorException#ValidatorException(String, IRender,
085 * ValidationConstraint)
086 * @since 1.0.9
087 */
088
089 IRender getErrorRenderer();
090
091 /**
092 * Returns the invalid input recorded for the field. This is stored so that,
093 * on a subsequent render, the smae invalid input can be presented to the
094 * client to be corrected.
095 *
096 * @return The original input value.
097 */
098 String getInput();
099
100 /**
101 * Returns the name of the field, that is, the name assigned by the form
102 * (this will differ from the component's id when any kind of looping
103 * operation is in effect).
104 *
105 * @return The name of the field within the form.
106 */
107
108 String getFieldName();
109
110 /**
111 * Returns the validation constraint that was violated by the input. This
112 * may be null if the constraint isn't known.
113 *
114 * @return The associated {@link ValidationConstraint} that caused the field error.
115 */
116
117 ValidationConstraint getConstraint();
118 }