Errors


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.validation;
18  
19  import java.util.List  ;
20  
21  import org.springframework.beans.PropertyAccessor;
22  
23  /**
24   * Stores and exposes information about data-binding and validation
25   * errors for a specific object.
26   *
27   * <p>Field names can be properties of the target object (e.g. "name"
28   * when binding to a customer object), or nested fields in case of
29   * subobjects (e.g. "address.street"). Supports subtree navigation
30   * via {@link #setNestedPath(String)}: for example, an
31   * <code>AddressValidator</code> validates "address", not being aware
32   * that this is a subobject of customer.
33   *
34   * <p>Note: <code>Errors</code> objects are single-threaded.
35   *
36   * @author Rod Johnson
37   * @author Juergen Hoeller
38   * @see #setNestedPath
39   * @see BindException
40   * @see DataBinder
41   * @see ValidationUtils
42   */
43  public interface Errors {
44  
45      /**
46       * The separator between path elements in a nested path,
47       * for example in "customer.name" or "customer.address.street".
48       * <p>"." = same as the
49       * {@link org.springframework.beans.PropertyAccessor#NESTED_PROPERTY_SEPARATOR nested property separator}
50       * in the beans package.
51       */
52      String   NESTED_PATH_SEPARATOR = PropertyAccessor.NESTED_PROPERTY_SEPARATOR;
53  
54  
55      /**
56       * Return the name of the bound root object.
57       */
58      String   getObjectName();
59  
60      /**
61       * Allow context to be changed so that standard validators can validate
62       * subtrees. Reject calls prepend the given path to the field names.
63       * <p>For example, an address validator could validate the subobject
64       * "address" of a customer object.
65       * @param nestedPath nested path within this object,
66       * e.g. "address" (defaults to "", <code>null</code> is also acceptable).
67       * Can end with a dot: both "address" and "address." are valid.
68       */
69      void setNestedPath(String   nestedPath);
70  
71      /**
72       * Return the current nested path of this {@link Errors} object.
73       * <p>Returns a nested path with a dot, i.e. "address.", for easy
74       * building of concatenated paths. Default is an empty String.
75       */
76      String   getNestedPath();
77  
78      /**
79       * Push the given sub path onto the nested path stack.
80       * <p>A {@link #popNestedPath()} call will reset the original
81       * nested path before the corresponding
82       * <code>pushNestedPath(String)</code> call.
83       * <p>Using the nested path stack allows to set temporary nested paths
84       * for subobjects without having to worry about a temporary path holder.
85       * <p>For example: current path "spouse.", pushNestedPath("child") ->
86       * result path "spouse.child."; popNestedPath() -> "spouse." again.
87       * @param subPath the sub path to push onto the nested path stack
88       * @see #popNestedPath
89       */
90      void pushNestedPath(String   subPath);
91  
92      /**
93       * Pop the former nested path from the nested path stack.
94       * @throws IllegalStateException if there is no former nested path on the stack
95       * @see #pushNestedPath
96       */
97      void popNestedPath() throws IllegalStateException  ;
98  
99      /**
100      * Register a global error for the entire target object,
101      * using the given error description.
102      * @param errorCode error code, interpretable as a message key
103      */
104     void reject(String   errorCode);
105 
106     /**
107      * Register a global error for the entire target object,
108      * using the given error description.
109      * @param errorCode error code, interpretable as a message key
110      * @param defaultMessage fallback default message
111      */
112     void reject(String   errorCode, String   defaultMessage);
113 
114     /**
115      * Register a global error for the entire target object,
116      * using the given error description.
117      * @param errorCode error code, interpretable as a message key
118      * @param errorArgs error arguments, for argument binding via MessageFormat
119      * (can be <code>null</code>)
120      * @param defaultMessage fallback default message
121      */
122     void reject(String   errorCode, Object  [] errorArgs, String   defaultMessage);
123 
124     /**
125      * Register a field error for the specified field of the current object
126      * (respecting the current nested path, if any), using the given error
127      * description.
128      * <p>The field name may be <code>null</code> or empty String to indicate
129      * the current object itself rather than a field of it. This may result
130      * in a corresponding field error within the nested object graph or a
131      * global error if the current object is the top object.
132      * @param field the field name (may be <code>null</code> or empty String)
133      * @param errorCode error code, interpretable as a message key
134      * @see #getNestedPath()
135      */
136     void rejectValue(String   field, String   errorCode);
137 
138     /**
139      * Register a field error for the specified field of the current object
140      * (respecting the current nested path, if any), using the given error
141      * description.
142      * <p>The field name may be <code>null</code> or empty String to indicate
143      * the current object itself rather than a field of it. This may result
144      * in a corresponding field error within the nested object graph or a
145      * global error if the current object is the top object.
146      * @param field the field name (may be <code>null</code> or empty String)
147      * @param errorCode error code, interpretable as a message key
148      * @param defaultMessage fallback default message
149      * @see #getNestedPath()
150      */
151     void rejectValue(String   field, String   errorCode, String   defaultMessage);
152 
153     /**
154      * Register a field error for the specified field of the current object
155      * (respecting the current nested path, if any), using the given error
156      * description.
157      * <p>The field name may be <code>null</code> or empty String to indicate
158      * the current object itself rather than a field of it. This may result
159      * in a corresponding field error within the nested object graph or a
160      * global error if the current object is the top object.
161      * @param field the field name (may be <code>null</code> or empty String)
162      * @param errorCode error code, interpretable as a message key
163      * @param errorArgs error arguments, for argument binding via MessageFormat
164      * (can be <code>null</code>)
165      * @param defaultMessage fallback default message
166      * @see #getNestedPath()
167      */
168     void rejectValue(String   field, String   errorCode, Object  [] errorArgs, String   defaultMessage);
169 
170     /**
171      * Add all errors from the given <code>Errors</code> instance to this
172      * <code>Errors</code> instance.
173      * <p>This is a onvenience method to avoid repeated <code>reject(..)</code>
174      * calls for merging an <code>Errors</code> instance into another
175      * <code>Errors</code> instance.
176      * <p>Note that the passed-in <code>Errors</code> instance is supposed
177      * to refer to the same target object, or at least contain compatible errors
178      * that apply to the target object of this <code>Errors</code> instance.
179      * @param errors the <code>Errors</code> instance to merge in
180      */
181     void addAllErrors(Errors errors);
182 
183     /**
184      * Return if there were any errors.
185      */
186     boolean hasErrors();
187 
188     /**
189      * Return the total number of errors.
190      */
191     int getErrorCount();
192 
193     /**
194      * Get all errors, both global and field ones.
195      * @return List of {@link ObjectError} instances
196      */
197     List   getAllErrors();
198 
199     /**
200      * Are there any global errors?
201      * @return <code>true</code> if there are any global errors
202      * @see #hasFieldErrors() 
203      */
204     boolean hasGlobalErrors();
205 
206     /**
207      * Return the number of global errors.
208      * @return the number of global errors
209      * @see #getFieldErrorCount() 
210      */
211     int getGlobalErrorCount();
212 
213     /**
214      * Get all global errors.
215      * @return List of ObjectError instances
216      */
217     List   getGlobalErrors();
218 
219     /**
220      * Get the <i>first</i> global error, if any.
221      * @return the global error, or <code>null</code>
222      */
223     ObjectError getGlobalError();
224 
225     /**
226      * Are there any field errors?
227      * @return <code>true</code> if there are any errors associated with a field
228      * @see #hasGlobalErrors() 
229      */
230     boolean hasFieldErrors();
231 
232     /**
233      * Return the number of errors associated with a field.
234      * @return the number of errors associated with a field
235      * @see #getGlobalErrorCount() 
236      */
237     int getFieldErrorCount();
238 
239     /**
240      * Get all errors associated with a field.
241      * @return a List of {@link FieldError} instances
242      */
243     List   getFieldErrors();
244 
245     /**
246      * Get the <i>first</i> error associated with a field, if any.
247      * @return the field-specific error, or <code>null</code>
248      */
249     FieldError getFieldError();
250 
251     /**
252      * Are there any errors associated with the given field?
253      * @param field the field name
254      * @return <code>true</code> if there were any errors associated with the given field
255      */
256     boolean hasFieldErrors(String   field);
257 
258     /**
259      * Return the number of errors associated with the given field.
260      * @param field the field name
261      * @return the number of errors associated with the given field
262      */
263     int getFieldErrorCount(String   field);
264 
265     /**
266      * Get all errors associated with the given field.
267      * <p>Implementations should support not only full field names like
268      * "name" but also pattern matches like "na*" or "address.*".
269      * @param field the field name
270      * @return a List of {@link FieldError} instances
271      */
272     List   getFieldErrors(String   field);
273 
274     /**
275      * Get the first error associated with the given field, if any.
276      * @param field the field name
277      * @return the field-specific error, or <code>null</code>
278      */
279     FieldError getFieldError(String   field);
280 
281     /**
282      * Return the current value of the given field, either the current
283      * bean property value or a rejected update from the last binding.
284      * <p>Allows for convenient access to user-specified field values,
285      * even if there were type mismatches.
286      * @param field the field name
287      * @return the current value of the given field
288      */
289     Object   getFieldValue(String   field);
290 
291     /**
292      * Return the type of a given field.
293      * <p>Implementations should be able to determine the type even
294      * when the field value is <code>null</code>, for example from some
295      * associated descriptor.
296      * @param field the field name
297      * @return the type of the field, or <code>null</code> if not determinable
298      */
299     Class   getFieldType(String   field);
300 
301 }
302
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags