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

COLLECTIONS-653 fix Javadoc syntax for Java 8

This commit is contained in:
Bruno P. Kinoshita 2017-09-12 22:35:18 +12:00
parent 3633bbd32c
commit f98ef6d3ba
74 changed files with 335 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -432,7 +432,7 @@ public class CollectionUtils {
* Only those elements present in the collection will appear as
* keys in the map.
*
* @param <O> the type of object in the returned {@link Map}. This is a super type of <I>.
* @param <O> the type of object in the returned {@link Map}. This is a super type of &lt;I&gt;.
* @param coll the collection to get the cardinality map for, must not be null
* @return the populated cardinality map
*/
@ -483,7 +483,7 @@ public class CollectionUtils {
* <ul>
* <li><code>a.size()</code> and <code>b.size()</code> represent the
* total cardinality of <i>a</i> and <i>b</i>, resp. </li>
* <li><code>a.size() < Integer.MAXVALUE</code></li>
* <li><code>a.size() &lt; Integer.MAXVALUE</code></li>
* </ul>
*
* @param a the first (sub?) collection, must not be null
@ -833,7 +833,7 @@ public class CollectionUtils {
* Answers true if a predicate is true for every element of a
* collection.
* <p>
* A <code>null</code> predicate returns false.<br/>
* A <code>null</code> predicate returns false.<br>
* A <code>null</code> or empty collection returns true.
*
* @param <C> the type of object the {@link Iterable} contains

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

@ -94,11 +94,12 @@ public class FactoryUtils {
* Creates a Factory that will return a clone of the same prototype object
* each time the factory is used. The prototype will be cloned using one of these
* techniques (in order):
*
* <ul>
* <li>public clone method
* <li>public copy constructor
* <li>serialization clone
* <ul>
* <li>public clone method</li>
* <li>public copy constructor</li>
* <li>serialization clone</li>
* </ul>
*
* @see org.apache.commons.collections4.functors.PrototypeFactory
*

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

@ -47,7 +47,7 @@ import org.apache.commons.collections4.iterators.SingletonIterator;
* List&lt;String&gt; result =
* FluentIterable
* .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
* .filter(new Predicate<Integer>() {
* .filter(new Predicate&lt;Integer&gt;() {
* public boolean evaluate(Integer number) {
* return number % 2 == 0;
* }
@ -192,7 +192,7 @@ public class FluentIterable<E> implements Iterable<E> {
* @param other the other iterable to collate, may not be null
* @return a new iterable, collating this iterable with the other in natural order
* @throws NullPointerException if other is null
* @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator}
* @see org.apache.commons.collections4.iterators.CollatingIterator
*/
public FluentIterable<E> collate(final Iterable<? extends E> other) {
return of(IterableUtils.collatedIterable(iterable, other));
@ -217,7 +217,7 @@ public class FluentIterable<E> implements Iterable<E> {
* @param other the other iterable to collate, may not be null
* @return a new iterable, collating this iterable with the other in natural order
* @throws NullPointerException if other is null
* @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator}
* @see org.apache.commons.collections4.iterators.CollatingIterator
*/
public FluentIterable<E> collate(final Iterable<? extends E> other,
final Comparator<? super E> comparator) {
@ -231,7 +231,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* Calling this method is equivalent to:
* <pre>
* FluentIterable<E> someIterable = ...;
* FluentIterable&lt;E&gt; someIterable = ...;
* FluentIterable.of(someIterable.toList());
* </pre>
*

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

@ -30,46 +30,63 @@ import java.util.Set;
public interface Get<K, V> {
/**
* @param key key whose presence in this map is to be tested
* @return <tt>true</tt> if this map contains a mapping for the specified
* key
* @see java.util.Map#containsKey(Object)
*/
boolean containsKey(Object key);
/**
* @param value value whose presence in this map is to be tested
* @return <tt>true</tt> if this map maps one or more keys to the
* specified value
* @see java.util.Map#containsValue(Object)
*/
boolean containsValue(Object value);
/**
* @return a set view of the mappings contained in this map
* @see java.util.Map#entrySet()
*/
Set<java.util.Map.Entry<K, V>> entrySet();
/**
* @param key the key whose associated value is to be returned
* @return the value to which the specified key is mapped, or
* {@code null} if this map contains no mapping for the key
* @see java.util.Map#get(Object)
*/
V get(Object key);
/**
* @param key key whose mapping is to be removed from the map
* @return the previous value associated with <tt>key</tt>, or
* <tt>null</tt> if there was no mapping for <tt>key</tt>.
* @see java.util.Map#remove(Object)
*/
V remove(Object key);
/**
* @return <tt>true</tt> if this map contains no key-value mappings
* @see java.util.Map#isEmpty()
*/
boolean isEmpty();
/**
* @return a set view of the keys contained in this map
* @see java.util.Map#keySet()
*/
Set<K> keySet();
/**
* @return the number of key-value mappings in this map
* @see java.util.Map#size()
*/
int size();
/**
* @return a collection view of the values contained in this map
* @see java.util.Map#values()
*/
Collection<V> values();

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

@ -31,8 +31,8 @@ public interface IterableGet<K, V> extends Get<K, V> {
* A map iterator is an efficient way of iterating over maps.
* There is no need to access the entry set or use Map Entry objects.
* <pre>
* IterableMap<String,Integer> map = new HashedMap<String,Integer>();
* MapIterator<String,Integer> it = map.mapIterator();
* IterableMap&lt;String,Integer&gt; map = new HashedMap&lt;String,Integer&gt;();
* MapIterator&lt;String,Integer&gt; it = map.mapIterator();
* while (it.hasNext()) {
* String key = it.next();
* Integer value = it.getValue();

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

@ -24,8 +24,8 @@ import java.util.Map;
* A map iterator is an efficient way of iterating over maps.
* There is no need to access the entry set or use Map Entry objects.
* <pre>
* IterableMap<String,Integer> map = new HashedMap<String,Integer>();
* MapIterator<String,Integer> it = map.mapIterator();
* IterableMap&lt;String,Integer&gt; map = new HashedMap&lt;String,Integer&gt;();
* MapIterator&lt;String,Integer&gt; it = map.mapIterator();
* while (it.hasNext()) {
* String key = it.next();
* Integer value = it.getValue();

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

@ -1765,7 +1765,7 @@ public class MapUtils {
* @param <K> the key type
* @param <V> the value type
* @param map to wrap if necessary.
* @return IterableMap<K, V>
* @return IterableMap&lt;K, V&gt;
* @throws NullPointerException if map is null
* @since 4.0
*/
@ -1782,7 +1782,7 @@ public class MapUtils {
* @param <K> the key type
* @param <V> the value type
* @param sortedMap to wrap if necessary
* @return {@link IterableSortedMap}<K, V>
* @return {@link IterableSortedMap}&lt;K, V&gt;
* @throws NullPointerException if sortedMap is null
* @since 4.0
*/

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

@ -43,11 +43,19 @@ public interface Put<K, V> {
* Note that the return type is Object, rather than V as in the Map interface.
* See the class Javadoc for further info.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @return the previous value associated with <tt>key</tt>, or
* <tt>null</tt> if there was no mapping for <tt>key</tt>.
* (A <tt>null</tt> return can also indicate that the map
* previously associated <tt>null</tt> with <tt>key</tt>,
* if the implementation supports <tt>null</tt> values.)
* @see Map#put(Object, Object)
*/
Object put(K key, V value);
/**
* @param t mappings to be stored in this map
* @see Map#putAll(Map)
*/
void putAll(Map<? extends K, ? extends V> t);

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

@ -163,10 +163,10 @@ public class SetUtils {
* Returns a new hash set that matches elements based on <code>==</code> not
* <code>equals()</code>.
* <p>
* <strong>This set will violate the detail of various Set contracts.</note>
* <strong>This set will violate the detail of various Set contracts.</strong>
* As a general rule, don't compare this set to other sets. In particular, you can't
* use decorators like {@link ListOrderedSet} on it, which silently assume that these
* contracts are fulfilled.</strong>
* contracts are fulfilled.
* <p>
* <strong>Note that the returned set is not synchronized and is not thread-safe.</strong>
* If you wish to use this set from multiple threads concurrently, you must use

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

@ -53,7 +53,7 @@ public interface SortedBidiMap<K, V> extends OrderedBidiMap<K, V>, SortedMap<K,
/**
* Get the comparator used for the values in the value-to-key map aspect.
* @return Comparator<? super V>
* @return Comparator&lt;? super V&gt;
*/
Comparator<? super V> valueComparator();
}

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

@ -117,10 +117,10 @@ public class TransformerUtils {
* Gets a transformer that returns a clone of the input object.
* The input object will be cloned using one of these techniques (in order):
* <ul>
* <li>public clone method
* <li>public copy constructor
* <li>serialization clone
* <ul>
* <li>public clone method</li>
* <li>public copy constructor</li>
* <li>serialization clone</li>
* </ul>
*
* @param <T> the input/output type
* @return the transformer
@ -267,7 +267,7 @@ public class TransformerUtils {
* @return the transformer
* @throws NullPointerException if either the predicate or transformer is null
* @see SwitchTransformer
* @deprecated as of 4.1, use {@link #ifTransformer(Predicate, Transformer, Transformer))
* @deprecated as of 4.1, use {@link #ifTransformer(Predicate, Transformer, Transformer)}
*/
@SuppressWarnings("unchecked")
@Deprecated
@ -430,12 +430,14 @@ 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,
* null is returned.
* The method must have no parameters. If the input object is {@code null},
* {@code 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.
* </p>
*
* @param <I> the input type
* @param <O> the output type

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

@ -71,7 +71,7 @@ public final class CollectionBag<E> extends AbstractBagDecorator<E> {
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -82,8 +82,8 @@ public final class CollectionBag<E> extends AbstractBagDecorator<E> {
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @throws ClassCastException if deserialised object has wrong type
*/
@SuppressWarnings("unchecked") // will throw CCE, see Javadoc

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

@ -63,7 +63,7 @@ public final class CollectionSortedBag<E> extends AbstractSortedBagDecorator<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -74,8 +74,8 @@ public final class CollectionSortedBag<E> extends AbstractSortedBagDecorator<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @throws ClassCastException if deserialised object has wrong type
*/
@SuppressWarnings("unchecked") // will throw CCE, see Javadoc

7
src/main/java/org/apache/commons/collections4/bag/HashBag.java
View File

@ -61,6 +61,9 @@ public class HashBag<E> extends AbstractMapBag<E> implements Serializable {
//-----------------------------------------------------------------------
/**
* Write the bag out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -69,6 +72,10 @@ public class HashBag<E> extends AbstractMapBag<E> implements Serializable {
/**
* Read the bag in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

7
src/main/java/org/apache/commons/collections4/bag/TreeBag.java
View File

@ -120,6 +120,9 @@ public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>, Seria
//-----------------------------------------------------------------------
/**
* Write the bag out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -129,6 +132,10 @@ public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>, Seria
/**
* Read the bag in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -81,7 +81,7 @@ public final class UnmodifiableBag<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -92,8 +92,8 @@ public final class UnmodifiableBag<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @throws ClassCastException if deserialised object has wrong type
*/
@SuppressWarnings("unchecked") // will throw CCE, see Javadoc

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

@ -78,7 +78,7 @@ public final class UnmodifiableSortedBag<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -89,8 +89,8 @@ public final class UnmodifiableSortedBag<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @throws ClassCastException if deserialised object has wrong type
*/
@SuppressWarnings("unchecked") // will throw CCE, see Javadoc

7
src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java
View File

@ -1431,6 +1431,10 @@ public class TreeBidiMap<K extends Comparable<K>, V extends Comparable<V>>
/**
* Reads the content of the stream.
*
* @param stream the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked") // This will fail at runtime if the stream is incorrect
private void readObject(final ObjectInputStream stream) throws IOException, ClassNotFoundException{
@ -1446,6 +1450,9 @@ public class TreeBidiMap<K extends Comparable<K>, V extends Comparable<V>>
/**
* Writes the content to the stream for serialization.
*
* @param stream the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream stream) throws IOException{
stream.defaultWriteObject();

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

@ -415,7 +415,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable {
/**
* Get the collection mutator to be used for this CompositeCollection.
* @return CollectionMutator<E>
* @return CollectionMutator&lt;E&gt;
*/
protected CollectionMutator<E> getMutator() {
return mutator;

9
src/main/java/org/apache/commons/collections4/comparators/BooleanComparator.java
View File

@ -48,12 +48,13 @@ public final class BooleanComparator implements Comparator<Boolean>, Serializabl
/**
* Returns a BooleanComparator instance that sorts
* <code>true</code> values before <code>false</code> values.
* <p />
* <p>
* Clients are encouraged to use the value returned from
* this method instead of constructing a new instance
* to reduce allocation and garbage collection overhead when
* multiple BooleanComparators may be used in the same
* virtual machine.
* </p>
*
* @return the true first singleton BooleanComparator
*/
@ -64,12 +65,13 @@ public final class BooleanComparator implements Comparator<Boolean>, Serializabl
/**
* Returns a BooleanComparator instance that sorts
* <code>false</code> values before <code>true</code> values.
* <p />
* <p>
* Clients are encouraged to use the value returned from
* this method instead of constructing a new instance
* to reduce allocation and garbage collection overhead when
* multiple BooleanComparators may be used in the same
* virtual machine.
* </p>
*
* @return the false first singleton BooleanComparator
*/
@ -81,12 +83,13 @@ public final class BooleanComparator implements Comparator<Boolean>, Serializabl
* Returns a BooleanComparator instance that sorts
* <code><i>trueFirst</i></code> values before
* <code>&#x21;<i>trueFirst</i></code> values.
* <p />
* <p>
* Clients are encouraged to use the value returned from
* this method instead of constructing a new instance
* to reduce allocation and garbage collection overhead when
* multiple BooleanComparators may be used in the same
* virtual machine.
* </p>
*
* @param trueFirst when <code>true</code>, sort
* <code>true</code> <code>Boolean</code>s before <code>false</code>

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

@ -34,7 +34,7 @@ import org.apache.commons.collections4.FunctorException;
* };
*
* // use catch and re-throw closure
* java.util.List<String> strList = // some list
* java.util.List&lt;String&gt; strList = // some list
* try {
* CollectionUtils.forAllDo(strList, writer);
* } catch (FunctorException ex) {

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

@ -25,7 +25,7 @@ import org.apache.commons.collections4.Predicate;
* Predicate that compares the input object with the one stored in the predicate using a comparator.
* In addition, the comparator result can be evaluated in accordance to a supplied criterion value.
*
* In order to demonstrate the use of the predicate, the following variables are declared:
* <p>In order to demonstrate the use of the predicate, the following variables are declared:</p>
*
* <pre>
* Integer ONE = Integer.valueOf(1);
@ -40,14 +40,14 @@ import org.apache.commons.collections4.Predicate;
* };
* </pre>
*
* Using the declared variables, the <code>ComparatorPredicate</code> can be used used in the
* following way:
* <p>Using the declared variables, the <code>ComparatorPredicate</code> can be used used in the
* following way:</p>
*
* <pre>
* ComparatorPredicate.comparatorPredicate(ONE, comparator).evaluate(TWO);
* </pre>
*
* The input variable <code>TWO</code> in compared to the stored variable <code>ONE</code> using
* <p>The input variable <code>TWO</code> in compared to the stored variable <code>ONE</code> using
* the supplied <code>comparator</code>. This is the default usage of the predicate and will return
* <code>true</code> if the underlying comparator returns <code>0</code>. In addition to the default
* usage of the predicate, it is possible to evaluate the comparator's result in several ways. The
@ -62,16 +62,16 @@ import org.apache.commons.collections4.Predicate;
* <li>LESS_OR_EQUAL</li>
* </ul>
*
* The following examples demonstrates how these constants can be used in order to manipulate the
* evaluation of a comparator result.
* <p>The following examples demonstrates how these constants can be used in order to manipulate the
* evaluation of a comparator result.</p>
*
* <pre>
* ComparatorPredicate.comparatorPredicate(ONE, comparator,<b>ComparatorPredicate.Criterion.GREATER</b>).evaluate(TWO);
* </pre>
*
* The input variable TWO is compared to the stored variable ONE using the supplied <code>comparator</code>
* <p>The input variable TWO is compared to the stored variable ONE using the supplied <code>comparator</code>
* using the <code>GREATER</code> evaluation criterion constant. This instructs the predicate to
* return <code>true</code> if the comparator returns a value greater than <code>0</code>.
* return <code>true</code> if the comparator returns a value greater than <code>0</code>.</p>
*
* @since 4.0
* @version $Id$
@ -148,11 +148,11 @@ public class ComparatorPredicate<T> implements Predicate<T>, Serializable {
* Evaluates the predicate. The predicate evaluates to <code>true</code> in the following cases:
*
* <ul>
* <li><code>comparator.compare(object, input) == 0 && criterion == EQUAL</code></li>
* <li><code>comparator.compare(object, input) < 0 && criterion == LESS</code></li>
* <li><code>comparator.compare(object, input) > 0 && criterion == GREATER</code></li>
* <li><code>comparator.compare(object, input) >= 0 && criterion == GREATER_OR_EQUAL</code></li>
* <li><code>comparator.compare(object, input) <= 0 && criterion == LESS_OR_EQUAL</code></li>
* <li><code>comparator.compare(object, input) == 0 &amp;&amp; criterion == EQUAL</code></li>
* <li><code>comparator.compare(object, input) &lt; 0 &amp;&amp; criterion == LESS</code></li>
* <li><code>comparator.compare(object, input) &gt; 0 &amp;&amp; criterion == GREATER</code></li>
* <li><code>comparator.compare(object, input) &gt;= 0 &amp;&amp; criterion == GREATER_OR_EQUAL</code></li>
* <li><code>comparator.compare(object, input) &lt;= 0 &amp;&amp; criterion == LESS_OR_EQUAL</code></li>
* </ul>
*
* @see org.apache.commons.collections4.Predicate#evaluate(java.lang.Object)

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

@ -47,7 +47,7 @@ public class ConstantTransformer<I, O> implements Transformer<I, O>, Serializabl
*
* @param <I> the input type
* @param <O> the output type
* @return Transformer<I, O> that always returns null.
* @return Transformer&lt;I, O&gt; that always returns null.
*/
@SuppressWarnings("unchecked") // The null transformer works for all object types
public static <I, O> Transformer<I, O> nullTransformer() {

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

@ -48,7 +48,7 @@ public class InstantiateTransformer<T> implements Transformer<Class<? extends T>
* Get a typed no-arg instance.
*
* @param <T> the type of the objects to be created
* @return Transformer<Class<? extends T>, T>
* @return Transformer&lt;Class&lt;? extends T&gt;, T&gt;
*/
@SuppressWarnings("unchecked")
public static <T> Transformer<Class<? extends T>, T> instantiateTransformer() {

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

@ -48,11 +48,13 @@ public class PrototypeFactory {
* Creates a Factory that will return a clone of the same prototype object
* each time the factory is used. The prototype will be cloned using one of these
* techniques (in order):
* </p>
*
* <ul>
* <li>public clone method
* <li>public copy constructor
* <li>serialization clone
* <ul>
* <li>public clone method</li>
* <li>public copy constructor</li>
* <li>serialization clone</li>
* </ul>
*
* @param <T> the type the factory creates
* @param prototype the object to clone each time in the factory

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

@ -22,7 +22,7 @@ import java.util.NoSuchElementException;
import org.apache.commons.collections4.ResettableListIterator;
/**
* Implements a {@link ListIterator} over an array.
* Implements a {@link java.util.ListIterator} over an array.
* <p>
* The array can be either an array of object or of primitives. If you know
* that you have an object array, the {@link ObjectArrayListIterator}
@ -177,9 +177,9 @@ public class ArrayListIterator<E> extends ArrayIterator<E>
* This method sets the element that was returned by the last call
* to {@link #next()} of {@link #previous()}.
* <p>
* <b>Note:</b> {@link ListIterator} implementations that support
* <b>Note:</b> {@link java.util.ListIterator} implementations that support
* <code>add()</code> and <code>remove()</code> only allow <code>set()</code> to be called
* once per call to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
* once per call to <code>next()</code> or <code>previous</code> (see the {@link java.util.ListIterator}
* javadoc for more details). Since this implementation does
* not support <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
* called as often as desired.

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

@ -49,7 +49,7 @@ public class EmptyIterator<E> extends AbstractEmptyIterator<E> implements Resett
/**
* Get a typed resettable empty iterator instance.
* @param <E> the element type
* @return ResettableIterator<E>
* @return ResettableIterator&lt;E&gt;
*/
@SuppressWarnings("unchecked")
public static <E> ResettableIterator<E> resettableEmptyIterator() {
@ -59,7 +59,7 @@ public class EmptyIterator<E> extends AbstractEmptyIterator<E> implements Resett
/**
* Get a typed empty iterator instance.
* @param <E> the element type
* @return Iterator<E>
* @return Iterator&lt;E&gt;
*/
@SuppressWarnings("unchecked")
public static <E> Iterator<E> emptyIterator() {

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

@ -50,7 +50,7 @@ public class EmptyListIterator<E> extends AbstractEmptyIterator<E> implements
/**
* Get a typed instance of the iterator.
* @param <E> the element type
* @return {@link ResettableListIterator}<E>
* @return {@link ResettableListIterator}&lt;E&gt;
*/
@SuppressWarnings("unchecked")
public static <E> ResettableListIterator<E> resettableEmptyListIterator() {
@ -60,7 +60,7 @@ public class EmptyListIterator<E> extends AbstractEmptyIterator<E> implements
/**
* Get a typed instance of the iterator.
* @param <E> the element type
* @return {@link ListIterator}<E>
* @return {@link ListIterator}&lt;E&gt;
*/
@SuppressWarnings("unchecked")
public static <E> ListIterator<E> emptyListIterator() {

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

@ -39,7 +39,7 @@ public class EmptyMapIterator<K, V> extends AbstractEmptyMapIterator<K, V> imple
* Get a typed instance of the iterator.
* @param <K> the key type
* @param <V> the value type
* @return {@link MapIterator}<K, V>
* @return {@link MapIterator}&lt;K, V&gt;
*/
@SuppressWarnings("unchecked")
public static <K, V> MapIterator<K, V> emptyMapIterator() {

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

@ -38,7 +38,7 @@ public class EmptyOrderedIterator<E> extends AbstractEmptyIterator<E>
/**
* Typed instance of the iterator.
* @param <E> the element type
* @return OrderedIterator<E>
* @return OrderedIterator&lt;E&gt;
*/
@SuppressWarnings("unchecked")
public static <E> OrderedIterator<E> emptyOrderedIterator() {

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

@ -39,7 +39,7 @@ public class EmptyOrderedMapIterator<K, V> extends AbstractEmptyMapIterator<K, V
* Get a typed instance of the iterator.
* @param <K> the key type
* @param <V> the value type
* @return {@link OrderedMapIterator}<K, V>
* @return {@link OrderedMapIterator}&lt;K, V&gt;
*/
@SuppressWarnings("unchecked")
public static <K, V> OrderedMapIterator<K, V> emptyOrderedMapIterator() {

11
src/main/java/org/apache/commons/collections4/iterators/FilterListIterator.java
View File

@ -112,7 +112,10 @@ public class FilterListIterator<E> implements ListIterator<E> {
}
//-----------------------------------------------------------------------
/** Not supported. */
/**
* Not supported.
* @param o the element to insert
*/
@Override
public void add(final E o) {
throw new UnsupportedOperationException("FilterListIterator.add(Object) is not supported.");
@ -170,7 +173,11 @@ public class FilterListIterator<E> implements ListIterator<E> {
throw new UnsupportedOperationException("FilterListIterator.remove() is not supported.");
}
/** Not supported. */
/**
* Not supported.
* @param o the element with which to replace the last element returned by
* {@code next} or {@code previous}
*/
@Override
public void set(final E o) {
throw new UnsupportedOperationException("FilterListIterator.set(Object) is not supported.");

25
src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java
View File

@ -28,35 +28,38 @@ import org.apache.commons.collections4.ResettableIterator;
* operations use the same, exhausted source iterator. To create a single use
* iterable, construct a new {@link IteratorIterable} using a {@link Iterator}
* that is NOT a {@link ResettableIterator} iterator:
* <pre>
* Iterator<Integer> iterator = // some non-resettable iterator
* Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator);
* </pre>
* </p>
*
* <pre>
* Iterator&lt;Integer&gt; iterator = // some non-resettable iterator
* Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator);
* </pre>
*
* <p>
* In the multiple use iterable case, the iterable is usable for any number of
* iterative operations over the source iterator. Of special note, even though
* the iterable supports multiple iterations, it does not support concurrent
* iterations. To implicitly create a multiple use iterable, construct a new
* {@link IteratorIterable} using a {@link ResettableIterator} iterator:
* </p>
*
* <pre>
* Integer[] array = {Integer.valueOf(1),Integer.valueOf(2),Integer.valueOf(3)};
* Iterator<Integer> iterator = IteratorUtils.arrayIterator(array); // a resettable iterator
* Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator);
* Iterator&lt;Integer&gt; iterator = IteratorUtils.arrayIterator(array); // a resettable iterator
* Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator);
* </pre>
* </p>
*
* <p>
* A multiple use iterable can also be explicitly constructed using any
* {@link Iterator} and specifying <code>true</code> for the
* <code>multipleUse</code> flag:
* <pre>
* Iterator<Integer> iterator = // some non-resettable iterator
* Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator, true);
* </pre>
* </p>
*
* <pre>
* Iterator&lt;Integer&gt; iterator = // some non-resettable iterator
* Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator, true);
* </pre>
*
* @since 4.0
* @version $Id$
*/

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

@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
import org.apache.commons.collections4.ResettableListIterator;
/**
* Implements a {@link ListIterator} over an array of objects.
* Implements a {@link java.util.ListIterator} over an array of objects.
* <p>
* This iterator does not support {@link #add} or {@link #remove}, as the object array
* cannot be structurally modified. The {@link #set} method is supported however.
@ -168,9 +168,9 @@ public class ObjectArrayListIterator<E> extends ObjectArrayIterator<E>
* This method sets the element that was returned by the last call
* to {@link #next()} of {@link #previous()}.
*
* <b>Note:</b> {@link ListIterator} implementations that support <code>add()</code>
* <b>Note:</b> {@link java.util.ListIterator} implementations that support <code>add()</code>
* and <code>remove()</code> only allow <code>set()</code> to be called once per call
* to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
* to <code>next()</code> or <code>previous</code> (see the {@link java.util.ListIterator}
* javadoc for more details). Since this implementation does not support
* <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
* called as often as desired.

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

@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
import org.apache.commons.collections4.ResettableIterator;
/**
* <code>SingletonIterator</code> is an {@link Iterator} over a single
* <code>SingletonIterator</code> is an {@link java.util.Iterator} over a single
* object instance.
*
* @since 2.0

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

@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
import org.apache.commons.collections4.ResettableListIterator;
/**
* <code>SingletonIterator</code> is an {@link ListIterator} over a single
* <code>SingletonIterator</code> is an {@link java.util.ListIterator} over a single
* object instance.
*
* @since 2.1

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

@ -49,7 +49,7 @@ public abstract class AbstractSerializableListDecorator<E>
* Write the list out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -60,8 +60,8 @@ public abstract class AbstractSerializableListDecorator<E>
* Read the list in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

7
src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java
View File

@ -363,6 +363,9 @@ public class CursorableLinkedList<E> extends AbstractLinkedList<E> implements Se
//-----------------------------------------------------------------------
/**
* Serializes the data held in this object to the stream specified.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -371,6 +374,10 @@ public class CursorableLinkedList<E> extends AbstractLinkedList<E> implements Se
/**
* Deserializes the data held in this object to the stream specified.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

7
src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java
View File

@ -227,6 +227,9 @@ public class NodeCachingLinkedList<E> extends AbstractLinkedList<E> implements S
//-----------------------------------------------------------------------
/**
* Serializes the data held in this object to the stream specified.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -235,6 +238,10 @@ public class NodeCachingLinkedList<E> extends AbstractLinkedList<E> implements S
/**
* Deserializes the data held in this object to the stream specified.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -30,14 +30,17 @@ import org.apache.commons.collections4.set.AbstractSetDecorator;
* <p>
* The Map API is very difficult to decorate correctly, and involves implementing
* lots of different classes. This class exists to provide a simpler API.
* </p>
* <p>
* Special hook methods are provided that are called when objects are added to
* the map. By overriding these methods, the input can be validated or manipulated.
* In addition to the main map methods, the entrySet is also affected, which is
* the hardest part of writing map implementations.
* </p>
* <p>
* This class is package-scoped, and may be withdrawn or replaced in future
* versions of Commons Collections.
* </p>
*
* @since 3.1
* @version $Id$
@ -68,10 +71,13 @@ abstract class AbstractInputCheckedMapDecorator<K, V>
* <p>
* An implementation may validate the value and throw an exception
* or it may transform the value into another object.
* </p>
* <p>
* This implementation returns the input value.
* </p>
*
* @param value the value to check
* @return the input value
* @throws UnsupportedOperationException if the map may not be changed by setValue
* @throws IllegalArgumentException if the specified value is invalid
* @throws ClassCastException if the class of the specified value is invalid

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

@ -75,7 +75,7 @@ public abstract class AbstractLinkedMap<K, V> extends AbstractHashedMap<K, V> im
* Constructor which performs no validation on the passed in parameters.
*
* @param initialCapacity the initial capacity, must be a power of two
* @param loadFactor the load factor, must be > 0.0f and generally < 1.0f
* @param loadFactor the load factor, must be &gt; 0.0f and generally &lt; 1.0f
* @param threshold the threshold, must be sensible
*/
protected AbstractLinkedMap(final int initialCapacity, final float loadFactor, final int threshold) {

11
src/main/java/org/apache/commons/collections4/map/CaseInsensitiveMap.java
View File

@ -46,16 +46,18 @@ import java.util.Map;
* returns <code>"Four".</code> The <code>Set</code> returned by <code>keySet()</code>
* equals <code>{"one", "two", null}.</code>
* <p>
* <strong>This map will violate the detail of various Map and map view contracts.</note>
* <strong>This map will violate the detail of various Map and map view contracts.</strong>
* As a general rule, don't compare this map to other maps. In particular, you can't
* use decorators like {@link ListOrderedMap} on it, which silently assume that these
* contracts are fulfilled.
* </p>
* <p>
* <strong>Note that CaseInsensitiveMap is not synchronized and is not thread-safe.</strong>
* If you wish to use this map from multiple threads concurrently, you must use
* appropriate synchronization. The simplest approach is to wrap this map
* using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw
* exceptions when accessed by concurrent threads without synchronization.
* </p>
*
* @since 3.0
* @version $Id$
@ -144,6 +146,9 @@ public class CaseInsensitiveMap<K, V> extends AbstractHashedMap<K, V> implements
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -152,6 +157,10 @@ public class CaseInsensitiveMap<K, V> extends AbstractHashedMap<K, V> implements
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -174,7 +174,7 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -185,8 +185,8 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

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

@ -109,7 +109,7 @@ public class EntrySetToMapIteratorAdapter<K, V> implements MapIterator<K, V>, Re
/**
* Get the currently active entry.
* @return Map.Entry<K, V>
* @return Map.Entry&lt;K, V&gt;
*/
protected synchronized Map.Entry<K, V> current() {
if (entry == null) {

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

@ -89,7 +89,7 @@ public class FixedSizeMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -101,8 +101,8 @@ public class FixedSizeMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

7
src/main/java/org/apache/commons/collections4/map/FixedSizeSortedMap.java
View File

@ -98,6 +98,9 @@ public class FixedSizeSortedMap<K, V>
//-----------------------------------------------------------------------
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -106,6 +109,10 @@ public class FixedSizeSortedMap<K, V>
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

7
src/main/java/org/apache/commons/collections4/map/Flat3Map.java
View File

@ -1108,6 +1108,9 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
//-----------------------------------------------------------------------
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -1120,6 +1123,10 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

7
src/main/java/org/apache/commons/collections4/map/HashedMap.java
View File

@ -98,6 +98,9 @@ public class HashedMap<K, V>
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -106,6 +109,10 @@ public class HashedMap<K, V>
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

11
src/main/java/org/apache/commons/collections4/map/LRUMap.java
View File

@ -198,8 +198,8 @@ public class LRUMap<K, V>
/**
* Constructor copying elements from another map.
* <p/>
* The maximum size is set from the map's size.
*
* <p>The maximum size is set from the map's size.</p>
*
* @param map the map to copy
* @param scanUntilRemovable scan until a removeable entry is found, default false
@ -482,6 +482,9 @@ public class LRUMap<K, V>
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -490,6 +493,10 @@ public class LRUMap<K, V>
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -133,7 +133,7 @@ public class LazyMap<K, V> extends AbstractMapDecorator<K, V> implements Seriali
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -145,8 +145,8 @@ public class LazyMap<K, V> extends AbstractMapDecorator<K, V> implements Seriali
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked")

7
src/main/java/org/apache/commons/collections4/map/LinkedMap.java
View File

@ -118,6 +118,9 @@ public class LinkedMap<K, V> extends AbstractLinkedMap<K, V> implements Serializ
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -126,6 +129,10 @@ public class LinkedMap<K, V> extends AbstractLinkedMap<K, V> implements Serializ
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -128,7 +128,7 @@ public class ListOrderedMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -140,8 +140,8 @@ public class ListOrderedMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

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

@ -885,7 +885,7 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -896,8 +896,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

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

@ -156,7 +156,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 4.0
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -168,8 +168,8 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 4.0
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

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

@ -504,8 +504,8 @@ public class PassiveExpiringMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
// (1) should only fail if input stream is incorrect
@ -519,7 +519,7 @@ public class PassiveExpiringMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out)
throws IOException {

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

@ -108,7 +108,7 @@ public class PredicatedMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -120,8 +120,8 @@ public class PredicatedMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

16
src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
View File

@ -27,41 +27,48 @@ import java.lang.ref.Reference;
* removed by the garbage collector and matches keys and values based
* on <code>==</code> not <code>equals()</code>.
* <p>
* <p>
* When you construct a <code>ReferenceIdentityMap</code>, you can specify what kind
* of references are used to store the map's keys and values.
* If non-hard references are used, then the garbage collector can remove
* mappings if a key or value becomes unreachable, or if the JVM's memory is
* running low. For information on how the different reference types behave,
* see {@link Reference}.
* </p>
* <p>
* Different types of references can be specified for keys and values.
* The default constructor uses hard keys and soft values, providing a
* memory-sensitive cache.
* </p>
* <p>
* This map is similar to
* {@link org.apache.commons.collections4.map.ReferenceMap ReferenceMap}.
* It differs in that keys and values in this class are compared using <code>==</code>.
* </p>
* <p>
* This map will violate the detail of various Map and map view contracts.
* As a general rule, don't compare this map to other maps.
* </p>
* <p>
* This {@link java.util.Map Map} implementation does <i>not</i> allow null elements.
* Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
* </p>
* <p>
* This implementation is not synchronized.
* You can use {@link java.util.Collections#synchronizedMap} to
* provide synchronized access to a <code>ReferenceIdentityMap</code>.
* Remember that synchronization will not stop the garbage collector removing entries.
* </p>
* <p>
* All the available iterators can be reset back to the start by casting to
* <code>ResettableIterator</code> and calling <code>reset()</code>.
* </p>
* <p>
* <strong>Note that ReferenceIdentityMap is not synchronized and is not thread-safe.</strong>
* If you wish to use this map from multiple threads concurrently, you must use
* appropriate synchronization. The simplest approach is to wrap this map
* using {@link java.util.Collections#synchronizedMap}. This class may throw
* exceptions when accessed by concurrent threads without synchronization.
* </p>
*
* @see java.lang.ref.Reference
*
@ -223,6 +230,9 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
//-----------------------------------------------------------------------
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -231,6 +241,10 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

7
src/main/java/org/apache/commons/collections4/map/ReferenceMap.java
View File

@ -167,6 +167,9 @@ public class ReferenceMap<K, V> extends AbstractReferenceMap<K, V> implements Se
//-----------------------------------------------------------------------
/**
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -175,6 +178,10 @@ public class ReferenceMap<K, V> extends AbstractReferenceMap<K, V> implements Se
/**
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -132,7 +132,7 @@ public class TransformedMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -144,8 +144,8 @@ public class TransformedMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

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

@ -85,7 +85,7 @@ public final class UnmodifiableMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -97,8 +97,8 @@ public final class UnmodifiableMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked")

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

@ -83,7 +83,7 @@ public final class UnmodifiableOrderedMap<K, V> extends AbstractOrderedMapDecora
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -95,8 +95,8 @@ public final class UnmodifiableOrderedMap<K, V> extends AbstractOrderedMapDecora
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

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

@ -83,7 +83,7 @@ public final class UnmodifiableSortedMap<K, V>
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
* @since 3.1
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
@ -95,8 +95,8 @@ public final class UnmodifiableSortedMap<K, V>
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked")

7
src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
View File

@ -59,6 +59,9 @@ public class HashMultiSet<E> extends AbstractMapMultiSet<E> implements Serializa
//-----------------------------------------------------------------------
/**
* Write the multiset out using a custom routine.
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -67,6 +70,10 @@ public class HashMultiSet<E> extends AbstractMapMultiSet<E> implements Serializa
/**
* Read the multiset in using a custom routine.
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

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

@ -78,7 +78,7 @@ public final class UnmodifiableMultiSet<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -89,8 +89,8 @@ public final class UnmodifiableMultiSet<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @throws ClassCastException if deserialised object has wrong type
*/
@SuppressWarnings("unchecked") // will throw CCE, see Javadoc

4
src/main/java/org/apache/commons/collections4/multiset/package-info.java
View File

@ -16,14 +16,12 @@
*/
/**
* This package contains implementations of the
* {@link org.apache.commons.collections4.MultiSet MultiSet} and
* {@link org.apache.commons.collections4.SortedMultiSet SortedMultiSet} interfaces.
* {@link org.apache.commons.collections4.MultiSet MultiSet} interface.
* A multiset stores an object and a count of the number of occurrences of the object.
* <p>
* The following implementations are provided in the package:
* <ul>
* <li>HashMultiSet - implementation that uses a HashMap to store the data
* <li>TreeMultiSet - implementation that uses a TreeMap to store the data
* </ul>
* <p>
* The following decorators are provided in the package:

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

@ -97,7 +97,7 @@ package org.apache.commons.collections4.sequence;
* }
*
* private void display(String commandName, Object object) {
* System.out.println(commandName + " " + object + " ->" + this);
* System.out.println(commandName + " " + object + " -&gt;" + this);
* }
*
* public String toString() {

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

@ -49,7 +49,7 @@ public abstract class AbstractSerializableSetDecorator<E>
* Write the set out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -60,8 +60,8 @@ public abstract class AbstractSerializableSetDecorator<E>
* Read the set in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked")
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

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

@ -159,7 +159,7 @@ public final class UnmodifiableNavigableSet<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -170,8 +170,8 @@ public final class UnmodifiableNavigableSet<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

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

@ -130,7 +130,7 @@ public final class UnmodifiableSortedSet<E>
* Write the collection out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -141,8 +141,8 @@ public final class UnmodifiableSortedSet<E>
* Read the collection in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

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

@ -25,8 +25,8 @@ import org.apache.commons.collections4.MapIterator;
import org.apache.commons.collections4.map.EntrySetToMapIteratorAdapter;
/**
* {@link IterableGet} that uses a {@link Map}<K, V> for the
* {@link org.apache.commons.collections4.Get Get}<K, V> implementation.
* {@link IterableGet} that uses a {@link Map}&lt;K, V&gt; for the
* {@link org.apache.commons.collections4.Get Get}&lt;K, V&gt; implementation.
*
* @since 4.0
* @version $Id$
@ -111,7 +111,7 @@ public class AbstractIterableGetMapDecorator<K, V> implements IterableGet<K, V>
/**
* Get a MapIterator over this Get.
* @return MapIterator<K, V>
* @return MapIterator&lt;K, V&gt;
*/
@Override
public MapIterator<K, V> mapIterator() {

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

@ -121,7 +121,7 @@ public class TransformedSplitMap<J, K, U, V> extends AbstractIterableGetMapDecor
* Write the map out using a custom routine.
*
* @param out the output stream
* @throws IOException
* @throws IOException if an error occurs while writing to the stream
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -132,8 +132,8 @@ public class TransformedSplitMap<J, K, U, V> extends AbstractIterableGetMapDecor
* Read the map in using a custom routine.
*
* @param in the input stream
* @throws IOException
* @throws ClassNotFoundException
* @throws IOException if an error occurs while reading from the stream
* @throws ClassNotFoundException if an object read from the stream can not be loaded
* @since 3.1
*/
@SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect

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

@ -45,7 +45,7 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
private static final long serialVersionUID = 5155253417231339498L;
/** The root node of the {@link Trie}. */
/** The root node of the {@link org.apache.commons.collections4.Trie}. */
private transient TrieEntry<K, V> root = new TrieEntry<>(null, null, -1);
/**
@ -57,11 +57,11 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
private transient volatile Collection<V> values;
private transient volatile Set<Map.Entry<K,V>> entrySet;
/** The current size of the {@link Trie}. */
/** The current size of the {@link org.apache.commons.collections4.Trie}. */
private transient int size = 0;
/**
* The number of times this {@link Trie} has been modified.
* The number of times this {@link org.apache.commons.collections4.Trie} has been modified.
* It's used to detect concurrent modifications and fail-fast the {@link Iterator}s.
*/
protected transient int modCount = 0;
@ -71,8 +71,8 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
}
/**
* Constructs a new {@link org.apache.commons.collections4.Trie Trie} using the given
* {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie}
* Constructs a new {@link org.apache.commons.collections4.Trie org.apache.commons.collections4.Trie Trie}
* using the given {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie}
* with the values from the provided {@link Map}.
*/
protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer,
@ -271,7 +271,7 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* If the {@link org.apache.commons.collections4.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.
*
@ -300,7 +300,7 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* If the {@link org.apache.commons.collections4.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.
*
@ -327,7 +327,7 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
* <li>L = 1001100
* </ol>
*
* If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
* If the {@link org.apache.commons.collections4.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.
*
@ -1268,7 +1268,7 @@ abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, V> {
}
/**
* A {@link Trie} is a set of {@link TrieEntry} nodes.
* A {@link org.apache.commons.collections4.Trie} is a set of {@link TrieEntry} nodes.
*/
protected static class TrieEntry<K,V> extends BasicEntry<K, V> {

21
src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java
View File

@ -24,10 +24,12 @@ import org.apache.commons.collections4.trie.analyzer.StringKeyAnalyzer;
* Implementation of a PATRICIA Trie (Practical Algorithm to Retrieve Information
* Coded in Alphanumeric).
* <p>
* A PATRICIA {@link Trie} is a compressed {@link Trie}. Instead of storing
* all data at the edges of the {@link Trie} (and having empty internal nodes),
* PATRICIA stores data in every node. This allows for very efficient traversal,
* insert, delete, predecessor, successor, prefix, range, and {@link #select(Object)}
* A PATRICIA {@link org.apache.commons.collections4.Trie} is a compressed
* {@link org.apache.commons.collections4.Trie}. Instead of storing
* all data at the edges of the {@link org.apache.commons.collections4.Trie}
* (and having empty internal nodes), PATRICIA stores data in every node.
* This allows for very efficient traversal, insert, delete, predecessor,
* successor, prefix, range, and {@link #select(Object)}
* operations. All operations are performed at worst in O(K) time, where K
* is the number of bits in the largest item in the tree. In practice,
* operations actually take O(A(K)) time, where A(K) is the average number of
@ -38,15 +40,16 @@ import org.apache.commons.collections4.trie.analyzer.StringKeyAnalyzer;
* K of them, described above) will perform a single bit comparison against
* the given key, instead of comparing the entire key to another key.
* <p>
* The {@link Trie} can return operations in lexicographical order using the
* 'prefixMap', 'submap', or 'iterator' methods. The {@link Trie} can also
* The {@link org.apache.commons.collections4.Trie} can return operations in
* lexicographical order using the 'prefixMap', 'submap', or 'iterator' methods.
* The {@link org.apache.commons.collections4.Trie} can also
* scan for items that are 'bitwise' (using an XOR metric) by the 'select' method.
* Bitwise closeness is determined by the {@link KeyAnalyzer} returning true or
* false for a bit being set or not in a given key.
* <p>
* This PATRICIA {@link Trie} supports both variable length & fixed length
* keys. Some methods, such as {@link #prefixMap(Object)} are suited only
* to variable length keys.
* This PATRICIA {@link org.apache.commons.collections4.Trie} supports both variable
* length &amp; fixed length keys. Some methods, such as {@link #prefixMap(Object)}
* are suited only to variable length keys.
*
* @see <a href="http://en.wikipedia.org/wiki/Radix_tree">Radix Tree</a>
* @see <a href="http://www.csse.monash.edu.au/~lloyd/tildeAlgDS/Tree/PATRICIA">PATRICIA</a>