diff --git a/src/java/org/apache/commons/collections/ExtendedProperties.java b/src/java/org/apache/commons/collections/ExtendedProperties.java index 622f0fd2c..ab66e2653 100644 --- a/src/java/org/apache/commons/collections/ExtendedProperties.java +++ b/src/java/org/apache/commons/collections/ExtendedProperties.java @@ -1,5 +1,5 @@ /* - * Copyright 2001-2005 The Apache Software Foundation + * Copyright 2001-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -69,7 +69,7 @@ import java.util.Vector; * *
  • * If a key is used more than once, the values are appended - * like if they were on the same line separated with commas. + * as if they were on the same line separated with commas. *
    • *
  • * Blank lines and lines starting with character '#' are skipped. diff --git a/src/java/org/apache/commons/collections/buffer/BoundedBuffer.java b/src/java/org/apache/commons/collections/buffer/BoundedBuffer.java index 2640f1a74..301725ddf 100644 --- a/src/java/org/apache/commons/collections/buffer/BoundedBuffer.java +++ b/src/java/org/apache/commons/collections/buffer/BoundedBuffer.java @@ -33,8 +33,11 @@ import org.apache.commons.collections.iterators.AbstractIteratorDecorator; * behaviour to another buffer. If you just want a bounded buffer then * you should use {@link BoundedFifoBuffer} or {@link CircularFifoBuffer}. *

    - * The decoration methods allow you to specify a timeout value, which - * causes the add methods to wait for up to the specified wait period. + * The decoration methods allow you to specify a timeout value. + * This alters the behaviour of the add methods when the buffer is full. + * Normally, when the buffer is full, the add method will throw an exception. + * With a timeout, the add methods will wait for up to the timeout period + * to try and add the elements. * * @author James Carman * @author Stephen Colebourne diff --git a/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java b/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java index b062d1ed0..91e7f0bc8 100644 --- a/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java +++ b/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2004 The Apache Software Foundation + * Copyright 2002-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,7 +32,7 @@ import org.apache.commons.collections.BufferUnderflowException; /** * The BoundedFifoBuffer is a very efficient implementation of - * Buffer that does not alter the size of the buffer at runtime. + * Buffer that is of a fixed size. *

    * The removal order of a BoundedFifoBuffer is based on the * insertion order; elements are removed in the same order in which they diff --git a/src/java/org/apache/commons/collections/buffer/PriorityBuffer.java b/src/java/org/apache/commons/collections/buffer/PriorityBuffer.java index 3eb7f23bc..db30dd36c 100644 --- a/src/java/org/apache/commons/collections/buffer/PriorityBuffer.java +++ b/src/java/org/apache/commons/collections/buffer/PriorityBuffer.java @@ -45,10 +45,11 @@ import org.apache.commons.collections.BufferUnderflowException; * {@link org.apache.commons.collections.BufferUtils#synchronizedBuffer(Buffer)} or * {@link org.apache.commons.collections.buffer.SynchronizedBuffer#decorate(Buffer)} * to provide synchronized access to a PriorityBuffer: - * * 

      * Buffer heap = SynchronizedBuffer.decorate(new PriorityBuffer());
  *
    + *

    + * This class is Serializable from Commons Collections 3.2. * * @since Commons Collections 3.0 (previously BinaryHeap v1.0) * @version $Revision$ $Date$ diff --git a/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java b/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java index 44bb83e25..2cc07bb93 100644 --- a/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java +++ b/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2004 The Apache Software Foundation + * Copyright 2002-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,7 +27,8 @@ import org.apache.commons.collections.Buffer; import org.apache.commons.collections.BufferUnderflowException; /** - * UnboundedFifoBuffer is a very efficient buffer implementation. + * UnboundedFifoBuffer is a very efficient implementation of + * Buffer that can grow to any size. * According to performance testing, it exhibits a constant access time, but it * also outperforms ArrayList when used for the same purpose. *

    diff --git a/src/java/org/apache/commons/collections/functors/AllPredicate.java b/src/java/org/apache/commons/collections/functors/AllPredicate.java index 74e7906e4..22bce597f 100644 --- a/src/java/org/apache/commons/collections/functors/AllPredicate.java +++ b/src/java/org/apache/commons/collections/functors/AllPredicate.java @@ -41,7 +41,10 @@ public final class AllPredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + *

    + * If the array is size zero, the predicate always returns true. + * If the array is size one, then that predicate is returned. + * * @param predicates the predicates to check, cloned, not null * @return the all predicate * @throws IllegalArgumentException if the predicates array is null @@ -61,7 +64,10 @@ public final class AllPredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + *

    + * If the collection is size zero, the predicate always returns true. + * If the collection is size one, then that predicate is returned. + * * @param predicates the predicates to check, cloned, not null * @return the all predicate * @throws IllegalArgumentException if the predicates array is null diff --git a/src/java/org/apache/commons/collections/functors/AnyPredicate.java b/src/java/org/apache/commons/collections/functors/AnyPredicate.java index 918c60b96..fbf26c3a5 100644 --- a/src/java/org/apache/commons/collections/functors/AnyPredicate.java +++ b/src/java/org/apache/commons/collections/functors/AnyPredicate.java @@ -41,7 +41,10 @@ public final class AnyPredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + *

    + * If the array is size zero, the predicate always returns false. + * If the array is size one, then that predicate is returned. + * * @param predicates the predicates to check, cloned, not null * @return the any predicate * @throws IllegalArgumentException if the predicates array is null @@ -60,7 +63,10 @@ public final class AnyPredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + *

    + * If the collection is size zero, the predicate always returns false. + * If the collection is size one, then that predicate is returned. + * * @param predicates the predicates to check, cloned, not null * @return the all predicate * @throws IllegalArgumentException if the predicates array is null diff --git a/src/java/org/apache/commons/collections/functors/NonePredicate.java b/src/java/org/apache/commons/collections/functors/NonePredicate.java index edda30171..b70116217 100644 --- a/src/java/org/apache/commons/collections/functors/NonePredicate.java +++ b/src/java/org/apache/commons/collections/functors/NonePredicate.java @@ -41,7 +41,9 @@ public final class NonePredicate implements Predicate, PredicateDecorator, Seria /** * Factory to create the predicate. - * + *

    + * If the array is size zero, the predicate always returns true. + * * @param predicates the predicates to check, cloned, not null * @return the any predicate * @throws IllegalArgumentException if the predicates array is null @@ -58,7 +60,9 @@ public final class NonePredicate implements Predicate, PredicateDecorator, Seria /** * Factory to create the predicate. - * + *

    + * If the collection is size zero, the predicate always returns true. + * * @param predicates the predicates to check, cloned, not null * @return the one predicate * @throws IllegalArgumentException if the predicates array is null diff --git a/src/java/org/apache/commons/collections/functors/OnePredicate.java b/src/java/org/apache/commons/collections/functors/OnePredicate.java index e031b0651..83cc23033 100644 --- a/src/java/org/apache/commons/collections/functors/OnePredicate.java +++ b/src/java/org/apache/commons/collections/functors/OnePredicate.java @@ -41,7 +41,10 @@ public final class OnePredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + *

    + * If the array is size zero, the predicate always returns false. + * If the array is size one, then that predicate is returned. + * * @param predicates the predicates to check, cloned, not null * @return the any predicate * @throws IllegalArgumentException if the predicates array is null @@ -61,7 +64,7 @@ public final class OnePredicate implements Predicate, PredicateDecorator, Serial /** * Factory to create the predicate. - * + * * @param predicates the predicates to check, cloned, not null * @return the one predicate * @throws IllegalArgumentException if the predicates array is null diff --git a/src/java/org/apache/commons/collections/functors/StringValueTransformer.java b/src/java/org/apache/commons/collections/functors/StringValueTransformer.java index 5a7eb305e..08e1ef60a 100644 --- a/src/java/org/apache/commons/collections/functors/StringValueTransformer.java +++ b/src/java/org/apache/commons/collections/functors/StringValueTransformer.java @@ -1,5 +1,5 @@ /* - * Copyright 2001-2004 The Apache Software Foundation + * Copyright 2001-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,8 +20,9 @@ import java.io.Serializable; import org.apache.commons.collections.Transformer; /** - * Transformer implementation that returns the String.valueOf. - * + * Transformer implementation that returns the result of calling + * String.valueOf on the input object. + * * @since Commons Collections 3.0 * @version $Revision$ $Date$ * diff --git a/src/java/org/apache/commons/collections/keyvalue/AbstractKeyValue.java b/src/java/org/apache/commons/collections/keyvalue/AbstractKeyValue.java index 6de7b85db..20b81ca1a 100644 --- a/src/java/org/apache/commons/collections/keyvalue/AbstractKeyValue.java +++ b/src/java/org/apache/commons/collections/keyvalue/AbstractKeyValue.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,7 +18,8 @@ package org.apache.commons.collections.keyvalue; import org.apache.commons.collections.KeyValue; /** - * Abstract pair class to assist with creating KeyValue and MapEntry implementations. + * Abstract pair class to assist with creating KeyValue + * and {@link java.util.Map.Entry Map.Entry} implementations. * * @since Commons Collections 3.0 * @version $Revision$ $Date$ @@ -29,12 +30,12 @@ import org.apache.commons.collections.KeyValue; * @author Stephen Colebourne */ public abstract class AbstractKeyValue implements KeyValue { - + /** The key */ protected Object key; /** The value */ protected Object value; - + /** * Constructs a new pair with the specified key and given value. * diff --git a/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntry.java b/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntry.java index 440ab977b..f35967678 100644 --- a/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntry.java +++ b/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntry.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,7 +18,8 @@ package org.apache.commons.collections.keyvalue; import java.util.Map; /** - * Abstract Pair class to assist with creating correct Map Entry implementations. + * Abstract Pair class to assist with creating correct + * {@link java.util.Map.Entry Map.Entry} implementations. * * @since Commons Collections 3.0 * @version $Revision$ $Date$ @@ -29,7 +30,7 @@ import java.util.Map; * @author Stephen Colebourne */ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.Entry { - + /** * Constructs a new entry with the given key and given value. * @@ -43,9 +44,10 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E // Map.Entry interface //------------------------------------------------------------------------- /** - * Sets the value stored in this Map Entry. + * Sets the value stored in this Map.Entry. *

    - * This Map Entry is not connected to a Map, so only the local data is changed. + * This Map.Entry is not connected to a Map, so only the + * local data is changed. * * @param value the new value * @return the previous value @@ -57,7 +59,7 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E } /** - * Compares this Map Entry with another Map Entry. + * Compares this Map.Entry with another Map.Entry. *

    * Implemented per API documentation of {@link java.util.Map.Entry#equals(Object)} * @@ -76,7 +78,7 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E (getKey() == null ? other.getKey() == null : getKey().equals(other.getKey())) && (getValue() == null ? other.getValue() == null : getValue().equals(other.getValue())); } - + /** * Gets a hashCode compatible with the equals method. *

    diff --git a/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntryDecorator.java b/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntryDecorator.java index bd924825e..76bae1f49 100644 --- a/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntryDecorator.java +++ b/src/java/org/apache/commons/collections/keyvalue/AbstractMapEntryDecorator.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,8 +20,8 @@ import java.util.Map; import org.apache.commons.collections.KeyValue; /** - * Provides a base decorator that allows additional functionality to be added - * to a Map Entry. + * Provides a base decorator that allows additional functionality to be + * added to a {@link java.util.Map.Entry Map.Entry}. * * @since Commons Collections 3.0 * @version $Revision$ $Date$ diff --git a/src/java/org/apache/commons/collections/keyvalue/DefaultKeyValue.java b/src/java/org/apache/commons/collections/keyvalue/DefaultKeyValue.java index 6f52fb8d7..0ac72a3df 100644 --- a/src/java/org/apache/commons/collections/keyvalue/DefaultKeyValue.java +++ b/src/java/org/apache/commons/collections/keyvalue/DefaultKeyValue.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,7 +20,8 @@ import java.util.Map; import org.apache.commons.collections.KeyValue; /** - * A mutable KeyValue pair that does not implement MapEntry. + * A mutable KeyValue pair that does not implement + * {@link java.util.Map.Entry Map.Entry}. *

    * Note that a DefaultKeyValue instance may not contain * itself as a key or value. @@ -53,7 +54,7 @@ public class DefaultKeyValue extends AbstractKeyValue { } /** - * Constructs a new pair from the specified KeyValue. + * Constructs a new pair from the specified KeyValue. * * @param pair the pair to copy, must not be null * @throws NullPointerException if the entry is null @@ -63,7 +64,7 @@ public class DefaultKeyValue extends AbstractKeyValue { } /** - * Constructs a new pair from the specified MapEntry. + * Constructs a new pair from the specified Map.Entry. * * @param entry the entry to copy, must not be null * @throws NullPointerException if the entry is null @@ -119,7 +120,7 @@ public class DefaultKeyValue extends AbstractKeyValue { //----------------------------------------------------------------------- /** - * Compares this Map Entry with another Map Entry. + * Compares this Map.Entry with another Map.Entry. *

    * Returns true if the compared object is also a DefaultKeyValue, * and its key and value are equal to this object's key and value. diff --git a/src/java/org/apache/commons/collections/keyvalue/DefaultMapEntry.java b/src/java/org/apache/commons/collections/keyvalue/DefaultMapEntry.java index 455799ec5..377dd4db1 100644 --- a/src/java/org/apache/commons/collections/keyvalue/DefaultMapEntry.java +++ b/src/java/org/apache/commons/collections/keyvalue/DefaultMapEntry.java @@ -1,5 +1,5 @@ /* - * Copyright 2001-2004 The Apache Software Foundation + * Copyright 2001-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -21,7 +21,7 @@ import org.apache.commons.collections.KeyValue; /** * A restricted implementation of {@link java.util.Map.Entry} that prevents - * the MapEntry contract from being broken. + * the Map.Entry contract from being broken. * * @since Commons Collections 3.0 * @version $Revision$ $Date$ @@ -32,7 +32,7 @@ import org.apache.commons.collections.KeyValue; * @author Stephen Colebourne */ public final class DefaultMapEntry extends AbstractMapEntry { - + /** * Constructs a new entry with the specified key and given value. * @@ -44,7 +44,7 @@ public final class DefaultMapEntry extends AbstractMapEntry { } /** - * Constructs a new entry from the specified KeyValue. + * Constructs a new entry from the specified KeyValue. * * @param pair the pair to copy, must not be null * @throws NullPointerException if the entry is null @@ -54,7 +54,7 @@ public final class DefaultMapEntry extends AbstractMapEntry { } /** - * Constructs a new entry from the specified MapEntry. + * Constructs a new entry from the specified Map.Entry. * * @param entry the entry to copy, must not be null * @throws NullPointerException if the entry is null diff --git a/src/java/org/apache/commons/collections/keyvalue/TiedMapEntry.java b/src/java/org/apache/commons/collections/keyvalue/TiedMapEntry.java index fa65e73cf..882f7fe61 100644 --- a/src/java/org/apache/commons/collections/keyvalue/TiedMapEntry.java +++ b/src/java/org/apache/commons/collections/keyvalue/TiedMapEntry.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -21,7 +21,7 @@ import java.util.Map; import org.apache.commons.collections.KeyValue; /** - * A Map Entry tied to a map underneath. + * A {@link java.util.Map.Entry Map.Entry} tied to a map underneath. *

    * This can be used to enable a map entry to make changes on the underlying * map, however this will probably mess up any iterators. @@ -40,7 +40,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable { private final Map map; /** The key */ private final Object key; - + /** * Constructs a new entry with the given Map and key. * @@ -88,7 +88,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable { } /** - * Compares this Map Entry with another Map Entry. + * Compares this Map.Entry with another Map.Entry. *

    * Implemented per API documentation of {@link java.util.Map.Entry#equals(Object)} * @@ -108,7 +108,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable { (key == null ? other.getKey() == null : key.equals(other.getKey())) && (value == null ? other.getValue() == null : value.equals(other.getValue())); } - + /** * Gets a hashCode compatible with the equals method. *

    @@ -121,7 +121,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable { return (getKey() == null ? 0 : getKey().hashCode()) ^ (value == null ? 0 : value.hashCode()); } - + /** * Gets a string version of the entry. * diff --git a/src/java/org/apache/commons/collections/keyvalue/UnmodifiableMapEntry.java b/src/java/org/apache/commons/collections/keyvalue/UnmodifiableMapEntry.java index b5f877c5f..3aaf00add 100644 --- a/src/java/org/apache/commons/collections/keyvalue/UnmodifiableMapEntry.java +++ b/src/java/org/apache/commons/collections/keyvalue/UnmodifiableMapEntry.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -21,8 +21,8 @@ import org.apache.commons.collections.KeyValue; import org.apache.commons.collections.Unmodifiable; /** - * A {@link java.util.Map.Entry} that throws UnsupportedOperationException - * when setValue is called. + * A {@link java.util.Map.Entry Map.Entry} that throws + * UnsupportedOperationException when setValue is called. * * @since Commons Collections 3.0 * @version $Revision$ $Date$ @@ -30,7 +30,7 @@ import org.apache.commons.collections.Unmodifiable; * @author Stephen Colebourne */ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmodifiable { - + /** * Constructs a new entry with the specified key and given value. * @@ -42,7 +42,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo } /** - * Constructs a new entry from the specified KeyValue. + * Constructs a new entry from the specified KeyValue. * * @param pair the pair to copy, must not be null * @throws NullPointerException if the entry is null @@ -52,7 +52,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo } /** - * Constructs a new entry from the specified MapEntry. + * Constructs a new entry from the specified Map.Entry. * * @param entry the entry to copy, must not be null * @throws NullPointerException if the entry is null @@ -60,7 +60,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo public UnmodifiableMapEntry(final Map.Entry entry) { super(entry.getKey(), entry.getValue()); } - + /** * Throws UnsupportedOperationException. * diff --git a/src/java/org/apache/commons/collections/list/GrowthList.java b/src/java/org/apache/commons/collections/list/GrowthList.java index d758ac877..1e1753055 100644 --- a/src/java/org/apache/commons/collections/list/GrowthList.java +++ b/src/java/org/apache/commons/collections/list/GrowthList.java @@ -1,5 +1,5 @@ /* - * Copyright 2005 The Apache Software Foundation + * Copyright 2005-2006 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -21,7 +21,7 @@ import java.util.Collections; import java.util.List; /** - * Decorates another List to make it seemlessly grow when + * Decorates another List to make it seamlessly grow when * indices larger than the list size are used on add and set, * avoiding most IndexOutOfBoundsExceptions. *

    @@ -34,7 +34,7 @@ import java.util.List; * not to use excessively large indices, as the internal list will grow to * match. *

    - * Trying to use any method other than add or set with an invalid inde will + * Trying to use any method other than add or set with an invalid index will * call the underlying list and probably result in an IndexOutOfBoundsException. *

    * Take care when using this list with null values, as @@ -45,12 +45,12 @@ import java.util.List; *

    * This class differs from {@link LazyList} because here growth occurs on * set and add, where LazyList grows on get. However, they - * could easily be used together by decorating twice. + * can be used together by decorating twice. * * @see LazyList * @since Commons Collections 3.2 * @version $Revision: 155406 $ $Date$ - * + * * @author Stephen Colebourne * @author Paul Legato */ diff --git a/src/java/org/apache/commons/collections/list/package.html b/src/java/org/apache/commons/collections/list/package.html index cfbf9c242..14aa36975 100644 --- a/src/java/org/apache/commons/collections/list/package.html +++ b/src/java/org/apache/commons/collections/list/package.html @@ -1,6 +1,6 @@