001: /*
002: * Copyright 2002-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.beans;
018:
019: import java.util.Map;
020:
021: /**
022: * Common interface for classes that can access named properties
023: * (such as bean properties of an object or fields in an object)
024: * Serves as base interface for {@link BeanWrapper}.
025: *
026: * @author Juergen Hoeller
027: * @since 1.1
028: * @see BeanWrapper
029: */
030: public interface PropertyAccessor {
031:
032: /**
033: * Path separator for nested properties.
034: * Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
035: */
036: String NESTED_PROPERTY_SEPARATOR = ".";
037: char NESTED_PROPERTY_SEPARATOR_CHAR = '.';
038:
039: /**
040: * Marker that indicates the start of a property key for an
041: * indexed or mapped property like "person.addresses[0]".
042: */
043: String PROPERTY_KEY_PREFIX = "[";
044: char PROPERTY_KEY_PREFIX_CHAR = '[';
045:
046: /**
047: * Marker that indicates the end of a property key for an
048: * indexed or mapped property like "person.addresses[0]".
049: */
050: String PROPERTY_KEY_SUFFIX = "]";
051: char PROPERTY_KEY_SUFFIX_CHAR = ']';
052:
053: /**
054: * Determine whether the specified property is readable.
055: * <p>Returns <code>false</code> if the property doesn't exist.
056: * @param propertyName the property to check
057: * (may be a nested path and/or an indexed/mapped property)
058: * @return whether the property is readable
059: */
060: boolean isReadableProperty(String propertyName);
061:
062: /**
063: * Determine whether the specified property is writable.
064: * <p>Returns <code>false</code> if the property doesn't exist.
065: * @param propertyName the property to check
066: * (may be a nested path and/or an indexed/mapped property)
067: * @return whether the property is writable
068: */
069: boolean isWritableProperty(String propertyName);
070:
071: /**
072: * Determine the property type for the specified property,
073: * either checking the property descriptor or checking the value
074: * in case of an indexed or mapped element.
075: * @param propertyName the property to check
076: * (may be a nested path and/or an indexed/mapped property)
077: * @return the property type for the particular property,
078: * or <code>null</code> if not determinable
079: * @throws InvalidPropertyException if there is no such property or
080: * if the property isn't readable
081: * @throws PropertyAccessException if the property was valid but the
082: * accessor method failed
083: */
084: Class getPropertyType(String propertyName) throws BeansException;
085:
086: /**
087: * Get the current value of the specified property.
088: * @param propertyName the name of the property to get the value of
089: * (may be a nested path and/or an indexed/mapped property)
090: * @return the value of the property
091: * @throws InvalidPropertyException if there is no such property or
092: * if the property isn't readable
093: * @throws PropertyAccessException if the property was valid but the
094: * accessor method failed
095: */
096: Object getPropertyValue(String propertyName) throws BeansException;
097:
098: /**
099: * Set the specified value as current property value.
100: * @param propertyName the name of the property to set the value of
101: * (may be a nested path and/or an indexed/mapped property)
102: * @param value the new value
103: * @throws InvalidPropertyException if there is no such property or
104: * if the property isn't writable
105: * @throws PropertyAccessException if the property was valid but the
106: * accessor method failed or a type mismatch occured
107: */
108: void setPropertyValue(String propertyName, Object value)
109: 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,
200: boolean ignoreInvalid) throws BeansException;
201:
202: }
|