diff --git a/src/java/org/apache/commons/collections/BeanMap.java b/src/java/org/apache/commons/collections/BeanMap.java
index 0b01e7f25..c5be34e55 100644
--- a/src/java/org/apache/commons/collections/BeanMap.java
+++ b/src/java/org/apache/commons/collections/BeanMap.java
@@ -1,5 +1,5 @@
/*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BeanMap.java,v 1.16 2003/02/19 20:14:25 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BeanMap.java,v 1.17 2003/03/03 19:41:29 scolebourne Exp $
* ====================================================================
*
* The Apache Software License, Version 1.1
@@ -82,7 +82,7 @@ import java.util.Set;
* property is considered non existent in the Map
*
* @since Commons Collections 1.0
- * @version $Revision: 1.16 $ $Date: 2003/02/19 20:14:25 $
+ * @version $Revision: 1.17 $ $Date: 2003/03/03 19:41:29 $
*
* @author James Strachan
* @author Stephen Colebourne
@@ -96,13 +96,13 @@ public class BeanMap extends AbstractMap implements Cloneable {
private transient HashMap types = new HashMap();
/**
- * An empty array. Used to invoke accessors via reflection.
+ * An empty array. Used to invoke accessors via reflection.
*/
public static final Object[] NULL_ARGUMENTS = {};
/**
- * Maps primitive Class types to transformers. The transformer
- * transform strings into the appropriate primitive wrapper.
+ * Maps primitive Class types to transformers. The transformer
+ * transform strings into the appropriate primitive wrapper.
*/
public static HashMap defaultTransformers = new HashMap();
@@ -178,17 +178,17 @@ public class BeanMap extends AbstractMap implements Cloneable {
//-------------------------------------------------------------------------
/**
- * Constructs a new empty BeanMap
.
+ * Constructs a new empty BeanMap
.
*/
public BeanMap() {
}
/**
- * Constructs a new BeanMap
that operates on the
- * specified bean. If the given bean is null
, then
- * this map will be empty.
+ * Constructs a new BeanMap
that operates on the
+ * specified bean. If the given bean is null
, then
+ * this map will be empty.
*
- * @param bean the bean for this map to operate on
+ * @param bean the bean for this map to operate on
*/
public BeanMap(Object bean) {
this.bean = bean;
@@ -199,29 +199,28 @@ public class BeanMap extends AbstractMap implements Cloneable {
//-------------------------------------------------------------------------
/**
- * Clone this bean map using the following process:
+ * Clone this bean map using the following process:
*
- *
clear()
differs from the Map contract in that
- * the mappings are not actually removed from the map (the mappings for a
- * BeanMap are fixed).
- **/
+ * This method reinitializes the bean map to have default values for the
+ * bean's properties. This is accomplished by constructing a new instance
+ * of the bean which the map uses as its underlying data source. This
+ * behavior for clear()
differs from the Map contract in that
+ * the mappings are not actually removed from the map (the mappings for a
+ * BeanMap are fixed).
+ */
public void clear() {
if(bean == null) return;
@@ -310,44 +309,52 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Returns true if the bean defines a property with the given name.
- * The given name must be a String
; if not, this method
- * returns false. This method will also return false if the bean
- * does not define a property with that name.
+ * Returns true if the bean defines a property with the given name.
+ *
+ * The given name must be a String
; if not, this method
+ * returns false. This method will also return false if the bean
+ * does not define a property with that name.
+ *
+ * Write-only properties will not be matched as the test operates against
+ * property read methods.
*
- * @param name the name of the property to check
- * @return false if the given name is null or is not a String
;
- * false if the bean does not define a property with that name; or
- * true if the bean does define a property with that name
+ * @param name the name of the property to check
+ * @return false if the given name is null or is not a String
;
+ * false if the bean does not define a property with that name; or
+ * true if the bean does define a property with that name
*/
public boolean containsKey(Object name) {
- Method method = getReadMethod( name );
+ Method method = getReadMethod(name);
return method != null;
}
/**
- * Returns true if the bean defines a property whose current value is
- * the given object.
+ * Returns true if the bean defines a property whose current value is
+ * the given object.
*
- * @param value the value to check
- * @return false true if the bean has at least one property whose
- * current value is that object, false otherwise
+ * @param value the value to check
+ * @return false true if the bean has at least one property whose
+ * current value is that object, false otherwise
*/
public boolean containsValue(Object value) {
// use default implementation
- return super.containsValue( value );
+ return super.containsValue(value);
}
/**
- * Returns the value of the bean's property with the given name.
- * The given name must be a {@link String} and must not be
- * null; otherwise, this method returns null
.
- * If the bean defines a property with the given name, the value of
- * that property is returned. Otherwise, null
is
- * returned.
+ * Returns the value of the bean's property with the given name.
+ *
+ * The given name must be a {@link String} and must not be
+ * null; otherwise, this method returns null
.
+ * If the bean defines a property with the given name, the value of
+ * that property is returned. Otherwise, null
is
+ * returned.
+ *
+ * Write-only properties will not be matched as the test operates against + * property read methods. * - * @param name the name of the property whose value to return - * @return the value of the property with that name + * @param name the name of the property whose value to return + * @return the value of the property with that name */ public Object get(Object name) { if ( bean != null ) { @@ -374,15 +381,15 @@ public class BeanMap extends AbstractMap implements Cloneable { } /** - * Sets the bean property with the given name to the given value. + * Sets the bean property with the given name to the given value. * - * @param name the name of the property to set - * @param value the value to set that property to - * @return the previous value of that property - * @throws IllegalArgumentException if the given name is null; - * if the given name is not a {@link String}; if the bean doesn't - * define a property with that name; or if the bean property with - * that name is read-only + * @param name the name of the property to set + * @param value the value to set that property to + * @return the previous value of that property + * @throws IllegalArgumentException if the given name is null; + * if the given name is not a {@link String}; if the bean doesn't + * define a property with that name; or if the bean property with + * that name is read-only */ public Object put(Object name, Object value) throws IllegalArgumentException, ClassCastException { if ( bean != null ) { @@ -412,9 +419,9 @@ public class BeanMap extends AbstractMap implements Cloneable { } /** - * Returns the number of properties defined by the bean. + * Returns the number of properties defined by the bean. * - * @return the number of properties defined by the bean + * @return the number of properties defined by the bean */ public int size() { return readMethods.size(); @@ -423,9 +430,13 @@ public class BeanMap extends AbstractMap implements Cloneable { /** * Get the keys for this BeanMap. + *
+ * Write-only properties are not included in the returned set of
+ * property names, although it is possible to set their value and to get
+ * their type.
*
* @return BeanMap keys. The Set returned by this method is not
- * modifiable.
+ * modifiable.
*/
public Set keySet() {
return Collections.unmodifiableSet(readMethods.keySet());
@@ -435,7 +446,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* Get the mappings for this BeanMap
*
* @return BeanMap mappings. The Set returned by this method
- * is not modifiable.
+ * is not modifiable.
*/
public Set entrySet() {
return Collections.unmodifiableSet(new AbstractSet() {
@@ -471,7 +482,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* Returns the values for the BeanMap.
*
* @return values for the BeanMap. The returned collection is not
- * modifiable.
+ * modifiable.
*/
public Collection values() {
ArrayList answer = new ArrayList( readMethods.size() );
@@ -489,26 +500,28 @@ public class BeanMap extends AbstractMap implements Cloneable {
* Returns the type of the property with the given name.
*
* @param name the name of the property
- * @return the type of the property, or null
if no such
- * property exists
+ * @return the type of the property, or null
if no such
+ * property exists
*/
public Class getType(String name) {
return (Class) types.get( name );
}
/**
- * Convenience method for getting an iterator over the keys.
+ * Convenience method for getting an iterator over the keys.
+ *
+ * Write-only properties will not be returned in the iterator.
*
- * @return an iterator over the keys
+ * @return an iterator over the keys
*/
public Iterator keyIterator() {
return readMethods.keySet().iterator();
}
/**
- * Convenience method for getting an iterator over the values.
+ * Convenience method for getting an iterator over the values.
*
- * @return an iterator over the values
+ * @return an iterator over the values
*/
public Iterator valueIterator() {
final Iterator iter = keyIterator();
@@ -527,9 +540,9 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Convenience method for getting an iterator over the entries.
+ * Convenience method for getting an iterator over the entries.
*
- * @return an iterator over the entries
+ * @return an iterator over the entries
*/
public Iterator entryIterator() {
final Iterator iter = keyIterator();
@@ -553,20 +566,20 @@ public class BeanMap extends AbstractMap implements Cloneable {
//-------------------------------------------------------------------------
/**
- * Returns the bean currently being operated on. The return value may
- * be null if this map is empty.
+ * Returns the bean currently being operated on. The return value may
+ * be null if this map is empty.
*
- * @return the bean being operated on by this map
+ * @return the bean being operated on by this map
*/
public Object getBean() {
return bean;
}
/**
- * Sets the bean to be operated on by this map. The given value may
- * be null, in which case this map will be empty.
+ * Sets the bean to be operated on by this map. The given value may
+ * be null, in which case this map will be empty.
*
- * @param newBean the new bean to operate on
+ * @param newBean the new bean to operate on
*/
public void setBean( Object newBean ) {
bean = newBean;
@@ -598,32 +611,32 @@ public class BeanMap extends AbstractMap implements Cloneable {
//-------------------------------------------------------------------------
/**
- * Returns the accessor for the property with the given name.
+ * Returns the accessor for the property with the given name.
*
- * @param name the name of the property
- * @return null if the name is null; null if the name is not a
- * {@link String}; null if no such property exists; or the accessor
- * method for that property
+ * @param name the name of the property
+ * @return null if the name is null; null if the name is not a
+ * {@link String}; null if no such property exists; or the accessor
+ * method for that property
*/
protected Method getReadMethod( Object name ) {
return (Method) readMethods.get( name );
}
/**
- * Returns the mutator for the property with the given name.
+ * Returns the mutator for the property with the given name.
*
- * @param name the name of the
- * @return null if the name is null; null if the name is not a
- * {@link String}; null if no such property exists; null if the
- * property is read-only; or the mutator method for that property
+ * @param name the name of the
+ * @return null if the name is null; null if the name is not a
+ * {@link String}; null if no such property exists; null if the
+ * property is read-only; or the mutator method for that property
*/
protected Method getWriteMethod( Object name ) {
return (Method) writeMethods.get( name );
}
/**
- * Reinitializes this bean. Called during {@link #setBean(Object)}.
- * Does introspection to find properties.
+ * Reinitializes this bean. Called during {@link #setBean(Object)}.
+ * Does introspection to find properties.
*/
protected void reinitialise() {
readMethods.clear();
@@ -666,13 +679,13 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Called during a successful {@link #put(Object,Object)} operation.
- * Default implementation does nothing. Override to be notified of
- * property changes in the bean caused by this map.
+ * Called during a successful {@link #put(Object,Object)} operation.
+ * Default implementation does nothing. Override to be notified of
+ * property changes in the bean caused by this map.
*
- * @param key the name of the property that changed
- * @param oldValue the old value for that property
- * @param newValue the new value for that property
+ * @param key the name of the property that changed
+ * @param oldValue the old value for that property
+ * @param newValue the new value for that property
*/
protected void firePropertyChange( Object key, Object oldValue, Object newValue ) {
}
@@ -681,17 +694,17 @@ public class BeanMap extends AbstractMap implements Cloneable {
//-------------------------------------------------------------------------
/**
- * Map entry used by {@link BeanMap}.
+ * Map entry used by {@link BeanMap}.
*/
protected static class MyMapEntry extends DefaultMapEntry {
private BeanMap owner;
/**
- * Constructs a new MyMapEntry
.
+ * Constructs a new MyMapEntry
.
*
- * @param owner the BeanMap this entry belongs to
- * @param key the key for this entry
- * @param value the value for this entry
+ * @param owner the BeanMap this entry belongs to
+ * @param key the key for this entry
+ * @param value the value for this entry
*/
protected MyMapEntry( BeanMap owner, Object key, Object value ) {
super( key, value );
@@ -699,10 +712,10 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Sets the value.
+ * Sets the value.
*
- * @param value the new value for the entry
- * @return the old value for the entry
+ * @param value the new value for the entry
+ * @return the old value for the entry
*/
public Object setValue(Object value) {
Object key = getKey();
@@ -716,18 +729,18 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Creates an array of parameters to pass to the given mutator method.
- * If the given object is not the right type to pass to the method
- * directly, it will be converted using {@link #convertType(Class,Object)}.
+ * Creates an array of parameters to pass to the given mutator method.
+ * If the given object is not the right type to pass to the method
+ * directly, it will be converted using {@link #convertType(Class,Object)}.
*
- * @param method the mutator method
- * @param value the value to pass to the mutator method
- * @return an array containing one object that is either the given value
- * or a transformed value
- * @throws IllegalAccessException if {@link #convertType(Class,Object)}
- * raises it
- * @throws IllegalArgumentException if any other exception is raised
- * by {@link #convertType(Class,Object)}
+ * @param method the mutator method
+ * @param value the value to pass to the mutator method
+ * @return an array containing one object that is either the given value
+ * or a transformed value
+ * @throws IllegalAccessException if {@link #convertType(Class,Object)}
+ * raises it
+ * @throws IllegalArgumentException if any other exception is raised
+ * by {@link #convertType(Class,Object)}
*/
protected Object[] createWriteMethodArguments( Method method, Object value ) throws IllegalAccessException, ClassCastException {
try {
@@ -766,7 +779,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* {@link Object#toString() toString()} method, and that string is
* parsed into the correct primitve type using, for instance,
* {@link Integer#valueOf(String)} to convert the string into an
- * int
.
+ * int
.
*
* If no special constructor exists and the given type is not a
* primitive type, this method returns the original value.
@@ -775,12 +788,12 @@ public class BeanMap extends AbstractMap implements Cloneable {
* @param value the value to conert
* @return the converted value
* @throws NumberFormatException if newType is a primitive type, and
- * the string representation of the given value cannot be converted
- * to that type
+ * the string representation of the given value cannot be converted
+ * to that type
* @throws InstantiationException if the constructor found with
- * reflection raises it
+ * reflection raises it
* @throws InvocationTargetExcetpion if the constructor found with
- * reflection raises it
+ * reflection raises it
* @throws IllegalAccessException never
* @throws IllegalArgumentException never
*/
@@ -805,38 +818,36 @@ public class BeanMap extends AbstractMap implements Cloneable {
}
/**
- * Returns a transformer for the given primitive type.
+ * Returns a transformer for the given primitive type.
*
- * @param aType the primitive type whose transformer to return
- * @return a transformer that will convert strings into that type,
- * or null if the given type is not a primitive type
+ * @param aType the primitive type whose transformer to return
+ * @return a transformer that will convert strings into that type,
+ * or null if the given type is not a primitive type
*/
protected Transformer getTypeTransformer( Class aType ) {
return (Transformer) defaultTransformers.get( aType );
}
/**
- * Logs the given exception to System.out
. Used to display
- * warnings while accessing/mutating the bean.
+ * Logs the given exception to System.out
. Used to display
+ * warnings while accessing/mutating the bean.
*
- * @param e the exception to log
+ * @param ex the exception to log
*/
- protected void logInfo(Exception e) {
- // XXXX: should probably use log4j here instead...
- System.out.println( "INFO: Exception: " + e );
+ protected void logInfo(Exception ex) {
+ // Deliberately do not use LOG4J or Commons Logging to avoid dependencies
+ System.out.println( "INFO: Exception: " + ex );
}
/**
- * Logs the given exception to System.err
. Used to display
- * errors while accessing/mutating the bean.
+ * Logs the given exception to System.err
. Used to display
+ * errors while accessing/mutating the bean.
*
- * @param e the exception to log
+ * @param ex the exception to log
*/
- protected void logWarn(Exception e) {
- // XXXX: should probably use log4j here instead...
- System.out.println( "WARN: Exception: " + e );
- e.printStackTrace();
+ protected void logWarn(Exception ex) {
+ // Deliberately do not use LOG4J or Commons Logging to avoid dependencies
+ System.out.println( "WARN: Exception: " + ex );
+ ex.printStackTrace();
}
}
-
-