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

Remove trailing spaces. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1477779 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2013-04-30 18:55:24 +00:00
parent 0ba5e75432
commit b7430de759
26 changed files with 218 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/main/java/org/apache/commons/collections4/ArrayStack.java
View File

@ -26,7 +26,7 @@ import java.util.EmptyStackException;
* is therefore operates faster in environments where you do not need to
* worry about multiple thread contention.
* <p>
* The removal order of an <code>ArrayStack</code> is based on insertion
* The removal order of an <code>ArrayStack</code> is based on insertion
* order: The most recently added element is removed first. The iteration
* order is <i>not</i> the same as the removal order. The iterator returns
* elements from the bottom up.
@ -44,7 +44,7 @@ import java.util.EmptyStackException;
@Deprecated
public class ArrayStack<E> extends ArrayList<E> {
/** Ensure serialization compatibility */
/** Ensure serialization compatibility */
private static final long serialVersionUID = 2130079159931574599L;
/**
@ -57,7 +57,7 @@ public class ArrayStack<E> extends ArrayList<E> {
/**
* Constructs a new empty <code>ArrayStack</code> with an initial size.
*
*
* @param initialSize the initial size to use
* @throws IllegalArgumentException if the specified initial size
* is negative
@ -71,7 +71,7 @@ public class ArrayStack<E> extends ArrayList<E> {
* <p>
* This method exists for compatibility with <code>java.util.Stack</code>.
* New users of this class should use <code>isEmpty</code> instead.
*
*
* @return true if the stack is currently empty
*/
public boolean empty() {

26
src/main/java/org/apache/commons/collections4/Bag.java
View File

@ -28,7 +28,7 @@ import java.util.Set;
* Calling {@link #getCount(Object)} on <code>a</code> would return 2, while
* calling {@link #uniqueSet()} would return <code>{a, b, c}</code>.
* <p>
* <i>NOTE: This interface violates the {@link Collection} contract.</i>
* <i>NOTE: This interface violates the {@link Collection} contract.</i>
* The behavior specified in many of these methods is <i>not</i> the same
* as the behavior specified by <code>Collection</code>.
* The noncompliant methods are clearly marked with "(Violation)".
@ -48,7 +48,7 @@ public interface Bag<E> extends Collection<E> {
* Returns the number of occurrences (cardinality) of the given
* object currently in the bag. If the object does not exist in the
* bag, return 0.
*
*
* @param object the object to search for
* @return the number of occurrences of the object, zero if not found
*/
@ -63,7 +63,7 @@ public interface Bag<E> extends Collection<E> {
* {@link #uniqueSet()} and report its count as 1.
* <p>
* Since this method always increases the size of the bag,
* according to the {@link Collection#add(Object)} contract, it
* according to the {@link Collection#add(Object)} contract, it
* should always return <code>true</code>. Since it sometimes returns
* <code>false</code>, this method violates the contract.
*
@ -78,7 +78,7 @@ public interface Bag<E> extends Collection<E> {
* If the object is already in the {@link #uniqueSet()} then increment its
* count as reported by {@link #getCount(Object)}. Otherwise add it to the
* {@link #uniqueSet()} and report its count as <code>nCopies</code>.
*
*
* @param object the object to add
* @param nCopies the number of copies to add
* @return <code>true</code> if the object was not already in the <code>uniqueSet</code>
@ -105,7 +105,7 @@ public interface Bag<E> extends Collection<E> {
* <p>
* If the number of copies to remove is greater than the actual number of
* copies in the Bag, no error is thrown.
*
*
* @param object the object to remove
* @param nCopies the number of copies to remove
* @return <code>true</code> if this call changed the collection
@ -116,14 +116,14 @@ public interface Bag<E> extends Collection<E> {
* Returns a {@link Set} of unique elements in the Bag.
* <p>
* Uniqueness constraints are the same as those in {@link java.util.Set}.
*
*
* @return the Set of unique Bag elements
*/
Set<E> uniqueSet();
/**
* Returns the total number of items in the bag across all types.
*
*
* @return the total size of the Bag
*/
int size();
@ -140,7 +140,7 @@ public interface Bag<E> extends Collection<E> {
* that cardinality should <i>not</i> be respected; this method should
* return true if the bag contains at least one of every object contained
* in the given collection.
*
*
* @param coll the collection to check against
* @return <code>true</code> if the Bag contains all the collection
*/
@ -156,7 +156,7 @@ public interface Bag<E> extends Collection<E> {
*
* <p>The {@link Collection#removeAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* remove <i>all</i> occurrences of every object contained in the
* remove <i>all</i> occurrences of every object contained in the
* given collection.
*
* @param coll the collection to remove
@ -177,7 +177,7 @@ public interface Bag<E> extends Collection<E> {
*
* <p>The {@link Collection#retainAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* keep <i>all</i> occurrences of every object contained in the
* keep <i>all</i> occurrences of every object contained in the
* given collection.
*
* @param coll the collection to retain
@ -189,7 +189,7 @@ public interface Bag<E> extends Collection<E> {
* Returns an {@link Iterator} over the entire set of members,
* including copies due to cardinality. This iterator is fail-fast
* and will not tolerate concurrent modifications.
*
*
* @return iterator over all elements in the Bag
*/
Iterator<E> iterator();
@ -201,7 +201,7 @@ public interface Bag<E> extends Collection<E> {
// * This Bag equals another Bag if it contains the same number of occurrences of
// * the same elements.
// * This equals definition is compatible with the Set interface.
// *
// *
// * @param obj the Bag to compare to
// * @return true if equal
// */
@ -213,7 +213,7 @@ public interface Bag<E> extends Collection<E> {
// * The per element hash code is defined as
// * <code>(e==null ? 0 : e.hashCode()) ^ noOccurances)</code>.
// * This hash code definition is compatible with the Set interface.
// *
// *
// * @return the hash code of the Bag
// */
// int hashCode();

28
src/main/java/org/apache/commons/collections4/BagUtils.java
View File

@ -59,7 +59,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
*
*
* <pre>
* Bag bag = BagUtils.synchronizedBag(new HashBag());
* ...
@ -70,9 +70,9 @@ public class BagUtils {
* }
* }
* </pre>
*
*
* Failure to follow this advice may result in non-deterministic behavior.
*
*
* @param <E> the element type
* @param bag the bag to synchronize, must not be null
* @return a synchronized bag backed by that bag
@ -85,7 +85,7 @@ public class BagUtils {
/**
* Returns an unmodifiable view of the given bag. Any modification attempts
* to the returned bag will raise an {@link UnsupportedOperationException}.
*
*
* @param <E> the element type
* @param bag the bag whose unmodifiable view is to be returned, must not be null
* @return an unmodifiable view of that bag
@ -103,7 +103,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
*
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
* @param predicate the predicate for the bag, must not be null
@ -123,7 +123,7 @@ public class BagUtils {
* <p>
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see {@link TransformedBag#transformedBag(Bag, Transformer)}.
*
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
* @param transformer the transformer for the bag, must not be null
@ -142,7 +142,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
*
*
* <pre>
* SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
* ...
@ -153,9 +153,9 @@ public class BagUtils {
* }
* }
* </pre>
*
*
* Failure to follow this advice may result in non-deterministic behavior.
*
*
* @param <E> the element type
* @param bag the bag to synchronize, must not be null
* @return a synchronized bag backed by that bag
@ -169,7 +169,7 @@ public class BagUtils {
* Returns an unmodifiable view of the given sorted bag. Any modification
* attempts to the returned bag will raise an
* {@link UnsupportedOperationException}.
*
*
* @param <E> the element type
* @param bag the bag whose unmodifiable view is to be returned, must not be null
* @return an unmodifiable view of that bag
@ -188,7 +188,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
*
*
* @param <E> the element type
* @param bag the sorted bag to predicate, must not be null
* @param predicate the predicate for the bag, must not be null
@ -210,7 +210,7 @@ public class BagUtils {
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see
* {@link TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)}.
*
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
* @param transformer the transformer for the bag, must not be null
@ -230,7 +230,7 @@ public class BagUtils {
*/
@SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
public static <E> Bag<E> emptyBag() {
return (Bag<E>) EMPTY_BAG;
return (Bag<E>) EMPTY_BAG;
}
/**
@ -241,6 +241,6 @@ public class BagUtils {
*/
@SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
public static <E> SortedBag<E> emptySortedBag() {
return (SortedBag<E>) EMPTY_SORTED_BAG;
return (SortedBag<E>) EMPTY_SORTED_BAG;
}
}

18
src/main/java/org/apache/commons/collections4/BidiMap.java
View File

@ -29,8 +29,8 @@ package org.apache.commons.collections4;
* a key to be looked up from a value with equal performance.
* <p>
* This map enforces the restriction that there is a 1:1 relation between
* keys and values, meaning that multiple keys cannot map to the same value.
* This is required so that "inverting" the map results in a map without
* keys and values, meaning that multiple keys cannot map to the same value.
* This is required so that "inverting" the map results in a map without
* duplicate keys. See the {@link #put} method description for more information.
*
* @param <K> the type of the keys in the map
@ -51,7 +51,7 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* BidiMap map1 = new DualHashBidiMap();
* map.put("A","B"); // contains A mapped to B, as per Map
* map.put("A","C"); // contains A mapped to C, as per Map
*
*
* BidiMap map2 = new DualHashBidiMap();
* map.put("A","B"); // contains A mapped to B, as per Map
* map.put("C","B"); // contains C mapped to B, key A is removed
@ -60,9 +60,9 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* @param key the key to store
* @param value the value to store
* @return the previous value mapped to this key
*
*
* @throws UnsupportedOperationException if the <code>put</code> method is not supported
* @throws ClassCastException (optional) if the map limits the type of the
* @throws ClassCastException (optional) if the map limits the type of the
* value and the specified value is inappropriate
* @throws IllegalArgumentException (optional) if the map limits the values
* in some way and the value was invalid
@ -81,8 +81,8 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
*
* @param value the value to find the key for
* @return the mapped key, or <code>null</code> if not found
*
* @throws ClassCastException (optional) if the map limits the type of the
*
* @throws ClassCastException (optional) if the map limits the type of the
* value and the specified value is inappropriate
* @throws NullPointerException (optional) if the map limits the values to
* non-null and null was specified
@ -100,8 +100,8 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
*
* @param value the value to find the key-value pair for
* @return the key that was removed, <code>null</code> if nothing removed
*
* @throws ClassCastException (optional) if the map limits the type of the
*
* @throws ClassCastException (optional) if the map limits the type of the
* value and the specified value is inappropriate
* @throws NullPointerException (optional) if the map limits the values to
* non-null and null was specified

2
src/main/java/org/apache/commons/collections4/BoundedCollection.java
View File

@ -21,7 +21,7 @@ import java.util.Collection;
/**
* Defines a collection that is bounded in size.
* <p>
* The size of the collection can vary, but it can never exceed a preset
* The size of the collection can vary, but it can never exceed a preset
* maximum number of elements. This interface allows the querying of details
* associated with the maximum number of elements.
*

2
src/main/java/org/apache/commons/collections4/BoundedMap.java
View File

@ -19,7 +19,7 @@ package org.apache.commons.collections4;
/**
* Defines a map that is bounded in size.
* <p>
* The size of the map can vary, but it can never exceed a preset
* The size of the map can vary, but it can never exceed a preset
* maximum number of elements. This interface allows the querying of details
* associated with the maximum number of elements.
*

22
src/main/java/org/apache/commons/collections4/ComparatorUtils.java
View File

@ -30,8 +30,8 @@ import org.apache.commons.collections4.comparators.TransformingComparator;
* Provides convenient static utility methods for <Code>Comparator</Code>
* objects.
* <p>
* Most of the functionality in this class can also be found in the
* <code>comparators</code> package. This class merely provides a
* Most of the functionality in this class can also be found in the
* <code>comparators</code> package. This class merely provides a
* convenient central place if you have use for more than one class
* in the <code>comparators</code> subpackage.
*
@ -107,7 +107,7 @@ public class ComparatorUtils {
/**
* Gets a comparator that compares using a collection of {@link Comparator}s,
* applied in (default iterator) sequence until one returns not equal or the
* applied in (default iterator) sequence until one returns not equal or the
* collection is exhausted.
*
* @param <E> the object type to compare
@ -120,7 +120,7 @@ public class ComparatorUtils {
@SuppressWarnings("unchecked")
public static <E extends Comparable<? super E>> Comparator<E> chainedComparator(
final Collection<Comparator<E>> comparators) {
return chainedComparator(
(Comparator<E>[]) comparators.toArray(new Comparator[comparators.size()])
);
@ -144,8 +144,8 @@ public class ComparatorUtils {
* The parameter specifies whether true or false is sorted first.
* <p>
* The comparator throws NullPointerException if a null value is compared.
*
* @param trueFirst when <code>true</code>, sort
*
* @param trueFirst when <code>true</code>, sort
* <code>true</code> {@link Boolean}s before
* <code>false</code> {@link Boolean}s.
* @return a comparator that sorts booleans
@ -153,7 +153,7 @@ public class ComparatorUtils {
public static Comparator<Boolean> booleanComparator(final boolean trueFirst) {
return BooleanComparator.booleanComparator(trueFirst);
}
/**
* Gets a Comparator that controls the comparison of <code>null</code> values.
* <p>
@ -219,7 +219,7 @@ public class ComparatorUtils {
}
/**
* Returns the smaller of the given objects according to the given
* Returns the smaller of the given objects according to the given
* comparator, returning the second object if the comparator
* returns equal.
*
@ -239,8 +239,8 @@ public class ComparatorUtils {
}
/**
* Returns the larger of the given objects according to the given
* comparator, returning the second object if the comparator
* Returns the larger of the given objects according to the given
* comparator, returning the second object if the comparator
* returns equal.
*
* @param <E> the object type to compare
@ -257,5 +257,5 @@ public class ComparatorUtils {
final int c = comparator.compare(o1, o2);
return c > 0 ? o1 : o2;
}
}

4
src/main/java/org/apache/commons/collections4/EnumerationUtils.java
View File

@ -35,10 +35,10 @@ public class EnumerationUtils {
* EnumerationUtils is not normally instantiated.
*/
private EnumerationUtils() {}
/**
* Creates a list based on an enumeration.
*
*
* <p>As the enumeration is traversed, an ArrayList of its values is
* created. The new list is returned.</p>
*

10
src/main/java/org/apache/commons/collections4/FactoryUtils.java
View File

@ -48,7 +48,7 @@ public class FactoryUtils {
* This could be useful during testing as a placeholder.
*
* @see org.apache.commons.collections4.functors.ExceptionFactory
*
*
* @param <T> the type that the factory creates
* @return the factory
*/
@ -75,7 +75,7 @@ public class FactoryUtils {
* use the prototype factory.
*
* @see org.apache.commons.collections4.functors.ConstantFactory
*
*
* @param <T> the type that the factory creates
* @param constantToReturn the constant object to return each time in the factory
* @return the <code>constant</code> factory.
@ -95,7 +95,7 @@ public class FactoryUtils {
* <ul>
*
* @see org.apache.commons.collections4.functors.PrototypeFactory
*
*
* @param <T> the type that the factory creates
* @param prototype the object to clone each time in the factory
* @return the <code>prototype</code> factory, or a {@link ConstantFactory#NULL_INSTANCE} if
@ -111,7 +111,7 @@ public class FactoryUtils {
* a no-args constructor.
*
* @see org.apache.commons.collections4.functors.InstantiateFactory
*
*
* @param <T> the type that the factory creates
* @param classToInstantiate the Class to instantiate each time in the factory
* @return the <code>reflection</code> factory
@ -126,7 +126,7 @@ public class FactoryUtils {
* the arguments specified to this method.
*
* @see org.apache.commons.collections4.functors.InstantiateFactory
*
*
* @param <T> the type that the factory creates
* @param classToInstantiate the Class to instantiate each time in the factory
* @param paramTypes parameter types for the constructor, can be null

2
src/main/java/org/apache/commons/collections4/FunctorException.java
View File

@ -24,7 +24,7 @@ package org.apache.commons.collections4;
* @version $Id$
*/
public class FunctorException extends RuntimeException {
/** Serialization version */
private static final long serialVersionUID = -4704772662059351193L;

2
src/main/java/org/apache/commons/collections4/Get.java
View File

@ -21,7 +21,7 @@ import java.util.Set;
/**
* The "read" subset of the {@link java.util.Map} interface.
*
*
* @since 4.0
* @version $Id$
*

2
src/main/java/org/apache/commons/collections4/IterableGet.java
View File

@ -39,7 +39,7 @@ public interface IterableGet<K, V> extends Get<K, V> {
* it.setValue(value + 1);
* }
* </pre>
*
*
* @return a map iterator
*/
MapIterator<K, V> mapIterator();

2
src/main/java/org/apache/commons/collections4/KeyValue.java
View File

@ -33,7 +33,7 @@ public interface KeyValue<K, V> {
/**
* Gets the key from the pair.
*
* @return the key
* @return the key
*/
K getKey();

4
src/main/java/org/apache/commons/collections4/MultiMap.java
View File

@ -18,7 +18,7 @@ package org.apache.commons.collections4;
import java.util.Collection;
/**
/**
* Defines a map that holds a collection of values against each key.
* <p>
* A <code>MultiMap</code> is a Map with slightly different semantics.
@ -53,7 +53,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* If the last value for a key is removed, implementations typically
* return <code>null</code> from a subsequent <code>get(Object)</code>, however
* they may choose to return an empty collection.
*
*
* @param key the key to remove from
* @param item the item to remove
* @return the value removed (which was passed in), null if nothing removed

2
src/main/java/org/apache/commons/collections4/OrderedMap.java
View File

@ -33,7 +33,7 @@ public interface OrderedMap<K, V> extends IterableMap<K, V> {
* <p>
* A ordered map iterator is an efficient way of iterating over maps
* in both directions.
*
*
* @return a map iterator
*/
OrderedMapIterator<K, V> mapIterator();

4
src/main/java/org/apache/commons/collections4/Put.java
View File

@ -20,10 +20,10 @@ import java.util.Map;
/**
* The "write" subset of the {@link Map} interface.
*
*
* @since 4.0
* @version $Id$
*
*
* @see Get
*/
public interface Put<K, V> {

2
src/main/java/org/apache/commons/collections4/QueueUtils.java
View File

@ -77,7 +77,7 @@ public class QueueUtils {
* Returns a transformed queue backed by the given queue.
* <p>
* Each object is passed through the transformer as it is added to the
* Queue. It is important not to use the original queue after invoking this
* Queue. It is important not to use the original queue after invoking this
* method, as it is a backdoor for adding untransformed objects.
* <p>
* Existing entries in the specified queue will not be transformed.

2
src/main/java/org/apache/commons/collections4/ResettableIterator.java
View File

@ -18,7 +18,7 @@ package org.apache.commons.collections4;
import java.util.Iterator;
/**
/**
* Defines an iterator that can be reset back to an initial state.
* <p>
* This interface allows an iterator to be repeatedly reused.

2
src/main/java/org/apache/commons/collections4/ResettableListIterator.java
View File

@ -18,7 +18,7 @@ package org.apache.commons.collections4;
import java.util.ListIterator;
/**
/**
* Defines a list iterator that can be reset back to an initial state.
* <p>
* This interface allows an iterator to be repeatedly reused.

46
src/main/java/org/apache/commons/collections4/SetUtils.java
View File

@ -71,11 +71,11 @@ public class SetUtils {
private SetUtils() {}
//-----------------------------------------------------------------------
/**
* Returns an immutable empty set if the argument is <code>null</code>,
* or the argument itself otherwise.
*
*
* @param <T> the element type
* @param set the set, possibly <code>null</code>
* @return an empty set if the argument is <code>null</code>
@ -83,7 +83,7 @@ public class SetUtils {
public static <T> Set<T> emptyIfNull(final Set<T> set) {
return set == null ? Collections.<T>emptySet() : set;
}
/**
* Tests two sets for equality as per the <code>equals()</code> contract
* in {@link java.util.Set#equals(java.lang.Object)}.
@ -99,14 +99,14 @@ public class SetUtils {
* the second. This ensures that the <tt>equals</tt> method works
* properly across different implementations of the <tt>Set</tt>
* interface.</p>
*
*
* <p>
* This implementation first checks if the two sets are the same object:
* This implementation first checks if the two sets are the same object:
* if so it returns <tt>true</tt>. Then, it checks if the two sets are
* identical in size; if not, it returns false. If so, it returns
* <tt>a.containsAll((Collection) b)</tt>.</p>
* </blockquote>
*
*
* @see java.util.Set
* @param set1 the first set, may be null
* @param set2 the second set, may be null
@ -124,13 +124,13 @@ public class SetUtils {
}
/**
* Generates a hash code using the algorithm specified in
* Generates a hash code using the algorithm specified in
* {@link java.util.Set#hashCode()}.
* <p>
* This method is useful for implementing <code>Set</code> when you cannot
* extend AbstractSet. The method takes Collection instances to enable other
* collection types to use the Set implementation algorithm.
*
*
* @param <T> the element type
* @see java.util.Set#hashCode()
* @param set the set to calculate the hash code for, may be null
@ -149,14 +149,14 @@ public class SetUtils {
}
return hashCode;
}
//-----------------------------------------------------------------------
/**
* Returns a synchronized set backed by the given set.
* <p>
* You must manually synchronize on the returned set's iterator to
* You must manually synchronize on the returned set's iterator to
* avoid non-deterministic behavior:
*
*
* <pre>
* Set s = SetUtils.synchronizedSet(mySet);
* synchronized (s) {
@ -166,9 +166,9 @@ public class SetUtils {
* }
* }
* </pre>
*
*
* This method is just a wrapper for {@link Collections#synchronizedSet(Set)}.
*
*
* @param <E> the element type
* @param set the set to synchronize, must not be null
* @return a synchronized set backed by the given set
@ -214,7 +214,7 @@ public class SetUtils {
* Returns a transformed set backed by the given set.
* <p>
* Each object is passed through the transformer as it is added to the
* Set. It is important not to use the original set after invoking this
* Set. It is important not to use the original set after invoking this
* method, as it is a backdoor for adding untransformed objects.
* <p>
* Existing entries in the specified set will not be transformed.
@ -229,7 +229,7 @@ public class SetUtils {
public static <E> Set<E> transformedSet(final Set<E> set, final Transformer<? super E, ? extends E> transformer) {
return TransformedSet.transformingSet(set, transformer);
}
/**
* Returns a set that maintains the order of elements that are added
* backed by the given set.
@ -245,14 +245,14 @@ public class SetUtils {
public static <E> Set<E> orderedSet(final Set<E> set) {
return ListOrderedSet.listOrderedSet(set);
}
//-----------------------------------------------------------------------
/**
* Returns a synchronized sorted set backed by the given sorted set.
* <p>
* You must manually synchronize on the returned set's iterator to
* You must manually synchronize on the returned set's iterator to
* avoid non-deterministic behavior:
*
*
* <pre>
* Set s = SetUtils.synchronizedSet(mySet);
* synchronized (s) {
@ -262,9 +262,9 @@ public class SetUtils {
* }
* }
* </pre>
*
*
* This method is just a wrapper for {@link Collections#synchronizedSortedSet(SortedSet)}.
*
*
* @param <E> the element type
* @param set the sorted set to synchronize, must not be null
* @return a synchronized set backed by the given set
@ -289,7 +289,7 @@ public class SetUtils {
}
/**
* Returns a predicated (validating) sorted set backed by the given sorted set.
* Returns a predicated (validating) sorted set backed by the given sorted set.
* <p>
* Only objects that pass the test in the given predicate can be added to the set.
* Trying to add an invalid object results in an IllegalArgumentException.
@ -310,7 +310,7 @@ public class SetUtils {
* Returns a transformed sorted set backed by the given set.
* <p>
* Each object is passed through the transformer as it is added to the
* Set. It is important not to use the original set after invoking this
* Set. It is important not to use the original set after invoking this
* method, as it is a backdoor for adding untransformed objects.
* <p>
* Existing entries in the specified set will not be transformed.
@ -326,5 +326,5 @@ public class SetUtils {
final Transformer<? super E, ? extends E> transformer) {
return TransformedSortedSet.transformingSortedSet(set, transformer);
}
}

6
src/main/java/org/apache/commons/collections4/SortedBag.java
View File

@ -31,21 +31,21 @@ public interface SortedBag<E> extends Bag<E> {
/**
* Returns the comparator associated with this sorted set, or null
* if it uses its elements' natural ordering.
*
*
* @return the comparator in use, or null if natural ordering
*/
public Comparator<? super E> comparator();
/**
* Returns the first (lowest) member.
*
*
* @return the first element in the sorted bag
*/
public E first();
/**
* Returns the last (highest) member.
*
*
* @return the last element in the sorted bag
*/
public E last();

2
src/main/java/org/apache/commons/collections4/SortedBidiMap.java
View File

@ -25,7 +25,7 @@ import java.util.SortedMap;
* <p>
* Implementations should allow a value to be looked up from a key and
* a key to be looked up from a value with equal performance.
*
*
* @param <K> the type of the keys in the map
* @param <V> the type of the values in the map
* @since 3.0

76
src/main/java/org/apache/commons/collections4/TransformerUtils.java
View File

@ -35,7 +35,7 @@ import org.apache.commons.collections4.functors.StringValueTransformer;
import org.apache.commons.collections4.functors.SwitchTransformer;
/**
* <code>TransformerUtils</code> provides reference implementations and
* <code>TransformerUtils</code> provides reference implementations and
* utilities for the Transformer functor interface. The supplied transformers are:
* <ul>
* <li>Invoker - returns the result of a method call on the input object
@ -69,7 +69,7 @@ public class TransformerUtils {
/**
* Gets a transformer that always throws an exception.
* This could be useful during testing as a placeholder.
*
*
* @param <I> the input type
* @param <O> the output type
* @return the transformer
@ -81,7 +81,7 @@ public class TransformerUtils {
/**
* Gets a transformer that always returns null.
*
*
* @param <I> the input type
* @param <O> the output type
* @return the transformer
@ -95,7 +95,7 @@ public class TransformerUtils {
* Gets a transformer that returns the input object.
* The input object should be immutable to maintain the
* contract of Transformer (although this is not checked).
*
*
* @param <T> the input/output type
* @return the transformer
* @see org.apache.commons.collections4.functors.NOPTransformer
@ -113,7 +113,7 @@ public class TransformerUtils {
* <li>public copy constructor
* <li>serialization clone
* <ul>
*
*
* @param <T> the input/output type
* @return the transformer
* @see org.apache.commons.collections4.functors.CloneTransformer
@ -123,7 +123,7 @@ public class TransformerUtils {
}
/**
* Creates a Transformer that will return the same object each time the
* Creates a Transformer that will return the same object each time the
* transformer is used.
*
* @param <I> the input type
@ -182,7 +182,7 @@ public class TransformerUtils {
/**
* Create a new Transformer that calls two transformers, passing the result of
* the first into the second.
*
*
* @param <T> the input/output type
* @param transformer1 the first transformer
* @param transformer2 the second transformer
@ -198,9 +198,9 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls each transformer in turn, passing the
* Create a new Transformer that calls each transformer in turn, passing the
* result into the next transformer.
*
*
* @param <T> the input/output type
* @param transformers an array of transformers to chain
* @return the transformer
@ -212,10 +212,10 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls each transformer in turn, passing the
* Create a new Transformer that calls each transformer in turn, passing the
* result into the next transformer. The ordering is that of the iterator()
* method on the collection.
*
*
* @param <T> the input/output type
* @param transformers a collection of transformers to chain
* @return the transformer
@ -228,9 +228,9 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls one of two transformers depending
* Create a new Transformer that calls one of two transformers depending
* on the specified predicate.
*
*
* @param <I> the input type
* @param <O> the output type
* @param predicate the predicate to switch on
@ -249,11 +249,11 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls one of the transformers depending
* Create a new Transformer that calls one of the transformers depending
* on the predicates. The transformer at array location 0 is called if the
* predicate at array location 0 returned true. Each predicate is evaluated
* until one returns true. If no predicates evaluate to true, null is returned.
*
*
* @param <I> the input type
* @param <O> the output type
* @param predicates an array of predicates to check
@ -270,12 +270,12 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls one of the transformers depending
* Create a new Transformer that calls one of the transformers depending
* on the predicates. The transformer at array location 0 is called if the
* predicate at array location 0 returned true. Each predicate is evaluated
* until one returns true. If no predicates evaluate to true, the default
* transformer is called. If the default transformer is null, null is returned.
*
*
* @param <I> the input type
* @param <O> the output type
* @param predicates an array of predicates to check
@ -294,17 +294,17 @@ public class TransformerUtils {
}
/**
* Create a new Transformer that calls one of the transformers depending
* on the predicates.
* Create a new Transformer that calls one of the transformers depending
* on the predicates.
* <p>
* The Map consists of Predicate keys and Transformer values. A transformer
* The Map consists of Predicate keys and Transformer values. A transformer
* is called if its matching predicate returns true. Each predicate is evaluated
* until one returns true. If no predicates evaluate to true, the default
* transformer is called. The default transformer is set in the map with a
* transformer is called. The default transformer is set in the map with a
* null key. If no default transformer is set, null will be returned in a default
* case. The ordering is that of the iterator() method on the entryset collection
* case. The ordering is that of the iterator() method on the entryset collection
* of the map.
*
*
* @param <I> the input type
* @param <O> the output type
* @param predicatesAndTransformers a map of predicates to transformers
@ -321,13 +321,13 @@ public class TransformerUtils {
/**
* Create a new Transformer that uses the input object as a key to find the
* transformer to call.
* transformer to call.
* <p>
* The Map consists of object keys and Transformer values. A transformer
* The Map consists of object keys and Transformer values. A transformer
* is called if the input object equals the key. If there is no match, the
* default transformer is called. The default transformer is set in the map
* using a null key. If no default is set, null will be returned in a default case.
*
*
* @param <I> the input type
* @param <O> the output type
* @param objectsAndTransformers a map of objects to transformers
@ -357,7 +357,7 @@ public class TransformerUtils {
/**
* Gets a Transformer that expects an input Class object that it will instantiate.
*
*
* @param <T> the output type
* @return the transformer
* @see org.apache.commons.collections4.functors.InstantiateTransformer
@ -366,8 +366,8 @@ public class TransformerUtils {
return InstantiateTransformer.<T>instantiateTransformer();
}
/**
* Creates a Transformer that expects an input Class object that it will
/**
* Creates a Transformer that expects an input Class object that it will
* instantiate. The constructor used is determined by the arguments specified
* to this method.
*
@ -383,8 +383,8 @@ public class TransformerUtils {
return InstantiateTransformer.<T>instantiateTransformer(paramTypes, args);
}
/**
* Creates a Transformer that uses the passed in Map to transform the input
/**
* Creates a Transformer that uses the passed in Map to transform the input
* object (as a simple lookup).
*
* @param <I> the input type
@ -399,13 +399,13 @@ public class TransformerUtils {
/**
* Gets a Transformer that invokes a method on the input object.
* The method must have no parameters. If the input object is null,
* The method must have no parameters. If the input object is null,
* null is returned.
* <p>
* For example, <code>TransformerUtils.invokerTransformer("getName");</code>
* will call the <code>getName/code> method on the input object to
* will call the <code>getName/code> method on the input object to
* determine the transformer result.
*
*
* @param <I> the input type
* @param <O> the output type
* @param methodName the method name to call on the input object, may not be null
@ -419,9 +419,9 @@ public class TransformerUtils {
/**
* Gets a Transformer that invokes a method on the input object.
* The method parameters are specified. If the input object is {@code null},
* The method parameters are specified. If the input object is {@code null},
* {@code null} is returned.
*
*
* @param <I> the input type
* @param <O> the output type
* @param methodName the name of the method
@ -440,7 +440,7 @@ public class TransformerUtils {
* Gets a transformer that returns a <code>java.lang.String</code>
* representation of the input object. This is achieved via the
* <code>toString</code> method, <code>null</code> returns 'null'.
*
*
* @param <T> the input type
* @return the transformer
* @see org.apache.commons.collections4.functors.StringValueTransformer
@ -448,5 +448,5 @@ public class TransformerUtils {
public static <T> Transformer<T, String> stringValueTransformer() {
return StringValueTransformer.<T>stringValueTransformer();
}
}

150
src/main/java/org/apache/commons/collections4/Trie.java
View File

@ -21,16 +21,16 @@ import java.util.SortedMap;
import java.util.Map.Entry;
/**
* Defines the interface for a prefix tree, an ordered tree data structure. For
* Defines the interface for a prefix tree, an ordered tree data structure. For
* more information, see <a href="http://en.wikipedia.org/wiki/Trie">Tries</a>.
*
*
* @since 4.0
* @version $Id$
*/
public interface Trie<K, V> extends SortedMap<K, V> {
/**
* Returns the {@link Entry} whose key is closest in a bitwise XOR
* Returns the {@link Entry} whose key is closest in a bitwise XOR
* metric to the given key. This is NOT lexicographic closeness.
* For example, given the keys:
*
@ -39,60 +39,60 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* <li>H = 1001000
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
* @param key the key to use in the search
* @return the {@link Entry} whose key is closest in a bitwise XOR metric
* to the provided key
*/
public Map.Entry<K, V> select(K key);
/**
* Returns the key that is closest in a bitwise XOR metric to the
* Returns the key that is closest in a bitwise XOR metric to the
* provided key. This is NOT lexicographic closeness!
*
*
* For example, given the keys:
*
*
* <ol>
* <li>D = 1000100
* <li>H = 1001000
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
* @param key the key to use in the search
* @return the key that is closest in a bitwise XOR metric to the provided key
*/
public K selectKey(K key);
/**
* Returns the value whose key is closest in a bitwise XOR metric to
* Returns the value whose key is closest in a bitwise XOR metric to
* the provided key. This is NOT lexicographic closeness!
*
*
* For example, given the keys:
*
*
* <ol>
* <li>D = 1000100
* <li>H = 1001000
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H.
*
* @param key the key to use in the search
* @return the value whose key is closest in a bitwise XOR metric
* to the provided key
*/
public V selectValue(K key);
/**
* Iterates through the {@link Trie}, starting with the entry whose bitwise
* value is closest in an XOR metric to the given key. After the closest
@ -106,79 +106,79 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* and stop traversing.
* <p>
* Note: The {@link Cursor.Decision#REMOVE} operation is not supported.
*
*
* @param key the key to use in the search
* @param cursor the cursor used throughout the search
* @return the entry the cursor returned {@link Cursor.Decision#EXIT} on, or null
* @return the entry the cursor returned {@link Cursor.Decision#EXIT} on, or null
* if it continued till the end
*/
public Map.Entry<K,V> select(K key, Cursor<? super K, ? super V> cursor);
/**
* Traverses the {@link Trie} in lexicographical order.
* Traverses the {@link Trie} in lexicographical order.
* {@link Cursor#select(java.util.Map.Entry)} will be called on each entry.
* <p>
* The traversal will stop when the cursor returns {@link Cursor.Decision#EXIT},
* {@link Cursor.Decision#CONTINUE} is used to continue traversing and
* {@link Cursor.Decision#REMOVE} is used to remove the element that was selected
* The traversal will stop when the cursor returns {@link Cursor.Decision#EXIT},
* {@link Cursor.Decision#CONTINUE} is used to continue traversing and
* {@link Cursor.Decision#REMOVE} is used to remove the element that was selected
* and continue traversing.
* <p>
* {@link Cursor.Decision#REMOVE_AND_EXIT} is used to remove the current element
* and stop traversing.
*
*
* @param cursor the cursor used while traversing the {@link Trie}
* @return the entry the cursor returned {@link Cursor.Decision#EXIT} on, or null
* @return the entry the cursor returned {@link Cursor.Decision#EXIT} on, or null
* if it continued till the end
*/
public Map.Entry<K,V> traverse(Cursor<? super K, ? super V> cursor);
/**
* Returns a view of this {@link Trie} of all elements that are prefixed
* Returns a view of this {@link Trie} of all elements that are prefixed
* by the given key.
* <p>
* In a {@link Trie} with fixed size keys, this is essentially a
* In a {@link Trie} with fixed size keys, this is essentially a
* {@link #get(Object)} operation.
* <p>
* For example, if the {@link Trie} contains 'Anna', 'Anael',
* For example, if the {@link Trie} contains 'Anna', 'Anael',
* 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then
* a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'.
*
*
* @param key the key used in the search
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/
public SortedMap<K, V> getPrefixedBy(K key);
/**
* Returns a view of this {@link Trie} of all elements that are prefixed
* Returns a view of this {@link Trie} of all elements that are prefixed
* by the length of the key.
* <p>
* {@link Trie}s with fixed size keys will not support this operation
* {@link Trie}s with fixed size keys will not support this operation
* (because all keys are the same length).
* <p>
* For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for 'Andrey'
* For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for 'Andrey'
* and a length of 4 would return 'Andreas', 'Andrea', and 'Andres'.
*
*
* @param key the key used in the search
* @param length the length of the prefix
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/
public SortedMap<K, V> getPrefixedBy(K key, int length);
/**
* Returns a view of this {@link Trie} of all elements that are prefixed
* by the key, starting at the given offset and for the given length.
* <p>
* {@link Trie}s with fixed size keys will not support this operation
* {@link Trie}s with fixed size keys will not support this operation
* (because all keys are the same length).
* <p>
* For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for
* 'Hello Andrey Smith', an offset of 6 and a length of 4 would return
* For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for
* 'Hello Andrey Smith', an offset of 6 and a length of 4 would return
* 'Andreas', 'Andrea', and 'Andres'.
*
*
* @param key the key used in the search
* @param offset the prefix start
* @param length the length of the prefix
@ -186,27 +186,27 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* key is prefixed by the search key
*/
public SortedMap<K, V> getPrefixedBy(K key, int offset, int length);
/**
* Returns a view of this {@link Trie} of all elements that are prefixed
* by the number of bits in the given Key.
* <p>
* In {@link Trie}s with fixed size keys like IP addresses this method
* can be used to lookup partial keys. That is you can lookup all addresses
* that begin with '192.168' by providing the key '192.168.X.X' and a
* that begin with '192.168' by providing the key '192.168.X.X' and a
* length of 16.
*
*
* @param key the key to use in the search
* @param lengthInBits the number of significant key bits
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/
public SortedMap<K, V> getPrefixedByBits(K key, int lengthInBits);
/**
* Returns a view of this {@link Trie} of all elements that are prefixed
* by the number of bits in the given Key.
*
*
* @param key the key to use in the search
* @param offsetInBits the prefix offset
* @param lengthInBits the number of significant prefix bits
@ -214,39 +214,39 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* key is prefixed by the search key
*/
public SortedMap<K, V> getPrefixedByBits(K key, int offsetInBits, int lengthInBits);
/**
* A {@link Trie.Cursor} can be used to traverse a {@link Trie}, visit each node
* step by step and make {@link Decision}s on each step how to continue with
* A {@link Trie.Cursor} can be used to traverse a {@link Trie}, visit each node
* step by step and make {@link Decision}s on each step how to continue with
* traversing the {@link Trie}.
*/
public interface Cursor<K, V> {
/**
* The {@link Decision} tells the {@link Trie.Cursor} what to do on each step
* The {@link Decision} tells the {@link Trie.Cursor} what to do on each step
* while traversing the {@link Trie}.
*
* NOTE: Not all operations that work with a {@link Trie.Cursor} support all
*
* NOTE: Not all operations that work with a {@link Trie.Cursor} support all
* {@link Decision} types
*/
public static enum Decision {
/**
* Exit the traverse operation
*/
EXIT,
EXIT,
/**
* Continue with the traverse operation
*/
CONTINUE,
CONTINUE,
/**
* Remove the previously returned element
* from the {@link Trie} and continue
*/
REMOVE,
REMOVE,
/**
* Remove the previously returned element
* from the {@link Trie} and exit from the
@ -254,9 +254,9 @@ public interface Trie<K, V> extends SortedMap<K, V> {
*/
REMOVE_AND_EXIT;
}
/**
* Called for each {@link Entry} in the {@link Trie}. Return
* Called for each {@link Entry} in the {@link Trie}. Return
* {@link Decision#EXIT} to finish the {@link Trie} operation,
* {@link Decision#CONTINUE} to go to the next {@link Entry},
* {@link Decision#REMOVE} to remove the {@link Entry} and
@ -264,7 +264,7 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* remove the {@link Entry} and stop iterating.
* <p>
* Note: Not all operations support {@link Decision#REMOVE}.
*
*
* @param entry the current entry
* @return the {@link Decision} based on the current entry
*/

10
src/main/java/org/apache/commons/collections4/TrieUtils.java
View File

@ -21,7 +21,7 @@ import org.apache.commons.collections4.trie.UnmodifiableTrie;
/**
* A collection of {@link Trie} utilities.
*
*
* @since 4.0
* @version $Id$
*/
@ -31,19 +31,19 @@ public class TrieUtils {
* {@link TrieUtils} should not normally be instantiated.
*/
private TrieUtils() {}
/**
* Returns a synchronized instance of a {@link Trie}
*
*
* @see java.util.Collections#synchronizedMap(java.util.Map)
*/
public static <K, V> Trie<K, V> synchronizedTrie(final Trie<K, V> trie) {
return SynchronizedTrie.synchronizedTrie(trie);
}
/**
* Returns an unmodifiable instance of a {@link Trie}
*
*
* @see java.util.Collections#unmodifiableMap(java.util.Map)
*/
public static <K, V> Trie<K, V> unmodifiableTrie(final Trie<K, V> trie) {

2
src/main/java/org/apache/commons/collections4/Unmodifiable.java
View File

@ -29,7 +29,7 @@ package org.apache.commons.collections4;
* Of course all this only works if you use the Unmodifiable classes defined
* in this library. If you use the JDK unmodifiable class via {@code java.util Collections}
* then the interface won't be there.
*
*
* @since 3.0
* @version $Id$
*/