From 2298039999ea4b56eb70f686c119974ef94bc95b Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Mon, 3 Mar 2003 19:41:29 +0000
Subject: [PATCH] Improve javadoc to clatify role of read-only properties noted
 by BluePhelix@web.de

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130985 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/commons/collections/BeanMap.java   | 309 +++++++++---------
 1 file changed, 160 insertions(+), 149 deletions(-)

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 <a href="mailto:jstrachan@apache.org">James Strachan</a>
  * @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 <Code>BeanMap</Code>.
+     * Constructs a new empty <code>BeanMap</code>.
      */
     public BeanMap() {
     }
 
     /**
-     *  Constructs a new <Code>BeanMap</Code> that operates on the 
-     *  specified bean.  If the given bean is <Code>null</COde>, then
-     *  this map will be empty.
+     * Constructs a new <code>BeanMap</code> that operates on the 
+     * specified bean.  If the given bean is <code>null</COde>, 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: 
      *
-     *  <ul>
-
-     *  <li>If there is no underlying bean, return a cloned BeanMap without a
-     *  bean.
+     * <ul>
+     * <li>If there is no underlying bean, return a cloned BeanMap without a
+     * bean.
      *
-     *  <li>Since there is an underlying bean, try to instantiate a new bean of
-     *  the same type using Class.newInstance().
+     * <li>Since there is an underlying bean, try to instantiate a new bean of
+     * the same type using Class.newInstance().
      * 
-     *  <li>If the instantiation fails, throw a CloneNotSupportedException
+     * <li>If the instantiation fails, throw a CloneNotSupportedException
      *
-     *  <li>Clone the bean map and set the newly instantiated bean as the
-     *  underyling bean for the bean map.
+     * <li>Clone the bean map and set the newly instantiated bean as the
+     * underyling bean for the bean map.
      *
-     *  <li>Copy each property that is both readable and writable from the
-     *  existing object to a cloned bean map.  
+     * <li>Copy each property that is both readable and writable from the
+     * existing object to a cloned bean map.  
      *
-     *  <li>If anything fails along the way, throw a
-     *  CloneNotSupportedException.
+     * <li>If anything fails along the way, throw a
+     * CloneNotSupportedException.
      *
-     *  <ul>
-     **/
+     * <ul>
+     */
     public Object clone() throws CloneNotSupportedException {
         BeanMap newMap = (BeanMap)super.clone();
 
@@ -272,16 +271,16 @@ public class BeanMap extends AbstractMap implements Cloneable {
     }
 
     /**
-     *  Puts all of the writeable properties from the given BeanMap into this
-     *  BeanMap.  Read-only properties will be ignored.
+     * Puts all of the writeable properties from the given BeanMap into this
+     * BeanMap. Read-only and Write-only properties will be ignored.
      *
-     *  @param map  the BeanMap whose properties to put
+     * @param map  the BeanMap whose properties to put
      */
     public void putAllWriteable(BeanMap map) {
         Iterator readableKeys = map.readMethods.keySet().iterator();
-        while(readableKeys.hasNext()) {
+        while (readableKeys.hasNext()) {
             Object key = readableKeys.next();
-            if(getWriteMethod(key) != null) {
+            if (getWriteMethod(key) != null) {
                 this.put(key, map.get(key));
             }
         }
@@ -289,13 +288,13 @@ public class BeanMap extends AbstractMap implements Cloneable {
 
 
     /**
-     *  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 <code>clear()</code> 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 <code>clear()</code> 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 <Code>String</Code>; 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.
+     * <p>
+     * The given name must be a <code>String</code>; if not, this method
+     * returns false. This method will also return false if the bean
+     * does not define a property with that name.
+     * <p>
+     * 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 <Code>String</Code>;
-     *    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 <code>String</code>;
+     *   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 <Code>null</Code>.
-     *  If the bean defines a property with the given name, the value of
-     *  that property is returned.  Otherwise, <Code>null</Code> is 
-     *  returned.
+     * Returns the value of the bean's property with the given name.
+     * <p>
+     * The given name must be a {@link String} and must not be 
+     * null; otherwise, this method returns <code>null</code>.
+     * If the bean defines a property with the given name, the value of
+     * that property is returned.  Otherwise, <code>null</code> is 
+     * returned.
+     * <p>
+     * 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.
+     * <p>
+     * Write-only properties are <b>not</b> 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 <Code>null</Code> if no such
-     *   property exists
+     * @return  the type of the property, or <code>null</code> 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.
+     * <p>
+     * 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 <Code>MyMapEntry</Code>.
+         * Constructs a new <code>MyMapEntry</code>.
          *
-         *  @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
-     * <Code>int</Code>.<P>
+     * <code>int</code>.<P>
      *
      * 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 <Code>System.out</Code>.  Used to display
-     *  warnings while accessing/mutating the bean.
+     * Logs the given exception to <code>System.out</code>.  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 <Code>System.err</Code>.  Used to display
-     *  errors while accessing/mutating the bean.
+     * Logs the given exception to <code>System.err</code>.  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();
     }
 }
-
-