PropertyAccessor (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.beans

## Interface PropertyAccessor

- All Known Subinterfaces:
    BeanWrapper, ConfigurablePropertyAccessor
  All Known Implementing Classes:
    AbstractPropertyAccessor, BeanWrapperImpl, DirectFieldAccessor

      public interface PropertyAccessor

  Common interface for classes that can access named properties (such as bean properties of an object or fields in an object) Serves as base interface for `BeanWrapper`.
  Since:
    1.1
  Author:
    Juergen Hoeller
  See Also:
    `BeanWrapper`, `PropertyAccessorFactory.forBeanPropertyAccess(java.lang.Object)`, `PropertyAccessorFactory.forDirectFieldAccess(java.lang.Object)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `NESTED_PROPERTY_SEPARATOR` Path separator for nested properties.
    `static char` | `NESTED_PROPERTY_SEPARATOR_CHAR`
    `static String` | `PROPERTY_KEY_PREFIX` Marker that indicates the start of a property key for an indexed or mapped property like "person.addresses[0]".
    `static char` | `PROPERTY_KEY_PREFIX_CHAR`
    `static String` | `PROPERTY_KEY_SUFFIX` Marker that indicates the end of a property key for an indexed or mapped property like "person.addresses[0]".
    `static char` | `PROPERTY_KEY_SUFFIX_CHAR`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Class` | `getPropertyType(String propertyName)` Determine the property type for the specified property, either checking the property descriptor or checking the value in case of an indexed or mapped element.
    `TypeDescriptor` | `getPropertyTypeDescriptor(String propertyName)` Return a type descriptor for the specified property: preferably from the read method, falling back to the write method.
    `Object` | `getPropertyValue(String propertyName)` Get the current value of the specified property.
    `boolean` | `isReadableProperty(String propertyName)` Determine whether the specified property is readable.
    `boolean` | `isWritableProperty(String propertyName)` Determine whether the specified property is writable.
    `void` | `setPropertyValue(PropertyValue pv)` Set the specified value as current property value.
    `void` | `setPropertyValue(String propertyName, Object value)` Set the specified value as current property value.
    `void` | `setPropertyValues(Map<?,?> map)` Perform a batch update from a Map.
    `void` | `setPropertyValues(PropertyValues pvs)` The preferred way to perform a batch update.
    `void` | `setPropertyValues(PropertyValues pvs, boolean ignoreUnknown)` Perform a batch update with more control over behavior.
    `void` | `setPropertyValues(PropertyValues pvs, boolean ignoreUnknown, boolean ignoreInvalid)` Perform a batch update with full control over behavior.

- - ### Field Detail

    - #### NESTED_PROPERTY_SEPARATOR

          static final String NESTED_PROPERTY_SEPARATOR

      Path separator for nested properties. Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
      See Also:
        Constant Field Values

    - #### NESTED_PROPERTY_SEPARATOR_CHAR

          static final char NESTED_PROPERTY_SEPARATOR_CHAR

      See Also:
        Constant Field Values

    - #### PROPERTY_KEY_PREFIX

          static final String PROPERTY_KEY_PREFIX

      Marker that indicates the start of a property key for an indexed or mapped property like "person.addresses[0]".
      See Also:
        Constant Field Values

    - #### PROPERTY_KEY_PREFIX_CHAR

          static final char PROPERTY_KEY_PREFIX_CHAR

      See Also:
        Constant Field Values

    - #### PROPERTY_KEY_SUFFIX

          static final String PROPERTY_KEY_SUFFIX

      Marker that indicates the end of a property key for an indexed or mapped property like "person.addresses[0]".
      See Also:
        Constant Field Values

    - #### PROPERTY_KEY_SUFFIX_CHAR

          static final char PROPERTY_KEY_SUFFIX_CHAR

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isReadableProperty

          boolean isReadableProperty(String propertyName)

      Determine whether the specified property is readable.

      Returns `false` if the property doesn't exist.

      Parameters:
        `propertyName` - the property to check (may be a nested path and/or an indexed/mapped property)
      Returns:
        whether the property is readable

    - #### isWritableProperty

          boolean isWritableProperty(String propertyName)

      Determine whether the specified property is writable.

      Returns `false` if the property doesn't exist.

      Parameters:
        `propertyName` - the property to check (may be a nested path and/or an indexed/mapped property)
      Returns:
        whether the property is writable

    - #### getPropertyType

          Class getPropertyType(String propertyName)
                                throws BeansException

      Determine the property type for the specified property, either checking the property descriptor or checking the value in case of an indexed or mapped element.
      Parameters:
        `propertyName` - the property to check (may be a nested path and/or an indexed/mapped property)
      Returns:
        the property type for the particular property, or `null` if not determinable
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't readable
        `PropertyAccessException` - if the property was valid but the accessor method failed
        `BeansException`

    - #### getPropertyTypeDescriptor

          TypeDescriptor getPropertyTypeDescriptor(String propertyName)
                                                   throws BeansException

      Return a type descriptor for the specified property: preferably from the read method, falling back to the write method.
      Parameters:
        `propertyName` - the property to check (may be a nested path and/or an indexed/mapped property)
      Returns:
        the property type for the particular property, or `null` if not determinable
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't readable
        `BeansException`

    - #### getPropertyValue

          Object getPropertyValue(String propertyName)
                                  throws BeansException

      Get the current value of the specified property.
      Parameters:
        `propertyName` - the name of the property to get the value of (may be a nested path and/or an indexed/mapped property)
      Returns:
        the value of the property
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't readable
        `PropertyAccessException` - if the property was valid but the accessor method failed
        `BeansException`

    - #### setPropertyValue

          void setPropertyValue(String propertyName,
                              Object value)
                                throws BeansException

      Set the specified value as current property value.
      Parameters:
        `propertyName` - the name of the property to set the value of (may be a nested path and/or an indexed/mapped property)
        `value` - the new value
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyAccessException` - if the property was valid but the accessor method failed or a type mismatch occured
        `BeansException`

    - #### setPropertyValue

          void setPropertyValue(PropertyValue pv)
                                throws BeansException

      Set the specified value as current property value.
      Parameters:
        `pv` - an object containing the new property value
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyAccessException` - if the property was valid but the accessor method failed or a type mismatch occured
        `BeansException`

    - #### setPropertyValues

          void setPropertyValues(Map<?,?> map)
                                 throws BeansException

      Perform a batch update from a Map.

      Bulk updates from PropertyValues are more powerful: This method is provided for convenience. Behavior will be identical to that of the `setPropertyValues(PropertyValues)` method.

      Parameters:
        `map` - Map to take properties from. Contains property value objects, keyed by property name
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyBatchUpdateException` - if one or more PropertyAccessExceptions occured for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.
        `BeansException`

    - #### setPropertyValues

          void setPropertyValues(PropertyValues pvs)
                                 throws BeansException

      The preferred way to perform a batch update.

      Note that performing a batch update differs from performing a single update, in that an implementation of this class will continue to update properties if a recoverable error (such as a type mismatch, but not an invalid field name or the like) is encountered, throwing a `PropertyBatchUpdateException` containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated remain changed.

      Does not allow unknown fields or invalid fields.

      Parameters:
        `pvs` - PropertyValues to set on the target object
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyBatchUpdateException` - if one or more PropertyAccessExceptions occured for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.
        `BeansException`
      See Also:
        `setPropertyValues(PropertyValues, boolean, boolean)`

    - #### setPropertyValues

          void setPropertyValues(PropertyValues pvs,
                               boolean ignoreUnknown)
                                 throws BeansException

      Perform a batch update with more control over behavior.

      Note that performing a batch update differs from performing a single update, in that an implementation of this class will continue to update properties if a recoverable error (such as a type mismatch, but not an invalid field name or the like) is encountered, throwing a `PropertyBatchUpdateException` containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated remain changed.

      Parameters:
        `pvs` - PropertyValues to set on the target object
        `ignoreUnknown` - should we ignore unknown properties (not found in the bean)
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyBatchUpdateException` - if one or more PropertyAccessExceptions occured for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.
        `BeansException`
      See Also:
        `setPropertyValues(PropertyValues, boolean, boolean)`

    - #### setPropertyValues

          void setPropertyValues(PropertyValues pvs,
                               boolean ignoreUnknown,
                               boolean ignoreInvalid)
                                 throws BeansException

      Perform a batch update with full control over behavior.

      Note that performing a batch update differs from performing a single update, in that an implementation of this class will continue to update properties if a recoverable error (such as a type mismatch, but not an invalid field name or the like) is encountered, throwing a `PropertyBatchUpdateException` containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated remain changed.

      Parameters:
        `pvs` - PropertyValues to set on the target object
        `ignoreUnknown` - should we ignore unknown properties (not found in the bean)
        `ignoreInvalid` - should we ignore invalid properties (found but not accessible)
      Throws:
        `InvalidPropertyException` - if there is no such property or if the property isn't writable
        `PropertyBatchUpdateException` - if one or more PropertyAccessExceptions occured for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.
        `BeansException`