scolebourne 2003/03/03 11:41:30 Modified: collections/src/java/org/apache/commons/collections BeanMap.java Log: Improve javadoc to clatify role of read-only properties noted by [EMAIL PROTECTED] Revision Changes Path 1.17 +163 -152 jakarta-commons/collections/src/java/org/apache/commons/collections/BeanMap.java Index: BeanMap.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BeanMap.java,v retrieving revision 1.16 retrieving revision 1.17 diff -u -r1.16 -r1.17 --- BeanMap.java 19 Feb 2003 20:14:25 -0000 1.16 +++ BeanMap.java 3 Mar 2003 19:41:29 -0000 1.17 @@ -96,13 +96,13 @@ 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 @@ //------------------------------------------------------------------------- /** - * 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 @@ //------------------------------------------------------------------------- /** - * 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 @@ } /** - * 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 @@ /** - * 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 @@ } /** - * 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. - * - * @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 + * 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 */ 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 @@ } /** - * 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 @@ } /** - * 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 @@ /** * 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 @@ * 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 @@ * 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 @@ * 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 @@ } /** - * 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 @@ //------------------------------------------------------------------------- /** - * 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 @@ //------------------------------------------------------------------------- /** - * 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 - * [EMAIL PROTECTED] 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 + * [EMAIL PROTECTED] 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 - * [EMAIL PROTECTED] 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 + * [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #setBean(Object)}. - * Does introspection to find properties. + * Reinitializes this bean. Called during [EMAIL PROTECTED] #setBean(Object)}. + * Does introspection to find properties. */ protected void reinitialise() { readMethods.clear(); @@ -666,13 +679,13 @@ } /** - * Called during a successful [EMAIL PROTECTED] #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 + * Called during a successful [EMAIL PROTECTED] #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 */ protected void firePropertyChange( Object key, Object oldValue, Object newValue ) { } @@ -681,17 +694,17 @@ //------------------------------------------------------------------------- /** - * Map entry used by [EMAIL PROTECTED] BeanMap}. + * Map entry used by [EMAIL PROTECTED] 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 @@ } /** - * 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 @@ } /** - * 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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #convertType(Class,Object)} - * raises it - * @throws IllegalArgumentException if any other exception is raised - * by [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #convertType(Class,Object)} + * raises it + * @throws IllegalArgumentException if any other exception is raised + * by [EMAIL PROTECTED] #convertType(Class,Object)} */ protected Object[] createWriteMethodArguments( Method method, Object value ) throws IllegalAccessException, ClassCastException { try { @@ -766,7 +779,7 @@ * [EMAIL PROTECTED] Object#toString() toString()} method, and that string is * parsed into the correct primitve type using, for instance, * [EMAIL PROTECTED] 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 @@ * @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 @@ } /** - * 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(); } } - -
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]