PropertyAccessor


1   /*
2    * Copyright 2002-2007 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.beans;
18  
19  import java.util.Map  ;
20  
21  /**
22   * Common interface for classes that can access named properties
23   * (such as bean properties of an object or fields in an object)
24   * Serves as base interface for {@link BeanWrapper}.
25   *
26   * @author Juergen Hoeller
27   * @since 1.1
28   * @see BeanWrapper
29   */
30  public interface PropertyAccessor {
31  
32      /**
33       * Path separator for nested properties.
34       * Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
35       */
36      String   NESTED_PROPERTY_SEPARATOR = ".";
37      char NESTED_PROPERTY_SEPARATOR_CHAR = '.';
38  
39      /**
40       * Marker that indicates the start of a property key for an
41       * indexed or mapped property like "person.addresses[0]".
42       */
43      String   PROPERTY_KEY_PREFIX = "[";
44      char PROPERTY_KEY_PREFIX_CHAR = '[';
45  
46      /**
47       * Marker that indicates the end of a property key for an
48       * indexed or mapped property like "person.addresses[0]".
49       */
50      String   PROPERTY_KEY_SUFFIX = "]";
51      char PROPERTY_KEY_SUFFIX_CHAR = ']';
52  
53  
54      /**
55       * Determine whether the specified property is readable.
56       * <p>Returns <code>false</code> if the property doesn't exist.
57       * @param propertyName the property to check
58       * (may be a nested path and/or an indexed/mapped property)
59       * @return whether the property is readable
60       */
61      boolean isReadableProperty(String   propertyName);
62  
63      /**
64       * Determine whether the specified property is writable.
65       * <p>Returns <code>false</code> if the property doesn't exist.
66       * @param propertyName the property to check
67       * (may be a nested path and/or an indexed/mapped property)
68       * @return whether the property is writable
69       */
70      boolean isWritableProperty(String   propertyName);
71  
72      /**
73       * Determine the property type for the specified property,
74       * either checking the property descriptor or checking the value
75       * in case of an indexed or mapped element.
76       * @param propertyName the property to check
77       * (may be a nested path and/or an indexed/mapped property)
78       * @return the property type for the particular property,
79       * or <code>null</code> if not determinable
80       * @throws InvalidPropertyException if there is no such property or
81       * if the property isn't readable
82       * @throws PropertyAccessException if the property was valid but the
83       * accessor method failed
84       */
85      Class   getPropertyType(String   propertyName) throws BeansException;
86  
87      /**
88       * Get the current value of the specified property.
89       * @param propertyName the name of the property to get the value of
90       * (may be a nested path and/or an indexed/mapped property)
91       * @return the value of the property
92       * @throws InvalidPropertyException if there is no such property or
93       * if the property isn't readable
94       * @throws PropertyAccessException if the property was valid but the
95       * accessor method failed
96       */
97      Object   getPropertyValue(String   propertyName) throws BeansException;
98  
99      /**
100      * Set the specified value as current property value.
101      * @param propertyName the name of the property to set the value of
102      * (may be a nested path and/or an indexed/mapped property)
103      * @param value the new value
104      * @throws InvalidPropertyException if there is no such property or
105      * if the property isn't writable
106      * @throws PropertyAccessException if the property was valid but the
107      * accessor method failed or a type mismatch occured
108      */
109     void setPropertyValue(String   propertyName, Object   value) throws BeansException;
110 
111     /**
112      * Set the specified value as current property value.
113      * @param pv an object containing the new property value
114      * @throws InvalidPropertyException if there is no such property or
115      * if the property isn't writable
116      * @throws PropertyAccessException if the property was valid but the
117      * accessor method failed or a type mismatch occured
118      */
119     void setPropertyValue(PropertyValue pv) throws BeansException;
120 
121     /**
122      * Perform a batch update from a Map.
123      * <p>Bulk updates from PropertyValues are more powerful: This method is
124      * provided for convenience. Behavior will be identical to that of
125      * the {@link #setPropertyValues(PropertyValues)} method.
126      * @param map Map to take properties from. Contains property value objects,
127      * keyed by property name
128      * @throws InvalidPropertyException if there is no such property or
129      * if the property isn't writable
130      * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
131      * occured for specific properties during the batch update. This exception bundles
132      * all individual PropertyAccessExceptions. All other properties will have been
133      * successfully updated.
134      */
135     void setPropertyValues(Map   map) throws BeansException;
136 
137     /**
138      * The preferred way to perform a batch update.
139      * <p>Note that performing a batch update differs from performing a single update,
140      * in that an implementation of this class will continue to update properties
141      * if a <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
142      * invalid field name or the like) is encountered, throwing a
143      * {@link PropertyBatchUpdateException} containing all the individual errors.
144      * This exception can be examined later to see all binding errors.
145      * Properties that were successfully updated remain changed.
146      * <p>Does not allow unknown fields or invalid fields.
147      * @param pvs PropertyValues to set on the target object
148      * @throws InvalidPropertyException if there is no such property or
149      * if the property isn't writable
150      * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
151      * occured for specific properties during the batch update. This exception bundles
152      * all individual PropertyAccessExceptions. All other properties will have been
153      * successfully updated.
154      * @see #setPropertyValues(PropertyValues, boolean, boolean)
155      */
156     void setPropertyValues(PropertyValues pvs) throws BeansException;
157 
158     /**
159      * Perform a batch update with more control over behavior.
160      * <p>Note that performing a batch update differs from performing a single update,
161      * in that an implementation of this class will continue to update properties
162      * if a <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
163      * invalid field name or the like) is encountered, throwing a
164      * {@link PropertyBatchUpdateException} containing all the individual errors.
165      * This exception can be examined later to see all binding errors.
166      * Properties that were successfully updated remain changed.
167      * @param pvs PropertyValues to set on the target object
168      * @param ignoreUnknown should we ignore unknown properties (not found in the bean)
169      * @throws InvalidPropertyException if there is no such property or
170      * if the property isn't writable
171      * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
172      * occured for specific properties during the batch update. This exception bundles
173      * all individual PropertyAccessExceptions. All other properties will have been
174      * successfully updated.
175      * @see #setPropertyValues(PropertyValues, boolean, boolean)
176      */
177     void setPropertyValues(PropertyValues pvs, boolean ignoreUnknown)
178         throws BeansException;
179 
180     /**
181      * Perform a batch update with full control over behavior.
182      * <p>Note that performing a batch update differs from performing a single update,
183      * in that an implementation of this class will continue to update properties
184      * if a <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
185      * invalid field name or the like) is encountered, throwing a
186      * {@link PropertyBatchUpdateException} containing all the individual errors.
187      * This exception can be examined later to see all binding errors.
188      * Properties that were successfully updated remain changed.
189      * @param pvs PropertyValues to set on the target object
190      * @param ignoreUnknown should we ignore unknown properties (not found in the bean)
191      * @param ignoreInvalid should we ignore invalid properties (found but not accessible)
192      * @throws InvalidPropertyException if there is no such property or
193      * if the property isn't writable
194      * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
195      * occured for specific properties during the batch update. This exception bundles
196      * all individual PropertyAccessExceptions. All other properties will have been
197      * successfully updated.
198      */
199     void setPropertyValues(PropertyValues pvs, boolean ignoreUnknown, boolean ignoreInvalid)
200         throws BeansException;
201 
202 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags