You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by pj...@apache.org on 2002/08/15 22:04:33 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections ArrayIterator.java ArrayStack.java BeanMap.java BinaryHeap.java BufferUnderflowException.java BufferUtils.java CollatingIterator.java CollectionUtils.java DefaultMapBag.java DefaultMapEntry.java EnumerationIterator.java FactoryUtils.java FastArrayList.java FastHashMap.java FastTreeMap.java FilterIterator.java FilterListIterator.java HashBag.java IteratorEnumeration.java ListIteratorWrapper.java ListUtils.java MapUtils.java Predicate.java PredicateUtils.java ProxyIterator.java ProxyListIterator.java ProxyMap.java SequencedHashMap.java SingletonIterator.java StaticBucketMap.java SynchronizedPriorityQueue.java TransformIterator.java TreeBag.java UniqueFilterIterator.java
pjack 2002/08/15 13:04:33
Modified: collections/src/java/org/apache/commons/collections
ArrayIterator.java ArrayStack.java BeanMap.java
BinaryHeap.java BufferUnderflowException.java
BufferUtils.java CollatingIterator.java
CollectionUtils.java DefaultMapBag.java
DefaultMapEntry.java EnumerationIterator.java
FactoryUtils.java FastArrayList.java
FastHashMap.java FastTreeMap.java
FilterIterator.java FilterListIterator.java
HashBag.java IteratorEnumeration.java
ListIteratorWrapper.java ListUtils.java
MapUtils.java Predicate.java PredicateUtils.java
ProxyIterator.java ProxyListIterator.java
ProxyMap.java SequencedHashMap.java
SingletonIterator.java StaticBucketMap.java
SynchronizedPriorityQueue.java
TransformIterator.java TreeBag.java
UniqueFilterIterator.java
Log:
Documented (almost) all public/protected members.
Revision Changes Path
1.15 +22 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayIterator.java
Index: ArrayIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayIterator.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- ArrayIterator.java 20 Jun 2002 02:51:18 -0000 1.14
+++ ArrayIterator.java 15 Aug 2002 20:04:31 -0000 1.15
@@ -166,10 +166,23 @@
// Iterator interface
//-------------------------------------------------------------------------
+
+ /**
+ * Returns true if there are more elements to return from the array.
+ *
+ * @return true if there is a next element to return
+ */
public boolean hasNext() {
return index < length;
}
+ /**
+ * Returns the next element in the array.
+ *
+ * @return the next element in the array
+ * @throws NoSuchElementException if all the elements in the array
+ * have already been returned
+ */
public Object next() {
if(!hasNext()) {
throw new NoSuchElementException();
@@ -177,6 +190,11 @@
return Array.get( array, index++ );
}
+ /**
+ * Throws {@link UnsupportedOperationException}.
+ *
+ * @throws UnsupportedOperationException always
+ */
public void remove() {
throw new UnsupportedOperationException( "remove() method is not supported" );
}
1.8 +11 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayStack.java
Index: ArrayStack.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayStack.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- ArrayStack.java 3 Jul 2002 02:16:48 -0000 1.7
+++ ArrayStack.java 15 Aug 2002 20:04:31 -0000 1.8
@@ -92,6 +92,13 @@
final private static long serialVersionUID = 2130079159931574599L;
//, local class serialVersionUID = -3491241305852305742
+ /**
+ * Constructs a new empty <Code>ArrayStack</Code>.
+ */
+ public ArrayStack() {
+ super();
+ }
+
// --------------------------------------------------------- Public Methods
1.13 +220 -10 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- BeanMap.java 10 Aug 2002 02:05:20 -0000 1.12
+++ BeanMap.java 15 Aug 2002 20:04:31 -0000 1.13
@@ -96,7 +96,15 @@
private transient HashMap writeMethods = new HashMap();
private transient HashMap types = new HashMap();
+ /**
+ * 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.
+ */
public static HashMap defaultTransformers = new HashMap();
static {
@@ -169,9 +177,20 @@
// Constructors
//-------------------------------------------------------------------------
+
+ /**
+ * 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.
+ *
+ * @param bean the bean for this map to operate on
+ */
public BeanMap(Object bean) {
this.bean = bean;
initialise();
@@ -291,16 +310,46 @@
}
}
+ /**
+ * 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
+ */
public boolean containsKey(Object name) {
Method method = getReadMethod( name );
return method != null;
}
+ /**
+ * 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
+ */
public boolean containsValue(Object value) {
// use default implementation
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.
+ *
+ * @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 ) {
Method method = getReadMethod( name );
@@ -325,6 +374,17 @@
return null;
}
+ /**
+ * 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
+ */
public Object put(Object name, Object value) throws IllegalArgumentException, ClassCastException {
if ( bean != null ) {
Object oldValue = get( name );
@@ -352,6 +412,11 @@
return null;
}
+ /**
+ * Returns the number of properties defined by the bean.
+ *
+ * @return the number of properties defined by the bean
+ */
public int size() {
return readMethods.size();
}
@@ -360,7 +425,7 @@
/**
* Get the keys for this BeanMap.
*
- * @return BeanMap keys. The Set returned bu this method is not
+ * @return BeanMap keys. The Set returned by this method is not
* modifiable.
*/
public Set keySet() {
@@ -420,15 +485,32 @@
// Helper methods
//-------------------------------------------------------------------------
-
+
+ /**
+ * 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
+ */
public Class getType(String name) {
return (Class) types.get( name );
}
+ /**
+ * Convenience method for getting 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.
+ *
+ * @return an iterator over the values
+ */
public Iterator valueIterator() {
final Iterator iter = keyIterator();
return new Iterator() {
@@ -445,6 +527,11 @@
};
}
+ /**
+ * Convenience method for getting an iterator over the entries.
+ *
+ * @return an iterator over the entries
+ */
public Iterator entryIterator() {
final Iterator iter = keyIterator();
return new Iterator() {
@@ -465,10 +552,23 @@
// Properties
//-------------------------------------------------------------------------
+
+ /**
+ * 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
+ */
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.
+ *
+ * @param newBean the new bean to operate on
+ */
public void setBean( Object newBean ) {
bean = newBean;
reinitialise();
@@ -478,14 +578,34 @@
// Implementation methods
//-------------------------------------------------------------------------
+ /**
+ * 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
+ */
protected Method getReadMethod( Object name ) {
return (Method) readMethods.get( 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
+ */
protected Method getWriteMethod( Object name ) {
return (Method) writeMethods.get( name );
}
+ /**
+ * Reinitializes this bean. Called during {@link #setBean(Object)}.
+ * Does introspection to find properties.
+ */
protected void reinitialise() {
readMethods.clear();
writeMethods.clear();
@@ -526,19 +646,45 @@
}
}
+ /**
+ * 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 ) {
}
// Implementation classes
//-------------------------------------------------------------------------
+
+ /**
+ * Map entry used by {@link BeanMap}.
+ */
protected static class MyMapEntry extends DefaultMapEntry {
private BeanMap owner;
+ /**
+ * 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
+ */
protected MyMapEntry( BeanMap owner, Object key, Object value ) {
super( key, value );
this.owner = owner;
}
+ /**
+ * Sets the value.
+ *
+ * @param value the new value for the entry
+ * @return the old value for the entry
+ */
public Object setValue(Object value) {
Object key = getKey();
Object oldValue = owner.get( key );
@@ -549,7 +695,21 @@
return oldValue;
}
}
-
+
+ /**
+ * 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 {
if ( value != null ) {
@@ -573,7 +733,38 @@
throw new IllegalArgumentException( e.getMessage() );
}
}
-
+
+ /**
+ * Converts the given value to the given type. First, reflection is
+ * is used to find a public constructor declared by the given class
+ * that takes one argument, which must be the precise type of the
+ * given value. If such a constructor is found, a new object is
+ * created by passing the given value to that constructor, and the
+ * newly constructed object is returned.<P>
+ *
+ * If no such constructor exists, and the given type is a primitive
+ * type, then the given value is converted to a string using its
+ * {@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>
+ *
+ * If no special constructor exists and the given type is not a
+ * primitive type, this method returns the original value.
+ *
+ * @param newType the type to convert the value to
+ * @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
+ * @throws InstantiationException if the constructor found with
+ * reflection raises it
+ * @throws InvocationTargetExcetpion if the constructor found with
+ * reflection raises it
+ * @throws IllegalAccessException never
+ * @throws IllegalArgumentException never
+ */
protected Object convertType( Class newType, Object value )
throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException {
@@ -593,16 +784,35 @@
return value;
}
}
-
+
+ /**
+ * 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
+ */
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.
+ *
+ * @param e the exception to log
+ */
protected void logInfo(Exception e) {
// XXXX: should probably use log4j here instead...
System.out.println( "INFO: Exception: " + e );
}
-
+
+ /**
+ * Logs the given exception to <Code>System.err</Code>. Used to display
+ * errors while accessing/mutating the bean.
+ *
+ * @param e the exception to log
+ */
protected void logWarn(Exception e) {
// XXXX: should probably use log4j here instead...
System.out.println( "WARN: Exception: " + e );
1.10 +60 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/BinaryHeap.java
Index: BinaryHeap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BinaryHeap.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- BinaryHeap.java 3 Jul 2002 02:16:48 -0000 1.9
+++ BinaryHeap.java 15 Aug 2002 20:04:31 -0000 1.10
@@ -98,10 +98,27 @@
public final class BinaryHeap extends AbstractCollection
implements PriorityQueue, Buffer
{
+
+ /**
+ * The default capacity for a binary heap.
+ */
protected final static int DEFAULT_CAPACITY = 13;
+ /**
+ * The number of elements currently in this heap.
+ */
protected int m_size;
+
+ /**
+ * The elements in this heap.
+ */
protected Object[] m_elements;
+
+ /**
+ * If true, the first element as determined by the sort order will
+ * be returned. If false, the last element as determiend by the
+ * sort order will be returned.
+ */
protected boolean m_isMinHeap;
private Comparator m_comparator;
@@ -113,6 +130,10 @@
this( DEFAULT_CAPACITY, true );
}
+ /**
+ * Constructs a new <Code>BinaryHeap</Code> that will use the given
+ * comparator to order its elements.
+ */
public BinaryHeap( Comparator comparator )
{
this();
@@ -133,6 +154,14 @@
this( capacity, true );
}
+ /**
+ * Constructs a new <Code>BinaryHeap</Code>.
+ *
+ * @param capacity the initial capacity for the heap
+ * @param comparator the comparator to use to order elements
+ * @exception IllegalArgumentException
+ * if <code>capacity</code> is <code><= 0</code>
+ */
public BinaryHeap( final int capacity, Comparator comparator )
{
this( capacity );
@@ -150,6 +179,13 @@
this( DEFAULT_CAPACITY, isMinHeap );
}
+ /**
+ * Constructs a new <Code>BinaryHeap</Code>.
+ *
+ * @param isMinHeap true to use the order imposed by the given
+ * comparator; false to reverse that order
+ * @param comparator the comparator to use to order elements
+ */
public BinaryHeap( final boolean isMinHeap, Comparator comparator )
{
this( isMinHeap );
@@ -180,6 +216,16 @@
m_elements = new Object[ capacity + 1 ];
}
+ /**
+ * Constructs a new <Code>BinaryHeap</Code>.
+ *
+ * @param capacity the initial capacity for the heap
+ * @param isMinHeap true to use the order imposed by the given
+ * comparator; false to reverse that order
+ * @param comparator the comparator to use to order elements
+ * @exception IllegalArgumentException
+ * if <code>capacity</code> is <code><= 0</code>
+ */
public BinaryHeap( final int capacity, final boolean isMinHeap,
Comparator comparator )
{
@@ -409,6 +455,12 @@
m_elements = elements;
}
+ /**
+ * Returns a string representation of this heap. The returned string
+ * is similar to those produced by standard JDK collections.
+ *
+ * @return a string representation of this heap
+ */
public String toString()
{
final StringBuffer sb = new StringBuffer();
@@ -519,7 +571,11 @@
return m_size;
}
-
+ /**
+ * Used by testing code.
+ *
+ * @return the otherwise private comparator
+ */
Comparator comparator() {
return m_comparator;
}
1.4 +7 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUnderflowException.java
Index: BufferUnderflowException.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUnderflowException.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- BufferUnderflowException.java 13 Aug 2002 00:46:25 -0000 1.3
+++ BufferUnderflowException.java 15 Aug 2002 20:04:31 -0000 1.4
@@ -90,7 +90,9 @@
m_throwable = exception;
}
-
+ /**
+ * Constructs a new <Code>BufferUnderflowException</Code>.
+ */
public BufferUnderflowException() {
super();
m_throwable = null;
1.6 +14 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUtils.java
Index: BufferUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BufferUtils.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- BufferUtils.java 13 Aug 2002 00:46:25 -0000 1.5
+++ BufferUtils.java 15 Aug 2002 20:04:31 -0000 1.6
@@ -181,6 +181,16 @@
}
+ /**
+ * Returns a bounded buffer backed by the given buffer. New elements
+ * may only be added to the returned buffer if its size is less than
+ * the specified maximum; otherwise, an {@link IllegalStateException}
+ * will be thrown.
+ *
+ * @param buf the buffer whose size to bind
+ * @param maxSize the maximum size of the returned buffer
+ * @return a bounded buffer
+ */
public static Buffer boundedBuffer(Buffer buf, int maxSize) {
return new BoundedBuffer(buf, maxSize);
}
1.4 +58 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/CollatingIterator.java
Index: CollatingIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/CollatingIterator.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- CollatingIterator.java 13 Aug 2002 00:46:25 -0000 1.3
+++ CollatingIterator.java 15 Aug 2002 20:04:31 -0000 1.4
@@ -81,19 +81,53 @@
//------------------------------------------------------------ Constructors
+ /**
+ * Constructs a new <Code>CollatingIterator</Code>. Natural sort order
+ * will be used, and child iterators will have to be manually added
+ * using the {@link #addIterator(Iterator)} method.
+ */
public CollatingIterator() {
this(null,2);
}
+ /**
+ * Constructs a new <Code>CollatingIterator</Code> that will used the
+ * specified comparator for ordering. Child iterators will have to be
+ * manually added using the {@link #addIterator(Iterator)} method.
+ *
+ * @param comp the comparator to use for ordering, or <Code>null</Code>
+ * to use natural sort order
+ */
public CollatingIterator(Comparator comp) {
this(comp,2);
}
+ /**
+ * Constructs a new <Code>CollatingIterator</Code> that will used the
+ * specified comparator for ordering and have the specified initial
+ * capacity. Child iterators will have to be
+ * manually added using the {@link #addIterator(Iterator)} method.
+ *
+ * @param comp the comparator to use for ordering, or <Code>null</Code>
+ * to use natural sort order
+ * @param initIterCapacity the initial capacity for the internal list
+ * of child iterators
+ */
public CollatingIterator(Comparator comp, int initIterCapacity) {
iterators = new ArrayList(initIterCapacity);
setComparator(comp);
}
-
+
+ /**
+ * Constructs a new <Code>CollatingIterator</Code> that will use the
+ * specified comparator to provide ordered iteration over the two
+ * given iterators.
+ *
+ * @param comp the comparator to use to sort, or null to use natural
+ * sort order
+ * @param a the first child ordered iterator
+ * @param b the second child ordered iterator
+ */
public CollatingIterator(Comparator comp, Iterator a, Iterator b) {
this(comp,2);
addIterator(a);
@@ -129,11 +163,23 @@
//------------------------------------------------------- Iterator Methods
+ /**
+ * Returns <Code>true</Code> if any child iterator has remaining elements.
+ *
+ * @return true if this iterator has remaining elements
+ */
public boolean hasNext() {
start();
return anyValueSet(valueSet) || anyHasNext(iterators);
}
+ /**
+ * Returns the next ordered element from a child iterator.
+ *
+ * @return the next ordered element
+ * @throws NoSuchElementException if no child iterator has any more
+ * elements
+ */
public Object next() throws NoSuchElementException {
if(!hasNext()) {
throw new NoSuchElementException();
@@ -150,6 +196,13 @@
}
}
+ /**
+ * Removes the last returned element from the child iterator that
+ * produced it.
+ *
+ * @throws IllegalStateException if there is no last returned element,
+ * or if the last returned element has already been removed
+ */
public void remove() {
if(-1 == lastReturned) {
throw new NoSuchElementException("No value has been returned yet.");
1.11 +10 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/CollectionUtils.java
Index: CollectionUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/CollectionUtils.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- CollectionUtils.java 13 Aug 2002 00:26:51 -0000 1.10
+++ CollectionUtils.java 15 Aug 2002 20:04:31 -0000 1.11
@@ -107,6 +107,12 @@
}
/**
+ * Please don't ever instantiate a <Code>CollectionUtils</Code>.
+ */
+ public CollectionUtils() {
+ }
+
+ /**
* Returns a {@link Collection} containing the union
* of the given {@link Collection}s.
* <p>
1.5 +92 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/DefaultMapBag.java
Index: DefaultMapBag.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/DefaultMapBag.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DefaultMapBag.java 16 Jun 2002 18:56:19 -0000 1.4
+++ DefaultMapBag.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -76,7 +76,10 @@
* interface to minimize the effort required for target implementations.
* Subclasses need only to call {@link #setMap(Map)} in their constructor
* specifying a map instance that will be used to store the contents of
- * the bag.
+ * the bag.<P>
+ *
+ * The map will be used to map bag elements to a number; the number represents
+ * the number of occurrences of that element in the bag.<P>
*
* @since 2.0
* @author Chuck Burdick
@@ -87,10 +90,29 @@
private int _total = 0;
private int _mods = 0;
+
+ /**
+ * Constructor. Subclasses should invoke {@link #setMap(Map)} in
+ * their constructors.
+ */
+ public DefaultMapBag() {
+ }
+
+ /**
+ * Adds a new element to the bag by incrementing its count in the
+ * underlying map.
+ *
+ * @see Bag#add(Object)
+ */
public boolean add(Object o) {
return add(o, 1);
}
+ /**
+ * Adds a new element to the bag by incrementing its count in the map.
+ *
+ * @see Bag#add(Object, int)
+ */
public boolean add(Object o, int i) {
_mods++;
if (i > 0) {
@@ -103,6 +125,11 @@
}
}
+ /**
+ * Invokes {@link #add(Object)} for each element in the given collection.
+ *
+ * @see Bag#addAll(Collection)
+ */
public boolean addAll(Collection c) {
boolean changed = false;
Iterator i = c.iterator();
@@ -113,12 +140,22 @@
return changed;
}
+
+ /**
+ * Clears the bag by clearing the underlying map.
+ */
public void clear() {
_mods++;
_map.clear();
_total = 0;
}
+ /**
+ * Determines if the bag contains the given element by checking if the
+ * underlying map contains the element as a key.
+ *
+ * @return true if the bag contains the given element
+ */
public boolean contains(Object o) {
return _map.containsKey(o);
}
@@ -144,16 +181,34 @@
return result;
}
+ /**
+ * Returns true if the given object is not null, has the precise type
+ * of this bag, and contains the same number of occurrences of all the
+ * same elements.
+ *
+ * @param o the object to test for equality
+ * @return true if that object equals this bag
+ */
public boolean equals(Object o) {
return (o == this ||
(o != null && o.getClass().equals(this.getClass()) &&
((DefaultMapBag)o)._map.equals(this._map)));
}
+ /**
+ * Returns the hash code of the underlying map.
+ *
+ * @return the hash code of the underlying map
+ */
public int hashCode() {
return _map.hashCode();
}
+ /**
+ * Returns true if the underlying map is empty.
+ *
+ * @return true if there are no elements in this bag
+ */
public boolean isEmpty() {
return _map.isEmpty();
}
@@ -231,6 +286,12 @@
return result;
}
+ /**
+ * Remove any members of the bag that are not in the given
+ * bag, respecting cardinality.
+ *
+ * @return true if this call changed the collection
+ */
public boolean retainAll(Collection c) {
return retainAll(new HashBag(c));
}
@@ -261,14 +322,31 @@
return result;
}
+ /**
+ * Returns an array of all of this bag's elements.
+ *
+ * @return an array of all of this bag's elements
+ */
public Object[] toArray() {
return extractList().toArray();
}
+ /**
+ * Returns an array of all of this bag's elements.
+ *
+ * @param a the array to populate
+ * @return an array of all of this bag's elements
+ */
public Object[] toArray(Object[] a) {
return extractList().toArray(a);
}
+ /**
+ * Returns the number of occurrence of the given element in this bag
+ * by looking up its count in the underlying map.
+ *
+ * @see Bag#getCount(Object)
+ */
public int getCount(Object o) {
int result = 0;
Integer count = MapUtils.getInteger(_map, o);
@@ -278,10 +356,20 @@
return result;
}
+ /**
+ * Returns an unmodifiable view of the underlying map's key set.
+ *
+ * @return the set of unique elements in this bag
+ */
public Set uniqueSet() {
return Collections.unmodifiableSet(_map.keySet());
}
+ /**
+ * Returns the number of elements in this bag.
+ *
+ * @return the number of elements in this bag
+ */
public int size() {
return _total;
}
1.8 +32 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/DefaultMapEntry.java
Index: DefaultMapEntry.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/DefaultMapEntry.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- DefaultMapEntry.java 16 Jun 2002 03:39:40 -0000 1.7
+++ DefaultMapEntry.java 15 Aug 2002 20:04:31 -0000 1.8
@@ -74,9 +74,20 @@
private Object key;
private Object value;
+ /**
+ * Constructs a new <Code>DefaultMapEntry</Code> with a null key
+ * and null value.
+ */
public DefaultMapEntry() {
}
+ /**
+ * Constructs a new <Code>DefaultMapEntry</Code> with the given
+ * key and given value.
+ *
+ * @param key the key for the entry, may be null
+ * @param value the value for the entyr, may be null
+ */
public DefaultMapEntry(Object key, Object value) {
this.key = key;
this.value = value;
@@ -113,16 +124,34 @@
// Map.Entry interface
//-------------------------------------------------------------------------
+
+ /**
+ * Returns the key.
+ *
+ * @return the key
+ */
public Object getKey() {
return key;
}
+
+ /**
+ * Returns the value.
+ *
+ * @return the value
+ */
public Object getValue() {
return value;
}
// Properties
//-------------------------------------------------------------------------
+
+ /**
+ * Sets the key. This method does not modify any map.
+ *
+ * @param key the new key
+ */
public void setKey(Object key) {
this.key = key;
}
1.5 +48 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/EnumerationIterator.java
Index: EnumerationIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/EnumerationIterator.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- EnumerationIterator.java 12 Jun 2002 03:59:15 -0000 1.4
+++ EnumerationIterator.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -79,14 +79,31 @@
private Object last;
+ /**
+ * Constructs a new <Code>EnumerationIterator</Code> that will not
+ * function until {@link #setEnumeration(Enumeration)} is called.
+ */
public EnumerationIterator() {
this(null, null);
}
-
+
+ /**
+ * Constructs a new <Code>EnumerationIterator</Code> that provides
+ * an iterator view of the given enumeration.
+ *
+ * @param enumeration the enumeration to use
+ */
public EnumerationIterator( Enumeration enumeration ) {
this(enumeration, null);
}
+ /**
+ * Constructs a new <Code>EnumerationIterator</Code> that will remove
+ * elements from the specified collection.
+ *
+ * @param enum the enumeration to use
+ * @param collection the collection to remove elements form
+ */
public EnumerationIterator( Enumeration enum, Collection collection ) {
this.enumeration = enum;
this.collection = collection;
@@ -95,10 +112,23 @@
// Iterator interface
//-------------------------------------------------------------------------
+
+ /**
+ * Returns true if the underlying enumeration has more elements.
+ *
+ * @return true if the underlying enumeration has more elements
+ * @throws NullPointerException if the underlying enumeration is null
+ */
public boolean hasNext() {
return enumeration.hasMoreElements();
}
+ /**
+ * Returns the next object from the enumeration.
+ *
+ * @return the next object from the enumeration
+ * @throws NullPointerException if the enumeration is null
+ */
public Object next() {
last = enumeration.nextElement();
return last;
@@ -106,6 +136,8 @@
/**
* Functions if an associated <code>Collection</code> is known.
+ * If so, the first occurrence of the last returned object from this
+ * iterator will be removed from the collection.
*
* @exception IllegalStateException <code>next()</code> not called.
* @exception UnsupportedOperationException No associated
@@ -129,10 +161,21 @@
// Properties
//-------------------------------------------------------------------------
+
+ /**
+ * Returns the underlying enumeration.
+ *
+ * @return the underlying enumeration
+ */
public Enumeration getEnumeration() {
return enumeration;
}
-
+
+ /**
+ * Sets the underlying enumeration.
+ *
+ * @param enumeration the new underlying enumeration
+ */
public void setEnumeration( Enumeration enumeration ) {
this.enumeration = enumeration;
}
1.4 +7 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/FactoryUtils.java
Index: FactoryUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FactoryUtils.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- FactoryUtils.java 13 Aug 2002 01:19:00 -0000 1.3
+++ FactoryUtils.java 15 Aug 2002 20:04:31 -0000 1.4
@@ -73,6 +73,9 @@
* @since 2.1
*/
public class FactoryUtils {
+
+ private FactoryUtils() {
+ }
/** Creates a Factory whith a class definition, which will be
* used to create a new object from an empty constructor.
1.8 +15 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/FastArrayList.java
Index: FastArrayList.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FastArrayList.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- FastArrayList.java 13 Aug 2002 04:34:08 -0000 1.7
+++ FastArrayList.java 15 Aug 2002 20:04:31 -0000 1.8
@@ -173,10 +173,21 @@
*/
protected boolean fast = false;
+
+ /**
+ * Returns true if this list is operating in fast mode.
+ *
+ * @return true if this list is operating in fast mode
+ */
public boolean getFast() {
return (this.fast);
}
+ /**
+ * Sets whether this list will operate in fast mode.
+ *
+ * @param fast true if the list should operate in fast mode
+ */
public void setFast(boolean fast) {
this.fast = fast;
}
1.9 +14 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/FastHashMap.java
Index: FastHashMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FastHashMap.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- FastHashMap.java 13 Aug 2002 04:34:08 -0000 1.8
+++ FastHashMap.java 15 Aug 2002 20:04:31 -0000 1.9
@@ -186,10 +186,20 @@
*/
protected boolean fast = false;
+ /**
+ * Returns true if this map is operating in fast mode.
+ *
+ * @return true if this map is operating in fast mode
+ */
public boolean getFast() {
return (this.fast);
}
+ /**
+ * Sets whether this map is operating in fast mode.
+ *
+ * @param fast true if this map should operate in fast mode
+ */
public void setFast(boolean fast) {
this.fast = fast;
}
1.9 +15 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/FastTreeMap.java
Index: FastTreeMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FastTreeMap.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- FastTreeMap.java 13 Aug 2002 04:34:08 -0000 1.8
+++ FastTreeMap.java 15 Aug 2002 20:04:31 -0000 1.9
@@ -189,10 +189,21 @@
*/
protected boolean fast = false;
+
+ /**
+ * Returns true if this map is operating in fast mode.
+ *
+ * @return true if this map is operating in fast mode
+ */
public boolean getFast() {
return (this.fast);
}
+ /**
+ * Sets whether this map is operating in fast mode.
+ *
+ * @param fast true if this map should operate in fast mode
+ */
public void setFast(boolean fast) {
this.fast = fast;
}
1.6 +36 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/FilterIterator.java
Index: FilterIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FilterIterator.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- FilterIterator.java 12 Jun 2002 03:59:15 -0000 1.5
+++ FilterIterator.java 15 Aug 2002 20:04:31 -0000 1.6
@@ -84,13 +84,31 @@
//-------------------------------------------------------------------------
+
+ /**
+ * Constructs a new <Code>FilterIterator</Code> that will not function
+ * until {@link #setIterator(Iterator) setIterator} is invoked.
+ */
public FilterIterator() {
}
+ /**
+ * Constructs a new <Code>FilterIterator</Code> that will not function
+ * until {@link #setPredicate(Predicate) setPredicate} is invoked.
+ *
+ * @param iterator the iterator to use
+ */
public FilterIterator( Iterator iterator ) {
super( iterator );
}
+ /**
+ * Constructs a new <Code>FilterIterator</Code> that will use the
+ * given iterator and predicate.
+ *
+ * @param iterator the iterator to use
+ * @param predicate the predicate to use
+ */
public FilterIterator( Iterator iterator, Predicate predicate ) {
super( iterator );
this.predicate = predicate;
@@ -99,7 +117,12 @@
// Iterator interface
//-------------------------------------------------------------------------
- /** @return true if there is another object that matches the given predicate */
+ /**
+ * Returns true if the underlying iterator contains an object that
+ * matches the predicate.
+ *
+ * @return true if there is another object that matches the predicate
+ */
public boolean hasNext() {
if ( nextObjectSet ) {
return true;
@@ -108,7 +131,13 @@
}
}
- /** @return the next object which matches the given predicate */
+ /**
+ * Returns the next object that matches the predicate.
+ *
+ * @return the next object which matches the given predicate
+ * @throws NoSuchElementException if there are no more elements that
+ * match the predicate
+ */
public Object next() {
if ( !nextObjectSet ) {
if (!setNextObject()) {
@@ -122,6 +151,8 @@
/**
* Always throws UnsupportedOperationException as this class
* does look-ahead with its internal iterator.
+ *
+ * @throws UnsupportedOperationException always
*/
public void remove() {
throw new UnsupportedOperationException();
1.5 +30 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/FilterListIterator.java
Index: FilterListIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/FilterListIterator.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- FilterListIterator.java 12 Jun 2002 03:59:15 -0000 1.4
+++ FilterListIterator.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -80,18 +80,44 @@
// Constructors
//-------------------------------------------------------------------------
+ /**
+ * Constructs a new <Code>FilterListIterator</Code> that will not
+ * function until
+ * {@link ProxyListIterator#setListIterator(ListIterator) setListIterator}
+ * and {@link #setPredicate(Predicate) setPredicate} are invoked.
+ */
public FilterListIterator() {
}
+ /**
+ * Constructs a new <Code>FilterListIterator</Code> that will not
+ * function until {@link #setPredicate(Predicate) setPredicate} is invoked.
+ *
+ * @param iterator the iterator to use
+ */
public FilterListIterator(ListIterator iterator ) {
super(iterator);
}
+ /**
+ * Constructs a new <Code>FilterListIterator</Code>.
+ *
+ * @param iterator the iterator to use
+ * @param predicate the predicate to use
+ */
public FilterListIterator(ListIterator iterator, Predicate predicate) {
super(iterator);
this.predicate = predicate;
}
+ /**
+ * Constructs a new <Code>FilterListIterator</Code> that will not
+ * function until
+ * {@link ProxyListIterator#setListIterator(ListIterator) setListIterator}
+ * is invoked.
+ *
+ * @param predicate the predicate to use.
+ */
public FilterListIterator(Predicate predicate) {
this.predicate = predicate;
}
1.6 +7 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/HashBag.java
Index: HashBag.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/HashBag.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- HashBag.java 12 Jun 2002 03:59:15 -0000 1.5
+++ HashBag.java 15 Aug 2002 20:04:31 -0000 1.6
@@ -72,6 +72,10 @@
* @author Chuck Burdick
**/
public class HashBag extends DefaultMapBag implements Bag {
+
+ /**
+ * Constructs a new empty <Code>HashBag</Code>.
+ */
public HashBag() {
setMap(new HashMap());
}
1.5 +39 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/IteratorEnumeration.java
Index: IteratorEnumeration.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/IteratorEnumeration.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- IteratorEnumeration.java 12 Jun 2002 03:59:15 -0000 1.4
+++ IteratorEnumeration.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -73,29 +73,64 @@
private Iterator iterator;
+ /**
+ * Constructs a new <Code>IteratorEnumeration</Code> that will not
+ * function until {@link #setIterator(Iterator) setIterator} is
+ * invoked.
+ */
public IteratorEnumeration() {
}
+ /**
+ * Constructs a new <Code>IteratorEnumeration</Code> that will use
+ * the given iterator.
+ *
+ * @param iterator the iterator to use
+ */
public IteratorEnumeration( Iterator iterator ) {
this.iterator = iterator;
}
// Iterator interface
//-------------------------------------------------------------------------
+
+ /**
+ * Returns true if the underlying iterator has more elements.
+ *
+ * @return true if the underlying iterator has more elements
+ */
public boolean hasMoreElements() {
return iterator.hasNext();
}
+ /**
+ * Returns the next element from the underlying iterator.
+ *
+ * @return the next element from the underlying iterator.
+ * @throws NoSuchElementException if the underlying iterator has no
+ * more elements
+ */
public Object nextElement() {
return iterator.next();
}
// Properties
//-------------------------------------------------------------------------
+
+ /**
+ * Returns the underlying iterator.
+ *
+ * @return the underlying iterator
+ */
public Iterator getIterator() {
return iterator;
}
-
+
+ /**
+ * Sets the underlying iterator.
+ *
+ * @param iterator the new underlying iterator
+ */
public void setIterator( Iterator iterator ) {
this.iterator = iterator;
}
1.3 +60 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/ListIteratorWrapper.java
Index: ListIteratorWrapper.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ListIteratorWrapper.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ListIteratorWrapper.java 13 Aug 2002 00:46:25 -0000 1.2
+++ ListIteratorWrapper.java 15 Aug 2002 20:04:31 -0000 1.3
@@ -79,6 +79,12 @@
// Constructor
//-------------------------------------------------------------------------
+ /**
+ * Constructs a new <Code>ListIteratorWrapper</Code> that will wrap
+ * the given iterator.
+ *
+ * @param iterator the iterator to wrap
+ */
public ListIteratorWrapper(Iterator iterator) {
this.iterator = iterator;
}
@@ -86,10 +92,22 @@
// ListIterator interface
//-------------------------------------------------------------------------
+ /**
+ * Throws {@link UnsupportedOperationException}.
+ *
+ * @param o ignored
+ * @throws UnsupportedOperationException always
+ */
public void add(Object o) throws UnsupportedOperationException {
throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
}
+
+ /**
+ * Returns true if there are more elements in the iterator.
+ *
+ * @return true if there are more elements
+ */
public boolean hasNext() {
if (currentIndex == wrappedIteratorIndex) {
return iterator.hasNext();
@@ -98,6 +116,11 @@
return true;
}
+ /**
+ * Returns true if there are previous elements in the iterator.
+ *
+ * @return true if there are previous elements
+ */
public boolean hasPrevious() {
if (currentIndex == 0) {
return false;
@@ -106,6 +129,12 @@
return true;
}
+ /**
+ * Returns the next element from the iterator.
+ *
+ * @return the next element from the iterator
+ * @throws NoSuchElementException if there are no more elements
+ */
public Object next() throws NoSuchElementException {
if (currentIndex < wrappedIteratorIndex) {
++currentIndex;
@@ -119,10 +148,21 @@
return retval;
}
+ /**
+ * Returns in the index of the next element.
+ *
+ * @return the index of the next element
+ */
public int nextIndex() {
return currentIndex;
}
+ /**
+ * Returns the the previous element.
+ *
+ * @return the previous element
+ * @throws NoSuchElementException if there are no previous elements
+ */
public Object previous() throws NoSuchElementException {
if (currentIndex == 0) {
throw new NoSuchElementException();
@@ -132,14 +172,30 @@
return list.get(currentIndex);
}
+ /**
+ * Returns the index of the previous element.
+ *
+ * @return the index of the previous element
+ */
public int previousIndex() {
return currentIndex - 1;
}
+ /**
+ * Throws {@link UnsupportedOperationException}.
+ *
+ * @throws UnsupportedOperationException always
+ */
public void remove() throws UnsupportedOperationException {
throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
}
+ /**
+ * Throws {@link UnsupportedOperationException}.
+ *
+ * @param o ignored
+ * @throws UnsupportedOperationException always
+ */
public void set(Object o) throws UnsupportedOperationException {
throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
}
1.7 +54 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/ListUtils.java
Index: ListUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ListUtils.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- ListUtils.java 13 Aug 2002 01:19:00 -0000 1.6
+++ ListUtils.java 15 Aug 2002 20:04:31 -0000 1.7
@@ -77,6 +77,22 @@
*/
public class ListUtils
{
+
+ /**
+ * Please don't ever instantiate a <Code>ListUtils</Code>.
+ */
+ public ListUtils() {
+ }
+
+ /**
+ * Returns a new list containing all elements that are contained in
+ * both given lists.
+ *
+ * @param list1 the first list
+ * @param list2 the second list
+ * @return the intersection of those two lists
+ * @throws NullPointerException if either list is null
+ */
public static List intersection( final List list1, final List list2 )
{
final ArrayList result = new ArrayList();
@@ -95,6 +111,21 @@
return result;
}
+
+ /**
+ * Subtracts all elements in the second list from the first list,
+ * placing the results in a new list.
+ * This differs from {@link List#removeAll(Collection)} in that
+ * cardinality is respected; if <Code>list1</Code> contains two
+ * occurrences of <Code>null</Code> and <Code>list2</Code> only
+ * contains one occurrence, then the returned list will still contain
+ * one occurrence.
+ *
+ * @param list1 the list to subtract from
+ * @param list2 the lsit to subtract
+ * @return a new list containing the results
+ * @throws NullPointerException if either list is null
+ */
public static List subtract( final List list1, final List list2 )
{
final ArrayList result = new ArrayList( list1 );
@@ -108,12 +139,32 @@
return result;
}
+ /**
+ * Returns the sum of the given lists. This is their intersection
+ * subtracted from their union.
+ *
+ * @param list1 the first list
+ * @param list2 the second list
+ * @return a new list containing the sum of those lists
+ * @throws NullPointerException if either list is null
+ */
public static List sum( final List list1, final List list2 )
{
return subtract( union( list1, list2 ),
intersection( list1, list2 ) );
}
+
+ /**
+ * Returns a new list containing the second list appended to the
+ * first list. The {@link List#addAll(Collection)} operation is
+ * used to append the two given lists into a new list.
+ *
+ * @param list1 the first list
+ * @param list2 the second list
+ * @return a new list containing the union of those lists
+ * @throws NullPointerException if either list is null
+ */
public static List union( final List list1, final List list2 )
{
final ArrayList result = new ArrayList( list1 );
1.8 +309 -7 jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java
Index: MapUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/MapUtils.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- MapUtils.java 13 Aug 2002 01:19:00 -0000 1.7
+++ MapUtils.java 15 Aug 2002 20:04:31 -0000 1.8
@@ -62,12 +62,25 @@
import java.io.*;
import java.text.*;
+import java.text.NumberFormat;
import java.util.*;
-/** A helper class for using {@link Map Map} instances.
+/** A helper class for using {@link Map Map} instances.<P>
*
* It contains various typesafe methods
- * as well as other useful features like deep copying
+ * as well as other useful features like deep copying.<P>
+ *
+ * It also provides the following decorators:
+ *
+ * <UL>
+ * <LI>{@link #boundedMap(Map,int)}
+ * <LI>{@link #fixedSizeMap(Map)}
+ * <LI>{@link #fixedSizeSortedMap(SortedMap)}
+ * <LI>{@link #lazyMap(Map,Factory)}
+ * <LI>{@link #lazySortedMap(SortedMap,Factory)}
+ * <LI>{@link #predicatedMap(Map,Predicate,Predicate)}
+ * <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)}
+ * </UL>
*
* @since 1.0
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
@@ -78,11 +91,24 @@
public class MapUtils {
private static int debugIndent = 0;
-
-
+
+ /**
+ * Please don't instantiate a <Code>MapUtils</Code>.
+ */
+ public MapUtils() {
+ }
// Type safe getters
//-------------------------------------------------------------------------
+
+ /**
+ * Synonym for {@link Map#get(Object)}.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return null if the map is null; or the result of
+ * <Code>map.get(key)</Code>
+ */
public static Object getObject( Map map, Object key ) {
if ( map != null ) {
return map.get( key );
@@ -90,6 +116,16 @@
return null;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a string.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return null if the map is null; null if the value mapped by that
+ * key is null; or the <Code>toString()</Code>
+ * result of the value for that key
+ */
public static String getString( Map map, Object key ) {
if ( map != null ) {
Object answer = map.get( key );
@@ -100,6 +136,25 @@
return null;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Boolean}. If the map is null, this method returns null.
+ * If the value mapped by the given key is a
+ * {@link Boolean}, then it is returned as-is. Otherwise, if the value
+ * is a string, then if that string ignoring case equals "true", then
+ * a true {@link Boolean} is returned. Any other string value will
+ * result in a false {@link Boolean} being returned. OR, if the value
+ * is a {@link Number}, and that {@link Number} is 0, then a false
+ * {@link Boolean} is returned. Any other {@link Number} value results
+ * in a true {@link Boolean} being returned.<P>
+ *
+ * Any value that is not a {@link Boolean}, {@link String} or
+ * {@link Number} results in null being returned.<P>
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Boolean} or null
+ */
public static Boolean getBoolean( Map map, Object key ) {
if ( map != null ) {
Object answer = map.get( key );
@@ -121,6 +176,22 @@
return null;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Number}. If the map is null, this method returns null.
+ * Otherwise, if the key maps to a {@link Number}, then that number
+ * is returned as-is. Otherwise, if the key maps to a {@link String},
+ * that string is parsed into a number using the system default
+ * {@link NumberFormat}.<P>
+ *
+ * If the value is not a {@link Number} or a {@link String}, or if
+ * the value is a {@link String} that cannot be parsed into a
+ * {@link Number}, then null is returned.<P>
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Number} or null
+ */
public static Number getNumber( Map map, Object key ) {
if ( map != null ) {
Object answer = map.get( key );
@@ -143,6 +214,16 @@
return null;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Byte}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * byte value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Byte} or null
+ */
public static Byte getByte( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -155,6 +236,16 @@
return new Byte( answer.byteValue() );
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Short}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * short value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Short} or null
+ */
public static Short getShort( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -167,6 +258,16 @@
return new Short( answer.shortValue() );
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * an {@link Integer}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * integer value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return an {@link Integer} or null
+ */
public static Integer getInteger( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -179,6 +280,16 @@
return new Integer( answer.intValue() );
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Long}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * long value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Long} or null
+ */
public static Long getLong( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -191,6 +302,16 @@
return new Long( answer.longValue() );
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Float}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * float value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Float} or null
+ */
public static Float getFloat( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -203,6 +324,16 @@
return new Float( answer.floatValue() );
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a {@link Double}. First, {@link #getNumber(Map,Object)} is invoked.
+ * If the result is null, then null is returned. Otherwise, the
+ * double value of the resulting {@link Number} is returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Double} or null
+ */
public static Double getDouble( Map map, Object key ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -215,6 +346,16 @@
return new Double( answer.doubleValue() );
}
+ /**
+ * Looks up the given key in the given map, returning another map.
+ * If the given map is null or if the given key doesn't map to another
+ * map, then this method returns null. Otherwise the mapped map is
+ * returned.
+ *
+ * @param map the map whose value to look up
+ * @param key the key whose value to look up in that map
+ * @return a {@link Map} or null
+ */
public static Map getMap( Map map, Object key ) {
if ( map != null ) {
Object answer = map.get( key );
@@ -227,6 +368,17 @@
// Type safe getters with default values
//-------------------------------------------------------------------------
+
+ /**
+ * Looks up the given key in the given map, converting null into the
+ * given default value.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null
+ * @return the value in the map, or defaultValue if the original value
+ * is null or the map is null
+ */
public static Object getObject( Map map, Object key, Object defaultValue ) {
if ( map != null ) {
Object answer = map.get( key );
@@ -237,6 +389,18 @@
return defaultValue;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a string, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a string, or defaultValue if the
+ * original value is null, the map is null or the string conversion
+ * fails
+ */
public static String getString( Map map, Object key, String defaultValue ) {
String answer = getString( map, key );
if ( answer == null ) {
@@ -245,6 +409,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a boolean, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a boolean, or defaultValue if the
+ * original value is null, the map is null or the boolean conversion
+ * fails
+ */
public static Boolean getBoolean( Map map, Object key, Boolean defaultValue ) {
Boolean answer = getBoolean( map, key );
if ( answer == null ) {
@@ -253,6 +429,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a number, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Number getNumber( Map map, Object key, Number defaultValue ) {
Number answer = getNumber( map, key );
if ( answer == null ) {
@@ -261,6 +449,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a byte, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Byte getByte( Map map, Object key, Byte defaultValue ) {
Byte answer = getByte( map, key );
if ( answer == null ) {
@@ -269,6 +469,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a short, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Short getShort( Map map, Object key, Short defaultValue ) {
Short answer = getShort( map, key );
if ( answer == null ) {
@@ -277,6 +489,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * an integer, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Integer getInteger( Map map, Object key, Integer defaultValue ) {
Integer answer = getInteger( map, key );
if ( answer == null ) {
@@ -285,6 +509,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a long, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Long getLong( Map map, Object key, Long defaultValue ) {
Long answer = getLong( map, key );
if ( answer == null ) {
@@ -293,6 +529,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a float, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Float getFloat( Map map, Object key, Float defaultValue ) {
Float answer = getFloat( map, key );
if ( answer == null ) {
@@ -301,6 +549,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a double, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the number conversion
+ * fails
+ */
public static Double getDouble( Map map, Object key, Double defaultValue ) {
Double answer = getDouble( map, key );
if ( answer == null ) {
@@ -309,6 +569,18 @@
return answer;
}
+ /**
+ * Looks up the given key in the given map, converting the result into
+ * a map, using the default value if the the conversion fails.
+ *
+ * @param map the map whose value to look up
+ * @param key the key of the value to look up in that map
+ * @param defaultValue what to return if the value is null or if the
+ * conversion fails
+ * @return the value in the map as a number, or defaultValue if the
+ * original value is null, the map is null or the map conversion
+ * fails
+ */
public static Map getMap( Map map, Object key, Map defaultValue ) {
Map answer = getMap( map, key );
if ( answer == null ) {
@@ -319,6 +591,10 @@
// Conversion methods
//-------------------------------------------------------------------------
+
+ /**
+ * Synonym for <Code>new Properties(input)</COde>.
+ */
public static Properties toProperties(Map input) {
Properties answer = new Properties();
if ( input != null ) {
@@ -334,6 +610,14 @@
// Printing methods
//-------------------------------------------------------------------------
+
+ /**
+ * Prints the given map with nice line breaks.
+ *
+ * @param out the stream to print to
+ * @param key the key that maps to the map in some other map
+ * @param map the map to print
+ */
public static synchronized void verbosePrint( PrintStream out, Object key, Map map ) {
debugPrintIndent( out );
out.println( key + " = " );
@@ -359,6 +643,13 @@
out.println( "}" );
}
+ /**
+ * Prints the given map with nice line breaks.
+ *
+ * @param out the stream to print to
+ * @param key the key that maps to the map in some other map
+ * @param map the map to print
+ */
public static synchronized void debugPrint( PrintStream out, Object key, Map map ) {
debugPrintIndent( out );
out.println( key + " = " );
@@ -391,12 +682,23 @@
// Implementation methods
//-------------------------------------------------------------------------
+
+ /**
+ * Writes indentation to the given stream.
+ *
+ * @param out the stream to indent
+ */
protected static void debugPrintIndent( PrintStream out ) {
for ( int i = 0; i < debugIndent; i++ ) {
out.print( " " );
}
}
+ /**
+ * Logs the given exception to <Code>System.out</Code>.
+ *
+ * @param e the exception to log
+ */
protected static void logInfo(Exception e) {
// mapX: should probably use log4j here instead...
System.out.println( "INFO: Exception: " + e );
1.5 +7 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/Predicate.java
Index: Predicate.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/Predicate.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Predicate.java 12 Jun 2002 03:59:15 -0000 1.4
+++ Predicate.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -68,7 +68,10 @@
*/
public interface Predicate {
- /** @return true if the input object matches this predicate, else returns false
+ /**
+ * Returns true if the input object matches this predicate.
+ *
+ * @return true if the input object matches this predicate, else returns false
*/
public boolean evaluate(Object input);
}
1.5 +5 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/PredicateUtils.java
Index: PredicateUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/PredicateUtils.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- PredicateUtils.java 13 Aug 2002 00:46:25 -0000 1.4
+++ PredicateUtils.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -250,7 +250,7 @@
/**
* Predicate that checks the type of an object
*/
- public static class InstanceofPredicate implements Predicate {
+ private static class InstanceofPredicate implements Predicate {
private final Class iType;
/**
1.5 +31 -5 jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyIterator.java
Index: ProxyIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyIterator.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ProxyIterator.java 12 Jun 2002 03:59:15 -0000 1.4
+++ ProxyIterator.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -76,24 +76,50 @@
/** Holds value of property iterator. */
private Iterator iterator;
-
+ /**
+ * Constructs a new <Code>ProxyIterator</Code> that will not function
+ * until {@link #setIterator(Iterator)} is called.
+ */
public ProxyIterator() {
}
+ /**
+ * Constructs a new <Code>ProxyIterator</Code> that will use the
+ * given iterator.
+ *
+ * @param iterator the underyling iterator
+ */
public ProxyIterator( Iterator iterator ) {
this.iterator = iterator;
}
// Iterator interface
//-------------------------------------------------------------------------
+
+ /**
+ * Returns true if the underlying iterator has more elements.
+ *
+ * @return true if the underlying iterator has more elements
+ */
public boolean hasNext() {
return getIterator().hasNext();
}
+ /**
+ * Returns the next element from the underlying iterator.
+ *
+ * @return the next element from the underlying iterator
+ * @throws NoSuchElementException if the underlying iterator
+ * raises it because it has no more elements
+ */
public Object next() {
return getIterator().next();
}
+ /**
+ * Removes the last returned element from the collection that spawned
+ * the underlying iterator.
+ */
public void remove() {
getIterator().remove();
}
1.3 +60 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyListIterator.java
Index: ProxyListIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyListIterator.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ProxyListIterator.java 12 Jun 2002 03:59:15 -0000 1.2
+++ ProxyListIterator.java 15 Aug 2002 20:04:31 -0000 1.3
@@ -76,9 +76,20 @@
// Constructor
//-------------------------------------------------------------------------
+ /**
+ * Constructs a new <Code>ProxyListIterator</Code> that will not
+ * function until {@link #setListIterator(ListIterator) setListIterator}
+ * is invoked.
+ */
public ProxyListIterator() {
}
+ /**
+ * Constructs a new <Code>ProxyListIterator</Code> that will use the
+ * given list iterator.
+ *
+ * @param iterator the list iterator to use
+ */
public ProxyListIterator(ListIterator iterator) {
this.iterator = iterator;
}
@@ -86,38 +97,83 @@
// ListIterator interface
//-------------------------------------------------------------------------
+ /**
+ * Invokes the underlying {@link ListIterator#add(Object)} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public void add(Object o) {
getListIterator().add(o);
}
+ /**
+ * Invokes the underlying {@link ListIterator#hasNext()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public boolean hasNext() {
return getListIterator().hasNext();
}
+ /**
+ * Invokes the underlying {@link ListIterator#hasPrevious()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public boolean hasPrevious() {
return getListIterator().hasPrevious();
}
+ /**
+ * Invokes the underlying {@link ListIterator#next()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public Object next() {
return getListIterator().next();
}
+ /**
+ * Invokes the underlying {@link ListIterator#nextIndex()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public int nextIndex() {
return getListIterator().nextIndex();
}
+ /**
+ * Invokes the underlying {@link ListIterator#previous()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public Object previous() {
return getListIterator().previous();
}
+ /**
+ * Invokes the underlying {@link ListIterator#previousIndex()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public int previousIndex() {
return getListIterator().previousIndex();
}
+ /**
+ * Invokes the underlying {@link ListIterator#remove()} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public void remove() {
getListIterator().remove();
}
+ /**
+ * Invokes the underlying {@link ListIterator#set(Object)} method.
+ *
+ * @throws NullPointerException if the underyling iterator is null
+ */
public void set(Object o) {
getListIterator().set(o);
}
1.5 +45 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyMap.java
Index: ProxyMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ProxyMap.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ProxyMap.java 12 Aug 2002 22:51:13 -0000 1.4
+++ ProxyMap.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -97,58 +97,100 @@
this.map = map;
}
+ /**
+ * Invokes the underlying {@link Map#clear()} method.
+ */
public void clear() {
map.clear();
}
+ /**
+ * Invokes the underlying {@link Map#containsKey(Object)} method.
+ */
public boolean containsKey(Object key) {
return map.containsKey(key);
}
+ /**
+ * Invokes the underlying {@link Map#containsValue(Object)} method.
+ */
public boolean containsValue(Object value) {
return map.containsValue(value);
}
+ /**
+ * Invokes the underlying {@link Map#entrySet()} method.
+ */
public Set entrySet() {
return map.entrySet();
}
+ /**
+ * Invokes the underlying {@link Map#equals(Object)} method.
+ */
public boolean equals(Object m) {
return map.equals(m);
}
+ /**
+ * Invokes the underlying {@link Map#get(Object)} method.
+ */
public Object get(Object key) {
return map.get(key);
}
+ /**
+ * Invokes the underlying {@link Map#hashCode()} method.
+ */
public int hashCode() {
return map.hashCode();
}
+ /**
+ * Invokes the underlying {@link Map#isEmpty()} method.
+ */
public boolean isEmpty() {
return map.isEmpty();
}
+ /**
+ * Invokes the underlying {@link Map#keySet()} method.
+ */
public Set keySet() {
return map.keySet();
}
+ /**
+ * Invokes the underlying {@link Map#put(Object,Object)} method.
+ */
public Object put(Object key, Object value) {
return map.put(key, value);
}
+ /**
+ * Invokes the underlying {@link Map#putAll(Map)} method.
+ */
public void putAll(Map t) {
map.putAll(t);
}
+ /**
+ * Invokes the underlying {@link Map#remove(Object)} method.
+ */
public Object remove(Object key) {
return map.remove(key);
}
+ /**
+ * Invokes the underlying {@link Map#size()} method.
+ */
public int size() {
return map.size();
}
+ /**
+ * Invokes the underlying {@link Map#values()} method.
+ */
public Collection values() {
return map.values();
}
1.13 +57 -16 jakarta-commons/collections/src/java/org/apache/commons/collections/SequencedHashMap.java
Index: SequencedHashMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/SequencedHashMap.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- SequencedHashMap.java 12 Jun 2002 03:59:15 -0000 1.12
+++ SequencedHashMap.java 15 Aug 2002 20:04:31 -0000 1.13
@@ -269,25 +269,35 @@
}
// per Map.size()
+
+ /**
+ * Implements {@link Map#size()}.
+ */
public int size() {
// use the underlying Map's size since size is not maintained here.
return entries.size();
}
- // per Map.isEmpty()
+ /**
+ * Implements {@link Map#isEmpty()}.
+ */
public boolean isEmpty() {
// for quick check whether the map is entry, we can check the linked list
// and see if there's anything in it.
return sentinel.next == sentinel;
}
- // per Map.containsKey(Object)
+ /**
+ * Implements {@link Map#containsKey(Object)}.
+ */
public boolean containsKey(Object key) {
// pass on to underlying map implementation
return entries.containsKey(key);
}
- // per Map.containsValue(Object)
+ /**
+ * Implements {@link Map#containsValue(Object)}.
+ */
public boolean containsValue(Object value) {
// unfortunately, we cannot just pass this call to the underlying map
// because we are mapping keys to entries, not keys to values. The
@@ -309,7 +319,9 @@
return false;
}
- // per Map.get(Object)
+ /**
+ * Implements {@link Map#get(Object)}.
+ */
public Object get(Object o) {
// find entry for the specified key object
Entry entry = (Entry)entries.get(o);
@@ -442,7 +454,9 @@
return sentinel.prev.getValue();
}
- // per Map.put(Object,Object)
+ /**
+ * Implements {@link Map#put(Object, Object)}.
+ */
public Object put(Object key, Object value) {
modCount++;
@@ -477,7 +491,9 @@
return oldValue;
}
- // per Map.remove(Object)
+ /**
+ * Implements {@link Map#remove(Object)}.
+ */
public Object remove(Object key) {
Entry e = removeImpl(key);
return (e == null) ? null : e.getValue();
@@ -513,7 +529,9 @@
}
}
- // per Map.clear()
+ /**
+ * Implements {@link Map#clear()}.
+ */
public void clear() {
modCount++;
@@ -525,7 +543,9 @@
sentinel.prev = sentinel;
}
- // per Map.equals(Object)
+ /**
+ * Implements {@link Map#equals(Object)}.
+ */
public boolean equals(Object obj) {
if(obj == null) return false;
if(obj == this) return true;
@@ -535,7 +555,9 @@
return entrySet().equals(((Map)obj).entrySet());
}
- // per Map.hashCode()
+ /**
+ * Implements {@link Map#hashCode()}.
+ */
public int hashCode() {
return entrySet().hashCode();
}
@@ -563,7 +585,9 @@
return buf.toString();
}
- // per Map.keySet()
+ /**
+ * Implements {@link Map#keySet()}.
+ */
public Set keySet() {
return new AbstractSet() {
@@ -591,7 +615,9 @@
};
}
- // per Map.values()
+ /**
+ * Implements {@link Map#values()}.
+ */
public Collection values() {
return new AbstractCollection() {
// required impl
@@ -635,7 +661,9 @@
};
}
- // per Map.entrySet()
+ /**
+ * Implements {@link Map#entrySet()}.
+ */
public Set entrySet() {
return new AbstractSet() {
// helper
@@ -968,6 +996,14 @@
}
// per Externalizable.readExternal(ObjectInput)
+
+ /**
+ * Deserializes this map from the given stream.
+ *
+ * @param in the stream to deserialize from
+ * @throws IOException if the stream raises it
+ * @throws ClassNotFoundException if the stream raises it
+ */
public void readExternal( ObjectInput in )
throws IOException, ClassNotFoundException
{
@@ -979,7 +1015,12 @@
}
}
- // per Externalizable.writeExternal(ObjectOutput)
+ /**
+ * Serializes this map to the given stream.
+ *
+ * @param out the stream to serialize to
+ * @throws IOException if the stream raises it
+ */
public void writeExternal( ObjectOutput out ) throws IOException {
out.writeInt(size());
for(Entry pos = sentinel.next; pos != sentinel; pos = pos.next) {
1.6 +26 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/SingletonIterator.java
Index: SingletonIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/SingletonIterator.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- SingletonIterator.java 12 Jun 2002 03:59:15 -0000 1.5
+++ SingletonIterator.java 15 Aug 2002 20:04:31 -0000 1.6
@@ -75,14 +75,31 @@
private boolean first = true;
private Object object;
+ /**
+ * Constructs a new <Code>SingletonIterator</Code>.
+ *
+ * @param object the single object to return from the iterator
+ */
public SingletonIterator(Object object) {
this.object = object;
}
+ /**
+ * Returns true if the single object hasn't been returned yet.
+ *
+ * @return true if the single object hasn't been returned yet
+ */
public boolean hasNext() {
return first;
}
+ /**
+ * Returns the single object if it hasn't been returned yet.
+ *
+ * @return the single object
+ * @throws NoSuchElementException if the single object has already been
+ * returned
+ */
public Object next() {
if (! first ) {
throw new NoSuchElementException();
@@ -93,6 +110,11 @@
return answer;
}
+ /**
+ * Throws {@link UnsupportedOperationException}.
+ *
+ * @throws UnsupportedOperationException always
+ */
public void remove() {
throw new UnsupportedOperationException( "remove() is not supported by this iterator" );
}
1.4 +18 -30 jakarta-commons/collections/src/java/org/apache/commons/collections/StaticBucketMap.java
Index: StaticBucketMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/StaticBucketMap.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- StaticBucketMap.java 15 Aug 2002 03:22:29 -0000 1.3
+++ StaticBucketMap.java 15 Aug 2002 20:04:31 -0000 1.4
@@ -211,7 +211,7 @@
}
/**
- * Returns a set view of this map's keys.
+ * Implements {@link Map#keySet()}.
*/
public Set keySet()
{
@@ -219,7 +219,7 @@
}
/**
- * Returns the current number of key, value pairs.
+ * Implements {@link Map#size()}.
*/
public int size()
{
@@ -234,7 +234,7 @@
}
/**
- * Put a reference in the Map.
+ * Implements {@link Map#put(Object, Object)}.
*/
public Object put( final Object key, final Object value )
{
@@ -282,7 +282,7 @@
}
/**
- * Get an object from the Map by the key
+ * Implements {@link Map#get(Object)}.
*/
public Object get( final Object key )
{
@@ -307,7 +307,7 @@
}
/**
- * Checks to see if the provided key exists in the Map.
+ * Implements {@link Map#containsKey(Object)}.
*/
public boolean containsKey( final Object key )
{
@@ -332,9 +332,7 @@
}
/**
- * Checks to see if a value exists. This operation crosses bucket
- * boundaries, so it is less efficient, and greatly increases the chance
- * for thread contention.
+ * Implements {@link Map#containsValue(Object)}.
*/
public boolean containsValue( final Object value )
{
@@ -361,9 +359,7 @@
}
/**
- * Obtain a Set for the values. This operation crosses bucket boundaries,
- * so it is less efficient, and greatly increases the chance for thread
- * contention.
+ * Implements {@link Map#values()}.
*/
public Collection values()
{
@@ -371,9 +367,7 @@
}
/**
- * Obtain a Set for the entries. This operation crosses bucket boundaries,
- * so it is less efficient, and greatly increases the chance for thread
- * contention.
+ * Implements {@link Map#entrySet()}.
*/
public Set entrySet()
{
@@ -381,7 +375,7 @@
}
/**
- * Add all the contents of one Map into this one.
+ * Implements {@link Map#putAll(Map)}.
*/
public void putAll( Map other )
{
@@ -395,7 +389,7 @@
}
/**
- * Removes the object from the Map based on the key.
+ * Implements {@link Map#remove(Object)}.
*/
public Object remove( Object key )
{
@@ -434,7 +428,7 @@
}
/**
- * Tests if the Map is empty.
+ * Implements {@link Map#isEmpty()}.
*/
public final boolean isEmpty()
{
@@ -442,7 +436,7 @@
}
/**
- * Removes all the entries from the Map.
+ * Implements {@link Map#clear()}.
*/
public final void clear()
{
@@ -457,11 +451,7 @@
}
/**
- * Returns true if the given object is a map with the same mappings
- * as this map.
- *
- * @return true if the given object is the a map with same mappings
- * as this map
+ * Implements {@link Map#equals(Object)}.
*/
public final boolean equals( Object obj )
{
@@ -476,9 +466,7 @@
}
/**
- * Returns a hash code for this map.
- *
- * @return a hash code for this map
+ * Implements {@link Map#hashCode()}.
*/
public final int hashCode()
{
1.5 +18 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java
Index: SynchronizedPriorityQueue.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- SynchronizedPriorityQueue.java 12 Jun 2002 03:59:15 -0000 1.4
+++ SynchronizedPriorityQueue.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -73,8 +73,18 @@
public final class SynchronizedPriorityQueue
implements PriorityQueue
{
+
+ /**
+ * The underlying priority queue.
+ */
protected final PriorityQueue m_priorityQueue;
+
+ /**
+ * Constructs a new synchronized priority queue.
+ *
+ * @param priorityQueue the priority queue to synchronize
+ */
public SynchronizedPriorityQueue( final PriorityQueue priorityQueue )
{
m_priorityQueue = priorityQueue;
@@ -130,6 +140,11 @@
return m_priorityQueue.pop();
}
+ /**
+ * Returns a string representation of the underlying queue.
+ *
+ * @return a string representation of the underlying queue
+ */
public synchronized String toString()
{
return m_priorityQueue.toString();
1.5 +30 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/TransformIterator.java
Index: TransformIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/TransformIterator.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- TransformIterator.java 12 Jun 2002 03:59:15 -0000 1.4
+++ TransformIterator.java 15 Aug 2002 20:04:31 -0000 1.5
@@ -76,13 +76,32 @@
private Transformer transformer;
+ /**
+ * Constructs a new <Code>TransformIterator</Code> that will not function
+ * until the {@link #setIterator(Iterator) setIterator} method is
+ * invoked.
+ */
public TransformIterator() {
}
+ /**
+ * Constructs a new <Code>TransformIterator</Code> that won't transform
+ * elements from the given iterator.
+ *
+ * @param iterator the iterator to use
+ */
public TransformIterator( Iterator iterator ) {
super( iterator );
}
+ /**
+ * Constructs a new <Code>TransformIterator</Code> that will use the
+ * given iterator and transformer. If the given transformer is null,
+ * then objects will not be transformed.
+ *
+ * @param iterator the iterator to use
+ * @param transformer the transformer to use
+ */
public TransformIterator( Iterator iterator, Transformer transformer ) {
super( iterator );
this.transformer = transformer;
@@ -111,6 +130,14 @@
// Implementation methods
//-------------------------------------------------------------------------
+
+ /**
+ * Transforms the given object using the transformer. If the
+ * transformer is null, the original object is returned as-is.
+ *
+ * @param source the object to transform
+ * @return the transformed object
+ */
protected Object transform( Object source ) {
Transformer transformer = getTransformer();
if ( transformer != null ) {
1.6 +7 -3 jakarta-commons/collections/src/java/org/apache/commons/collections/TreeBag.java
Index: TreeBag.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/TreeBag.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- TreeBag.java 12 Jun 2002 03:59:15 -0000 1.5
+++ TreeBag.java 15 Aug 2002 20:04:31 -0000 1.6
@@ -75,6 +75,10 @@
* @author Chuck Burdick
**/
public class TreeBag extends DefaultMapBag implements SortedBag, Bag {
+
+ /**
+ * Constructs a new empty <Code>TreeBag</Code>.
+ */
public TreeBag() {
setMap(new TreeMap());
}
1.3 +9 -4 jakarta-commons/collections/src/java/org/apache/commons/collections/UniqueFilterIterator.java
Index: UniqueFilterIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/UniqueFilterIterator.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- UniqueFilterIterator.java 13 Aug 2002 00:46:25 -0000 1.2
+++ UniqueFilterIterator.java 15 Aug 2002 20:04:31 -0000 1.3
@@ -77,6 +77,11 @@
//-------------------------------------------------------------------------
+ /**
+ * Constructs a new <Code>UniqueFilterIterator</Code>.
+ *
+ * @param iterator the iterator to use
+ */
public UniqueFilterIterator( Iterator iterator ) {
super( iterator, new UniquePredicate() );
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>