org.springframework/spring-beans/5.1.5.RELEASE : org/springframework/beans/PropertyAccessor.java

PropertyAccessor

https://github.com/spring-projects/spring-framework: Spring Beans (Spring IO)

Apache License, Version 2.0

Juergen Hoeller

/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans;

import java.util.Map;

import org.springframework.core.convert.TypeDescriptor;
import org.springframework.lang.Nullable;

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. 
Author: Juergen Hoeller
See Also: BeanWrapper
PropertyAccessorFactory.forBeanPropertyAccess
PropertyAccessorFactory.forDirectFieldAccess
Since: 1.1/**
 * 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 {@link BeanWrapper}.
 *
 * @author Juergen Hoeller
 * @since 1.1
 * @see BeanWrapper
 * @see PropertyAccessorFactory#forBeanPropertyAccess
 * @see PropertyAccessorFactory#forDirectFieldAccess
 */
public interface PropertyAccessor {

	Path separator for nested properties.
Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
/**
	 * Path separator for nested properties.
	 * Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
	 */
	String NESTED_PROPERTY_SEPARATOR = ".";

	Path separator for nested properties.
Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
/**
	 * Path separator for nested properties.
	 * Follows normal Java conventions: getFoo().getBar() would be "foo.bar".
	 */
	char NESTED_PROPERTY_SEPARATOR_CHAR = '.';

	Marker that indicates the start of a property key for an
indexed or mapped property like "person.addresses[0]".
/**
	 * Marker that indicates the start of a property key for an
	 * indexed or mapped property like "person.addresses[0]".
	 */
	String PROPERTY_KEY_PREFIX = "[";

	Marker that indicates the start of a property key for an
indexed or mapped property like "person.addresses[0]".
/**
	 * Marker that indicates the start of a property key for an
	 * indexed or mapped property like "person.addresses[0]".
	 */
	char PROPERTY_KEY_PREFIX_CHAR = '[';

	Marker that indicates the end of a property key for an
indexed or mapped property like "person.addresses[0]".
/**
	 * Marker that indicates the end of a property key for an
	 * indexed or mapped property like "person.addresses[0]".
	 */
	String PROPERTY_KEY_SUFFIX = "]";

	Marker that indicates the end of a property key for an
indexed or mapped property like "person.addresses[0]".
/**
	 * Marker that indicates the end of a property key for an
	 * indexed or mapped property like "person.addresses[0]".
	 */
	char PROPERTY_KEY_SUFFIX_CHAR = ']';


	Determine whether the specified property is readable.
Returns false if the property doesn't exist. 
Params: propertyName – the property to check
(may be a nested path and/or an indexed/mapped property)
Returns: whether the property is readable/**
	 * Determine whether the specified property is readable.
	 * <p>Returns {@code false} if the property doesn't exist.
	 * @param propertyName the property to check
	 * (may be a nested path and/or an indexed/mapped property)
	 * @return whether the property is readable
	 */
	boolean isReadableProperty(String propertyName);

	Determine whether the specified property is writable.
Returns false if the property doesn't exist. 
Params: propertyName – the property to check
(may be a nested path and/or an indexed/mapped property)
Returns: whether the property is writable/**
	 * Determine whether the specified property is writable.
	 * <p>Returns {@code false} if the property doesn't exist.
	 * @param propertyName the property to check
	 * (may be a nested path and/or an indexed/mapped property)
	 * @return whether the property is writable
	 */
	boolean isWritableProperty(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.
Params: propertyName – the property to check
(may be a nested path and/or an indexed/mapped property)
Throws: PropertyAccessException – if the property was valid but the
accessor method failed
Returns: the property type for the particular property, or null if not determinable/**
	 * 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.
	 * @param propertyName the property to check
	 * (may be a nested path and/or an indexed/mapped property)
	 * @return the property type for the particular property,
	 * or {@code null} if not determinable
	 * @throws PropertyAccessException if the property was valid but the
	 * accessor method failed
	 */
	@Nullable
	Class<?> getPropertyType(String propertyName) throws BeansException;

	Return a type descriptor for the specified property:
preferably from the read method, falling back to the write method.
Params: propertyName – the property to check
(may be a nested path and/or an indexed/mapped property)
Throws: PropertyAccessException – if the property was valid but the
accessor method failed
Returns: the property type for the particular property, or null if not determinable/**
	 * Return a type descriptor for the specified property:
	 * preferably from the read method, falling back to the write method.
	 * @param propertyName the property to check
	 * (may be a nested path and/or an indexed/mapped property)
	 * @return the property type for the particular property,
	 * or {@code null} if not determinable
	 * @throws PropertyAccessException if the property was valid but the
	 * accessor method failed
	 */
	@Nullable
	TypeDescriptor getPropertyTypeDescriptor(String propertyName) throws BeansException;

	Get the current value of the specified property.
Params: propertyName – the name of the property to get the value of
(may be a nested path and/or an indexed/mapped 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
Returns: the value of the property/**
	 * Get the current value of the specified property.
	 * @param propertyName the name of the property to get the value of
	 * (may be a nested path and/or an indexed/mapped property)
	 * @return the value of the property
	 * @throws InvalidPropertyException if there is no such property or
	 * if the property isn't readable
	 * @throws PropertyAccessException if the property was valid but the
	 * accessor method failed
	 */
	@Nullable
	Object getPropertyValue(String propertyName) throws BeansException;

	Set the specified value as current property value.
Params: 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 occurred/**
	 * Set the specified value as current property value.
	 * @param propertyName the name of the property to set the value of
	 * (may be a nested path and/or an indexed/mapped property)
	 * @param value the new value
	 * @throws InvalidPropertyException if there is no such property or
	 * if the property isn't writable
	 * @throws PropertyAccessException if the property was valid but the
	 * accessor method failed or a type mismatch occurred
	 */
	void setPropertyValue(String propertyName, @Nullable Object value) throws BeansException;

	Set the specified value as current property value.
Params: 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 occurred/**
	 * Set the specified value as current property value.
	 * @param pv an object containing the new property value
	 * @throws InvalidPropertyException if there is no such property or
	 * if the property isn't writable
	 * @throws PropertyAccessException if the property was valid but the
	 * accessor method failed or a type mismatch occurred
	 */
	void setPropertyValue(PropertyValue pv) 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. 
Params: map – a 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
occurred for specific properties during the batch update. This exception bundles
all individual PropertyAccessExceptions. All other properties will have been
successfully updated./**
	 * Perform a batch update from a Map.
	 * <p>Bulk updates from PropertyValues are more powerful: This method is
	 * provided for convenience. Behavior will be identical to that of
	 * the {@link #setPropertyValues(PropertyValues)} method.
	 * @param map a 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
	 * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
	 * occurred for specific properties during the batch update. This exception bundles
	 * all individual PropertyAccessExceptions. All other properties will have been
	 * successfully updated.
	 */
	void setPropertyValues(Map<?, ?> map) 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.
Params: pvs – a 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
occurred for specific properties during the batch update. This exception bundles
all individual PropertyAccessExceptions. All other properties will have been
successfully updated.
See Also: setPropertyValues(PropertyValues, boolean, boolean)/**
	 * The preferred way to perform a batch update.
	 * <p>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 <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
	 * invalid field name or the like) is encountered, throwing a
	 * {@link PropertyBatchUpdateException} containing all the individual errors.
	 * This exception can be examined later to see all binding errors.
	 * Properties that were successfully updated remain changed.
	 * <p>Does not allow unknown fields or invalid fields.
	 * @param pvs a PropertyValues to set on the target object
	 * @throws InvalidPropertyException if there is no such property or
	 * if the property isn't writable
	 * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
	 * occurred for specific properties during the batch update. This exception bundles
	 * all individual PropertyAccessExceptions. All other properties will have been
	 * successfully updated.
	 * @see #setPropertyValues(PropertyValues, boolean, boolean)
	 */
	void setPropertyValues(PropertyValues pvs) 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. 
Params: pvs – a 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
occurred for specific properties during the batch update. This exception bundles
all individual PropertyAccessExceptions. All other properties will have been
successfully updated.
See Also: setPropertyValues(PropertyValues, boolean, boolean)/**
	 * Perform a batch update with more control over behavior.
	 * <p>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 <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
	 * invalid field name or the like) is encountered, throwing a
	 * {@link PropertyBatchUpdateException} containing all the individual errors.
	 * This exception can be examined later to see all binding errors.
	 * Properties that were successfully updated remain changed.
	 * @param pvs a PropertyValues to set on the target object
	 * @param 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
	 * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
	 * occurred for specific properties during the batch update. This exception bundles
	 * all individual PropertyAccessExceptions. All other properties will have been
	 * successfully updated.
	 * @see #setPropertyValues(PropertyValues, boolean, boolean)
	 */
	void setPropertyValues(PropertyValues pvs, boolean ignoreUnknown)
			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. 
Params: pvs – a 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
occurred for specific properties during the batch update. This exception bundles
all individual PropertyAccessExceptions. All other properties will have been
successfully updated./**
	 * Perform a batch update with full control over behavior.
	 * <p>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 <b>recoverable</b> error (such as a type mismatch, but <b>not</b> an
	 * invalid field name or the like) is encountered, throwing a
	 * {@link PropertyBatchUpdateException} containing all the individual errors.
	 * This exception can be examined later to see all binding errors.
	 * Properties that were successfully updated remain changed.
	 * @param pvs a PropertyValues to set on the target object
	 * @param ignoreUnknown should we ignore unknown properties (not found in the bean)
	 * @param 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
	 * @throws PropertyBatchUpdateException if one or more PropertyAccessExceptions
	 * occurred for specific properties during the batch update. This exception bundles
	 * all individual PropertyAccessExceptions. All other properties will have been
	 * successfully updated.
	 */
	void setPropertyValues(PropertyValues pvs, boolean ignoreUnknown, boolean ignoreInvalid)
			throws BeansException;

}

Author:	Juergen Hoeller
See Also:	BeanWrapper PropertyAccessorFactory.forBeanPropertyAccess PropertyAccessorFactory.forDirectFieldAccess
Since:	1.1

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

Params:	propertyName – the property to check (may be a nested path and/or an indexed/mapped property)
Throws:	PropertyAccessException – if the property was valid but the accessor method failed
Returns:	the property type for the particular property, or `null` if not determinable

Params:	propertyName – the name of the property to get the value of (may be a nested path and/or an indexed/mapped 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
Returns:	the value of the property

Params:	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 occurred

Params:	map – a 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 occurred for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.

Params:	pvs – a 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 occurred for specific properties during the batch update. This exception bundles all individual PropertyAccessExceptions. All other properties will have been successfully updated.
See Also:	setPropertyValues(PropertyValues, boolean, boolean)

/

org.springframework/ spring-beans/ 5.1.5.RELEASE/ org/springframework/beans/PropertyAccessor.java