001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: Validated.java 3634 2007-01-08 21:42:24Z gbevin $
007: */
008: package com.uwyn.rife.site;
009:
010: import java.util.List;
011: import java.util.Set;
012:
013: /**
014: * This interface defines methods for bean-centric data validation.
015: * <p>Validation is bound to subjects that have distinct names. Each subject
016: * corresponds to a different variable, for example a property of a bean. When
017: * a subject is found to be invalid, a corresponding instance of
018: * <code>ValidationError</code> has to be registered.
019: * <p><code>ValidationError</code>s indicate in detail why a
020: * <code>Validated</code> object doesn't contain valid data. They should be
021: * stored internally and can be manipulated by other classes that are able to
022: * work with <code>Validated</code> objects. This makes it possible to collect
023: * errors incrementally in one central place and to allow each component in a
024: * system to perform its own part of the validation.
025: * <p>A <code>Validated</code> object has a {@link #validate() validate()}
026: * method which should be used to perform mandatory validation on subjects and
027: * data that the object itself knows about. This validation has to perform all
028: * checks that guarantee a coherent internal state of the data. Note that this
029: * method should not reset the validation, but instead add new validation
030: * errors to an already existing collection.
031: * <p>Since it's possible that subjects generate multiple
032: * <code>ValidationError</code>s, it's possible to limit their number and only
033: * store the first error that occurs for a particular subject.
034: *
035: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
036: * @version $Revision: 3634 $
037: * @see ValidationError
038: * @see ValidationContext
039: * @since 1.0
040: */
041: public interface Validated {
042: /**
043: * Validates the internal subjects.
044: * <p>This method is not suppossed to reset the validation errors or to
045: * start the validation from scratch, but it's intended to add additional
046: * errors to an existing collection.
047: *
048: * @return <code>true</code> if no validation errors are present after the
049: * validation; or
050: * <p><code>false</code> if validation errors are available.
051: * @see #validate(ValidationContext)
052: * @see #resetValidation()
053: * @since 1.0
054: */
055: public boolean validate();
056:
057: /**
058: * Validates the internal subjects and also validates the bean within the
059: * provided <code>ValidationContext</code>
060: * <p>This method is not suppossed to reset the validation errors or to
061: * start the validation from scratch, but it's intended to add additional
062: * errors to an existing collection.
063: *
064: * @param context the <code>ValidationContext</code> in which this bean
065: * instance will be additionally validated
066: * @return <code>true</code> if no validation errors are present after the
067: * validation; or
068: * <p><code>false</code> if validation errors are available.
069: * @see #validate()
070: * @see #resetValidation()
071: * @since 1.0
072: */
073: public boolean validate(ValidationContext context);
074:
075: /**
076: * <p>Adds a new validation rule.
077: * <p>The collection of rules is what is supposed to perform the
078: * validation, though any other additional method could be used. At least
079: * those rules that have been registered will be evaluated.
080: *
081: * @param rule the rule that will be added
082: * @see #validate()
083: * @see #getRules()
084: * @since 1.4
085: */
086: public void addRule(ValidationRule rule);
087:
088: /**
089: * Retrieves that validation rules that have been registered.
090: *
091: * @see #validate()
092: * @see #addRule
093: * @since 1.0
094: */
095: public List<ValidationRule> getRules();
096:
097: /**
098: * <p>Resets the validation by removing all validation errors that are
099: * currently present.
100: * <p>This method is typically used to start a new validation from scratch
101: * or to re-validate until all errors have been solved.
102: *
103: * @see #validate()
104: * @since 1.0
105: */
106: public void resetValidation();
107:
108: /**
109: * Add a new validation error explicitly to the collection of already
110: * existing errors.
111: * <p>Note that this method should respect subjects with a limited error
112: * amount and only store the first error for these subjects.
113: *
114: * @param error the <code>ValidationError</code> to add
115: * @see #limitSubjectErrors(String)
116: * @see #unlimitSubjectErrors(String)
117: * @since 1.0
118: */
119: public void addValidationError(ValidationError error);
120:
121: /**
122: * Returns a set with all the stored <code>ValidationError</code>s.
123: *
124: * @return A <code>Set</code> instance with all the stored
125: * <code>ValidationError</code>s. Note that when no errors are available
126: * an empty set is returned, not <code>null</code>.
127: * @since 1.0
128: */
129: public Set<ValidationError> getValidationErrors();
130:
131: /**
132: * Counts the number of stored <code>ValidationError</code>s.
133: *
134: * @return The number of stored <code>ValidationError</code>s.
135: * @since 1.0
136: */
137: public int countValidationErrors();
138:
139: /**
140: * Replaces the stored <code>ValidationError</code>s with a new set of
141: * errors.
142: *
143: * @param errors the <code>Set</code> instance that contains all the
144: * <code>ValidationError</code>s that have to be stored.
145: * @since 1.0
146: */
147: public void replaceValidationErrors(Set<ValidationError> errors);
148:
149: /**
150: * Limits the number of errors for a particular subject so that maximum
151: * one <code>ValidationError</code> can be stored for it.
152: *
153: * @param subject the name of the subject that has to be limited.
154: * @since 1.0
155: */
156: public void limitSubjectErrors(String subject);
157:
158: /**
159: * Unlimits the number of errors for a particular subject so that any
160: * number of <code>ValidationError</code>s can be stored for it.
161: *
162: * @param subject the name of the subject that has to be unlimited.
163: * @since 1.0
164: */
165: public void unlimitSubjectErrors(String subject);
166:
167: /**
168: * Returns the list of subjects that this object is able to validate
169: * internally through the {@link #validate() validate()} method.
170: *
171: * @return a List instance with the names of the internally validated
172: * subjects
173: * @since 1.0
174: */
175: public List<String> getValidatedSubjects();
176:
177: /**
178: * Checks if a subject is valid.
179: * <p>This is determined by verifying if there are
180: * <code>ValidationError</code>s present for it. This method will thus not
181: * execute a validation action.
182: *
183: * @param subject the name of the subject that has to be checked.
184: * @return <code>true</code> when no errors could be found for the
185: * subject; or
186: * <p><code>false</code> when errors are present for the subject.
187: * @see #validate()
188: * @since 1.0
189: */
190: public boolean isSubjectValid(String subject);
191:
192: /**
193: * Makes errors for a particular subject and identifier valid.
194: * <p>This is done by removing all <code>ValidationError</code>s that are
195: * stored with this identifier and subject.
196: *
197: * @param identifier the name of the error identifier that has to be made
198: * @param subject the name of the subject that has to be made valid.
199: * valid.
200: * @since 1.0
201: */
202: public void makeErrorValid(String identifier, String subject);
203:
204: /**
205: * Makes a subject valid.
206: * <p>This is done by removing all <code>ValidationError</code>s that are
207: * stored for it.
208: *
209: * @param subject the name of the subject that has to be made valid.
210: * @since 1.0
211: */
212: public void makeSubjectValid(String subject);
213:
214: /**
215: * Provide the bean instance that will be validated.
216: * <p>By default '<code>this</code>' will be used.
217: *
218: * @param bean the bean instance that will be validated
219: * @since 1.4
220: */
221: public void provideValidatedBean(Validated bean);
222:
223: /**
224: * Retrieves the bean instance that will be validated.
225: *
226: * @since 1.4
227: */
228: public Validated retrieveValidatedBean();
229: }
|