You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2003/03/03 20:41:30 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections BeanMap.java
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 BluePhelix@web.de
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 {@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 @@
}
/**
- * 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 @@
}
/**
- * 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
- * {@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 @@
}
/**
- * 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
+ * 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
*/
protected void firePropertyChange( Object key, Object oldValue, Object newValue ) {
}
@@ -681,17 +694,17 @@
//-------------------------------------------------------------------------
/**
- * 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 @@
}
/**
- * 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 {@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)}
+ * 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)}
*/
protected Object[] createWriteMethodArguments( Method method, Object value ) throws IllegalAccessException, ClassCastException {
try {
@@ -766,7 +779,7 @@
* {@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 @@
* @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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org