Author: britter
Date: Sun Feb 17 12:55:44 2013
New Revision: 1447015
URL: http://svn.apache.org/r1447015
Log:
Provide JavaDoc for BeanAccessor - no functional changes
Modified:
commons/sandbox/beanutils2/trunk/src/main/java/org/apache/commons/beanutils2/BeanAccessor.java
Modified:
commons/sandbox/beanutils2/trunk/src/main/java/org/apache/commons/beanutils2/BeanAccessor.java
URL:
http://svn.apache.org/viewvc/commons/sandbox/beanutils2/trunk/src/main/java/org/apache/commons/beanutils2/BeanAccessor.java?rev=1447015&r1=1447014&r2=1447015&view=diff
==============================================================================
---
commons/sandbox/beanutils2/trunk/src/main/java/org/apache/commons/beanutils2/BeanAccessor.java
(original)
+++
commons/sandbox/beanutils2/trunk/src/main/java/org/apache/commons/beanutils2/BeanAccessor.java
Sun Feb 17 12:55:44 2013
@@ -21,27 +21,103 @@ package org.apache.commons.beanutils2;
import java.util.Map;
+/**
+ * <p>
+ * Provides access to properties and methods of a bean.
+ * </p>
+ *
+ * @param <B> the type of the bean this BeanAcessor is associated with.
+ */
public interface BeanAccessor<B>
{
// get
+ /**
+ * <p>
+ * Gets the value of the property with name {@code propertyName} from the
bean wrapped by this BeanAccessor. The
+ * value will be wrapped in a {@code BeanAccessor} to enable fluent calls.
+ * </p>
+ *
+ * @param propertyName the name of the property to get the value from.
Must not be {@code null}!
+ * @return a {@code BeanAccessor} wrapping the properties value.
+ */
BeanAccessor<?> get( String propertyName );
+ /**
+ * <p>
+ * Selects the indexed property with name {@code propertyName} from the
bean wrapped by this {@code BeanAccessor}. A
+ * {@link IndexedPropertyGetterAccessor} will be returned for specifying
the index to return the value of.
+ * </p>
+ *
+ * @param propertyName the name of the indexed property to select. Must
not be {@code null}!
+ * @return a {@link IndexedPropertyGetterAccessor} for specifying the
index to return the value of.
+ */
IndexedPropertyGetterAccessor<?> getIndexed( String propertyName );
+ /**
+ * <p>
+ * Selects the mapped property with name {@code propertyName} from the
bean wrapped by this {@code BeanAccessor}. A
+ * {@link MappedPropertyGetterAccessor} will be returned for specifying
the key to return the value of.
+ * </p>
+ *
+ * @param propertyName the name of the mapped property to select. Must not
be {@code null}!
+ * @return a {@link MappedPropertyGetterAccessor} for specifying the key
to return the value of.
+ */
MappedPropertyGetterAccessor getMapped( String propertyName );
+ /**
+ * <p>
+ * Gets the bean wrapped by this {@code BeanAccessor}.
+ * </p>
+ *
+ * @return the bean.
+ */
B get();
+ /**
+ * <p>
+ * Tries to cast the bean wrapped by this {@code BeanAccessor} an returns
the result.
+ * </p>
+ *
+ * @param <V> the type to cast the wrapped bean to.
+ * @return the wrapped bean, casted to type {@code V}.
+ */
<V> V cast();
// set
+ /**
+ * <p>
+ * Selects the property with name {@code propertyName} for setting a new
value. A {@link BeanPropertySetter} will be
+ * returned for specifying the new value.
+ * </p>
+ *
+ * @param propertyName the name of the property to select for setting a
new value. Must not be {@code null}.
+ * @return a {@link BeanPropertySetter} for setting a new value.
+ */
BeanPropertySetter<B> set( String propertyName );
+ /**
+ * <p>
+ * Selects the indexed property with name {@code propertyName} for setting
a new value. A
+ * {@link IndexedPropertySetterAccessor} will be returned for specifying
the index to set a new value to.
+ * </p>
+ *
+ * @param propertyName the name of the indexed property to select for
setting a new value. Must not be {@code null}.
+ * @return a {@link IndexedPropertySetterAccessor} for setting a new value.
+ */
IndexedPropertySetterAccessor<B> setIndexed( String propertyName );
+ /**
+ * <p>
+ * Selects the mapped property with name {@code propertyName} for setting
a new value. A
+ * {@link MappedPropertySetterAccessor} will be returned for specifying
the key to set a new value to.
+ * </p>
+ *
+ * @param propertyName the name of the mapped property to select for
setting a new value. Must not be {@code null}.
+ * @return a {@link MappedPropertySetterAccessor} for setting a new value.
+ */
MappedPropertySetterAccessor<B> setMapped( String propertyName );
// clone
@@ -57,55 +133,49 @@ public interface BeanAccessor<B>
* </p>
*
* @return the cloned bean
- * @throws IllegalAccessException if the caller does not have access to
the property accessor method
- * @throws InstantiationException if a new instance of the bean's class
cannot be instantiated
- * @throws NoSuchMethodException if an accessor method for this property
cannot be found
- * @throws IntrospectionException
*/
B cloneBean();
/**
- * <p>Copies property values from the bean wrapped by this BeanAccessor
- * to target for all cases where the property names are the same. For each
- * property, a conversion is attempted as necessary.</p>
- *
- * <p><strong>Note</strong> that this method is intended to perform a
- * "shallow copy" of the properties and so complex properties (for example,
- * nested ones) will not be copied.</p>
- *
+ * <p>
+ * Copies property values from the bean wrapped by this {@code
BeanAccessor} to {@code target} for all cases where
+ * the property names are the same. For each property, a conversion is
attempted as necessary.
+ * </p>
+ * <p>
+ * <strong>Note</strong> that this method is intended to perform a
"shallow copy" of the properties and so complex
+ * properties (for example, nested ones) will not be copied.
+ * </p>
* <strong>TODO</strong> should we implement something like the following?
- * <p>If you know that no type conversions are required, the
- * <code>copyProperties()</code> method in {@link PropertyUtils} will
- * execute faster than this method.</p>
- *
- * <p><strong>FIXME</strong> - Indexed and mapped properties that do not
- * have getter and setter methods for the underlying array or Map are not
- * copied by this method.</p>
+ * <p>
+ * If you know that no type conversions are required, the
<code>copyProperties()</code> method in
+ * {@link PropertyUtils} will execute faster than this method.
+ * </p>
+ * <p>
+ * <strong>FIXME</strong> - Indexed and mapped properties that do not have
getter and setter methods for the
+ * underlying array or Map are not copied by this method.
+ * </p>
*
+ * @param <T> the type of the bean to copy properties to.
* @param target the target to copy properties to from the wrapped bean
- * @throws IllegalAccessException if the caller does not have access to
any of the property accessor methods
- * @throws IntrospectionException TODO
- * @throws NoSuchMethodException if an accessor method for a property
cannot be found
*/
<T extends B> void copyPropertiesTo( T target );
// description
/**
- * <p>Return the entire set of properties for which the specified bean
- * provides a read method. This map contains the property names as keys
- * and the property values as values, for all properties the bean provides
- * a read method for (i.e. where the getReadMethod() returns non-null).</p>
- *
- * <p>This map can be fed back to a call to
- * <code>BeanAccessor.populate()</code> to reconstitute the same set of
- * properties, modulo differences for read-only and write-only
- * properties, but only if there are no indexed properties.</p>
- *
- * <p><strong>Warning:</strong> if any of the bean property implementations
- * contain (directly or indirectly) a call to this method then
- * a stack overflow may result. For example:
- * <code><pre>
+ * <p>
+ * Return the entire set of properties for which the specified bean
provides a read method. This map contains the
+ * property names as keys and the property values as values, for all
properties the bean provides a read method for
+ * (i.e. where the getReadMethod() returns non-null).
+ * </p>
+ * <p>
+ * This map can be fed back to a call to
<code>BeanAccessor.populate()</code> to reconstitute the same set of
+ * properties, modulo differences for read-only and write-only properties,
but only if there are no indexed
+ * properties.
+ * </p>
+ * <p>
+ * <strong>Warning:</strong> if any of the bean property implementations
contain (directly or indirectly) a call to
+ * this method then a stack overflow may result. For example: <code><pre>
* class MyBean
* {
* public Map<String, Object> getParameterMap()
@@ -113,46 +183,46 @@ public interface BeanAccessor<B>
* on( this ).describe;
* }
* }
- * </pre></code>
- * will result in an infinite regression when <code>getParametersMap</code>
- * is called. It is recommended that such methods are given alternative
- * names (for example, <code>parametersMap</code>).
+ * </pre></code> will result in an infinite regression when
<code>getParametersMap</code> is called. It is
+ * recommended that such methods are given alternative names (for example,
<code>parametersMap</code>).
* </p>
- * @return Map that contains the property names as keys and property
values as values.
*
- * TODO update to Wrapper Exceptions
- * @exception IllegalAccessException if the caller does not have
- * access to the property accessor method
- * TODO what is meant with "this property" in the context of describe()?
- * @exception NoSuchMethodException if an accessor method for this
- * property cannot be found
- * @throws IntrospectionException TODO
+ * @return Map that contains the property names as keys and property
values as values.
*/
Map<String, Object> describe();
+ /**
+ * <p>
+ * Populate {@code properties} to the bean wrapped by this {@code
BeanAccessor}. The map of properties passed to
+ * this method has to specify names of properties to set and corresponding
values as key-value-pairs.
+ * </p>
+ *
+ * @param properties Map keyed by property name, with the corresponding
value to be set.
+ * Must not be {@code null}.
+ */
void populate( Map<String, Object> properties );
// methods invocation
/**
- * Invokes the method with name {@code methodName}. Arguments are casted
to fit the methods signature, if possible.
+ * <p>
+ * Invokes the method with name {@code methodName}. An {@link
ArgumentsAccessor} will be returned to specify the
+ * parameters for the method invocation.
+ * </p>
*
* @param methodName the name of the method to invoke. Must not be {@code
null}!
- * @return a {@link ArgumentsAccessor} to specify any arguments
- * @throws NoSuchMethodException if there no method with the name {@code
methodName} can be found or the arguments
- * can not be casted so set they fit the methods signature.
- * @throws IllegalAccessException if the method is not visible to the
caller
+ * @return an {@link ArgumentsAccessor} to specify arguments for the
method invocation.
*/
ArgumentsAccessor invoke( String methodName );
/**
- * Invoke the method with name {@code methodName} and the exact arguments.
+ * <p>
+ * Invokes the method with name {@code methodName} and the exact
arguments. An {@link ArgumentsAccessor} will be
+ * returned to specify the parameters for the method invocation.
+ * </p>
*
* @param methodName the name of the method to invoke. Must not be {@code
null}!
* @return a {@link ArgumentsAccessor} to specify any arguments
- * @throws NoSuchMethodException if no method with the name {@code
methodName} cand be found that accepts the exact
- * arguments.
- * @throws IllegalAccessException if the method is not visible to the
caller
*/
ArgumentsAccessor invokeExact( String methodName );
