Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Stephen Colebourne 2003-03-03 19:41:29 +00:00
parent 1a2f50cb26
commit 2298039999
1 changed files with 160 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
src/java/org/apache/commons/collections/BeanMap.java
View File

@ -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 * The Apache Software License, Version 1.1
@ -82,7 +82,7 @@ import java.util.Set;
* property is considered non existent in the Map * property is considered non existent in the Map
* *
* @since Commons Collections 1.0 * @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 <a href="mailto:jstrachan@apache.org">James Strachan</a>
* @author Stephen Colebourne * @author Stephen Colebourne
@ -178,14 +178,14 @@ public class BeanMap extends AbstractMap implements Cloneable {
//------------------------------------------------------------------------- //-------------------------------------------------------------------------
/** /**
* Constructs a new empty <Code>BeanMap</Code>. * Constructs a new empty <code>BeanMap</code>.
*/ */
public BeanMap() { public BeanMap() {
} }
/** /**
* Constructs a new <Code>BeanMap</Code> that operates on the * Constructs a new <code>BeanMap</code> that operates on the
* specified bean. If the given bean is <Code>null</COde>, then * specified bean. If the given bean is <code>null</COde>, then
* this map will be empty. * 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
@ -202,7 +202,6 @@ public class BeanMap extends AbstractMap implements Cloneable {
* Clone this bean map using the following process: * Clone this bean map using the following process:
* *
* <ul> * <ul>
* <li>If there is no underlying bean, return a cloned BeanMap without a * <li>If there is no underlying bean, return a cloned BeanMap without a
* bean. * bean.
* *
@ -221,7 +220,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* CloneNotSupportedException. * CloneNotSupportedException.
* *
* <ul> * <ul>
**/ */
public Object clone() throws CloneNotSupportedException { public Object clone() throws CloneNotSupportedException {
BeanMap newMap = (BeanMap)super.clone(); BeanMap newMap = (BeanMap)super.clone();
@ -273,7 +272,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
/** /**
* Puts all of the writeable properties from the given BeanMap into this * Puts all of the writeable properties from the given BeanMap into this
* BeanMap. Read-only properties will be ignored. * 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
*/ */
@ -295,7 +294,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* behavior for <code>clear()</code> differs from the Map contract in that * 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 * the mappings are not actually removed from the map (the mappings for a
* BeanMap are fixed). * BeanMap are fixed).
**/ */
public void clear() { public void clear() {
if(bean == null) return; if(bean == null) return;
@ -311,12 +310,16 @@ public class BeanMap extends AbstractMap implements Cloneable {
/** /**
* Returns true if the bean defines a property with the given name. * 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 * <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 * returns false. This method will also return false if the bean
* does not define a property with that name. * 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 * @param name the name of the property to check
* @return false if the given name is null or is not a <Code>String</Code>; * @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 * false if the bean does not define a property with that name; or
* true if the bean does define a property with that name * true if the bean does define a property with that name
*/ */
@ -340,11 +343,15 @@ public class BeanMap extends AbstractMap implements Cloneable {
/** /**
* Returns the value of the bean's property with the given name. * 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 * The given name must be a {@link String} and must not be
* null; otherwise, this method returns <Code>null</Code>. * null; otherwise, this method returns <code>null</code>.
* If the bean defines a property with the given name, the value of * If the bean defines a property with the given name, the value of
* that property is returned. Otherwise, <Code>null</Code> is * that property is returned. Otherwise, <code>null</code> is
* returned. * 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 * @param name the name of the property whose value to return
* @return the value of the property with that name * @return the value of the property with that name
@ -423,6 +430,10 @@ public class BeanMap extends AbstractMap implements Cloneable {
/** /**
* Get the keys for this BeanMap. * 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 * @return BeanMap keys. The Set returned by this method is not
* modifiable. * modifiable.
@ -489,7 +500,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* Returns the type of the property with the given name. * Returns the type of the property with the given name.
* *
* @param name the name of the property * @param name the name of the property
* @return the type of the property, or <Code>null</Code> if no such * @return the type of the property, or <code>null</code> if no such
* property exists * property exists
*/ */
public Class getType(String name) { public Class getType(String name) {
@ -498,6 +509,8 @@ public class BeanMap extends AbstractMap implements Cloneable {
/** /**
* 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
*/ */
@ -687,7 +700,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
private BeanMap owner; private BeanMap owner;
/** /**
* Constructs a new <Code>MyMapEntry</Code>. * Constructs a new <code>MyMapEntry</code>.
* *
* @param owner the BeanMap this entry belongs to * @param owner the BeanMap this entry belongs to
* @param key the key for this entry * @param key the key for this entry
@ -766,7 +779,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
* {@link Object#toString() toString()} method, and that string is * {@link Object#toString() toString()} method, and that string is
* parsed into the correct primitve type using, for instance, * parsed into the correct primitve type using, for instance,
* {@link Integer#valueOf(String)} to convert the string into an * {@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 * If no special constructor exists and the given type is not a
* primitive type, this method returns the original value. * primitive type, this method returns the original value.
@ -816,27 +829,25 @@ public class BeanMap extends AbstractMap implements Cloneable {
} }
/** /**
* Logs the given exception to <Code>System.out</Code>. Used to display * Logs the given exception to <code>System.out</code>. Used to display
* warnings while accessing/mutating the bean. * warnings while accessing/mutating the bean.
* *
* @param e the exception to log * @param ex the exception to log
*/ */
protected void logInfo(Exception e) { protected void logInfo(Exception ex) {
// XXXX: should probably use log4j here instead... // Deliberately do not use LOG4J or Commons Logging to avoid dependencies
System.out.println( "INFO: Exception: " + e ); System.out.println( "INFO: Exception: " + ex );
} }
/** /**
* Logs the given exception to <Code>System.err</Code>. Used to display * Logs the given exception to <code>System.err</code>. Used to display
* errors while accessing/mutating the bean. * errors while accessing/mutating the bean.
* *
* @param e the exception to log * @param ex the exception to log
*/ */
protected void logWarn(Exception e) { protected void logWarn(Exception ex) {
// XXXX: should probably use log4j here instead... // Deliberately do not use LOG4J or Commons Logging to avoid dependencies
System.out.println( "WARN: Exception: " + e ); System.out.println( "WARN: Exception: " + ex );
e.printStackTrace(); ex.printStackTrace();
} }
} }