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

Javadoc 

- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments
This commit is contained in:
Gary Gregory 2024-10-20 17:01:23 -04:00
parent 96763c2612
commit 346c8e7e9e
26 changed files with 152 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
View File

@ -45,14 +45,17 @@ import org.apache.commons.collections4.iterators.EmptyMapIterator;
* Key-value entries are stored in instances of the {@code HashEntry} class,
* which can be overridden and replaced. The iterators can similarly be replaced,
* without the need to replace the KeySet, EntrySet and Values view classes.
* </p>
* <p>
* Overridable methods are provided to change the default hashing behavior, and
* to change how entries are added to and removed from the map. Hopefully, all you
* need for unusual subclasses is here.
* </p>
* <p>
* NOTE: From Commons Collections 3.1 this class extends AbstractMap.
* This is to provide backwards compatibility for ReferenceMap between v3.0 and v3.1.
* This extends clause will be removed in v5.0.
* </p>
*
* @param <K> the type of the keys in this map
* @param <V> the type of the values in this map
@ -651,6 +654,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* This implementation adds the entry to the data storage table.
* Subclasses could override to handle changes to the map.
* </p>
*
* @param entry the entry to add
* @param hashIndex the index into the data array to store at
@ -666,6 +670,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* and {@code checkCapacity()}.
* It also handles changes to {@code modCount} and {@code size}.
* Subclasses could override to fully control adds to the map.
* </p>
*
* @param hashIndex the index into the data array to store at
* @param hashCode the hash code of the key to add
@ -718,6 +723,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* Checks the capacity of the map and enlarges it if necessary.
* <p>
* This implementation uses the threshold to check if the map needs enlarging
* </p>
*/
protected void checkCapacity() {
if (size >= threshold) {
@ -745,6 +751,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* To implement {@code clone()}, a subclass must implement the
* {@code Cloneable} interface and make this method public.
* </p>
*
* @return a shallow clone
* @throws InternalError if {@link AbstractMap#clone()} failed
@ -827,6 +834,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* The reverse conversion can be changed, if required, by overriding the
* getKey() method in the hash entry.
* </p>
*
* @param key the key convert
* @return the converted key
@ -841,6 +849,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* This implementation creates a new HashEntry instance.
* Subclasses can override this to return a different storage class,
* or implement caching.
* </p>
*
* @param next the next entry in sequence
* @param hashCode the hash code to use
@ -896,6 +905,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* This implementation prepares the HashEntry for garbage collection.
* Subclasses can override this to implement caching (override clear as well).
* </p>
*
* @param entry the entry to destroy
*/
@ -913,13 +923,16 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* initialize the superclass before the subclass. Sometimes however, this isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
* </p>
* <p>
* The solution adopted here is to deserialize the state data of this class in
* this protected method. This method must be called by the
* {@code readObject()} of the first serializable subclass.
* </p>
* <p>
* Subclasses may override if the subclass has a specific field that must be present
* before {@code put()} or {@code calculateThreshold()} will work correctly.
* </p>
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
@ -948,14 +961,17 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* initialize the superclass before the subclass. Sometimes however, this isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
* </p>
* <p>
* The solution adopted here is to serialize the state data of this class in
* this protected method. This method must be called by the
* {@code writeObject()} of the first serializable subclass.
* </p>
* <p>
* Subclasses may override if they have a specific field that must be present
* on read before this implementation will work. Generally, the read determines
* what must be serialized here, if anything.
* </p>
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
@ -1137,6 +1153,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* This method exists for subclasses that may need to perform a multi-step
* process accessing the entry. The public methods in this class don't use this
* method to gain a small performance boost.
* </p>
*
* @param key the key
* @return the entry, null if no match
@ -1266,6 +1283,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* methods to get the key and value, and set the value.
* It avoids the need to create an entrySet/keySet/values object.
* It also avoids creating the Map.Entry object.
* </p>
*
* @return the map iterator
*/
@ -1308,6 +1326,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* This implementation iterates around the specified map and
* uses {@link #put(Object, Object)}.
* </p>
*
* @param map the map to add
* @throws NullPointerException if the map is null
@ -1356,6 +1375,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* This implementation removes the entry from the data storage table.
* The size is not updated.
* Subclasses could override to handle changes to the map.
* </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure
@ -1375,6 +1395,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* This implementation calls {@code removeEntry()} and {@code destroyEntry()}.
* It also handles changes to {@code modCount} and {@code size}.
* Subclasses could override to fully control removals from the map.
* </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure
@ -1392,6 +1413,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* This implementation sets all the data fields on the entry.
* Subclasses could populate additional entry fields.
* </p>
*
* @param entry the entry to update, not null
* @param hashIndex the index in the data array
@ -1454,6 +1476,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab
* <p>
* This implementation calls {@code setValue()} on the entry.
* Subclasses could override to handle changes to the map.
* </p>
*
* @param entry the entry to update
* @param newValue the new value to store

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

@ -426,6 +426,7 @@ public abstract class AbstractLinkedMap<K, V> extends AbstractHashedMap<K, V> im
* <p>
* This implementation adds the entry to the data storage table and
* to the end of the linked list.
* </p>
*
* @param entry the entry to add
* @param hashIndex the index into the data array to store at
@ -480,6 +481,7 @@ public abstract class AbstractLinkedMap<K, V> extends AbstractHashedMap<K, V> im
* Creates an entry to store the data.
* <p>
* This implementation creates a new LinkEntry instance.
* </p>
*
* @param next the next entry in sequence
* @param hashCode the hash code to use
@ -612,9 +614,10 @@ public abstract class AbstractLinkedMap<K, V> extends AbstractHashedMap<K, V> im
/**
* Initialize this subclass during construction.
* <p>
* NOTE: As from v3.2 this method calls
* Note: As from v3.2 this method calls
* {@link #createEntry(HashEntry, int, Object, Object)} to create
* the map entry object.
* </p>
*/
@Override
protected void init() {
@ -675,6 +678,7 @@ public abstract class AbstractLinkedMap<K, V> extends AbstractHashedMap<K, V> im
* <p>
* This implementation removes the entry from the linked list chain, then
* calls the superclass implementation.
* </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure

12
src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
View File

@ -221,6 +221,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* <p>
* This implementation uses {@code isEqualKey} and
* {@code isEqualValue} on the main map for comparison.
* </p>
*
* @param obj the other map entry to compare to
* @return true if equal, false if not
@ -797,13 +798,16 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* initialize the superclass before the subclass. Sometimes however, this isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
* </p>
* <p>
* The solution adopted here is to deserialize the state data of this class in
* this protected method. This method must be called by the
* {@code readObject()} of the first serializable subclass.
* </p>
* <p>
* Subclasses may override if the subclass has a specific field that must be present
* before {@code put()} or {@code calculateThreshold()} will work correctly.
* </p>
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
@ -846,14 +850,17 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* initialize the superclass before the subclass. Sometimes however, this isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
* </p>
* <p>
* The solution adopted here is to serialize the state data of this class in
* this protected method. This method must be called by the
* {@code writeObject()} of the first serializable subclass.
* </p>
* <p>
* Subclasses may override if they have a specific field that must be present
* on read before this implementation will work. Generally, the read determines
* what must be serialized here, if anything.
* </p>
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
@ -955,6 +962,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* <p>
* This implementation converts the key from the entry to a real reference
* before comparison.
* </p>
*
* @param key1 the first key to compare passed in from outside
* @param key2 the second key extracted from the entry via {@code entry.key}
@ -969,6 +977,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
/**
* Provided protected read-only access to the key type.
*
* @param type the type to check against.
* @return true if keyType has the specified type
*/
@ -978,6 +987,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
/**
* Provided protected read-only access to the value type.
*
* @param type the type to check against.
* @return true if valueType has the specified type
*/
@ -1016,6 +1026,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* care must be taken if, for instance, you want stale
* mappings to be removed on a periodic basis by some
* background thread.
* </p>
*/
protected void purge() {
Reference<?> ref = queue.poll();
@ -1073,6 +1084,7 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V>
* Purges stale mappings from this map before write operations.
* <p>
* This implementation calls {@link #purge()} to maintain a consistent state.
* </p>
*/
protected void purgeBeforeWrite() {
purge();

1
src/main/java/org/apache/commons/collections4/map/CompositeMap.java
View File

@ -387,6 +387,7 @@ public class CompositeMap<K, V> extends AbstractIterableMap<K, V> implements Ser
* <p>
* This implementation returns a {@code CompositeSet} which
* composites the key sets from all of the composited maps.
* </p>
*
* @return a set view of the keys contained in this map.
*/

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

@ -99,6 +99,7 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
* The transformer specified is called when a missing key is found.
* The key is passed to the transformer as the input, and the result
* will be returned as the result of the map get(key) method.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -117,6 +118,7 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
* Factory method to create a defaulting map.
* <p>
* The value specified is returned when a missing key is found.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -160,6 +162,7 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
* <p>
* The object passed in will be returned by the map whenever an
* unknown key is requested.
* </p>
*
* @param defaultValue the default value to return when the key is not found
*/

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

@ -287,6 +287,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
}
}
/**
* FlatMapIterator
*/
@ -392,10 +393,12 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
return "Iterator[]";
}
}
/**
* KeySet
*/
static class KeySet<K> extends AbstractSet<K> {
private final Flat3Map<K, ?> parent;
KeySet(final Flat3Map<K, ?> parent) {
@ -435,6 +438,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
return parent.size();
}
}
/**
* KeySetIterator
*/
@ -450,10 +454,12 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
return nextEntry().getKey();
}
}
/**
* Values
*/
static class Values<V> extends AbstractCollection<V> {
private final Flat3Map<?, V> parent;
Values(final Flat3Map<?, V> parent) {
@ -486,6 +492,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
return parent.size();
}
}
/**
* ValuesIterator
*/
@ -501,10 +508,13 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
return nextEntry().getValue();
}
}
/** Serialization version */
private static final long serialVersionUID = -6701087419741928296L;
/** The size of the map, used while in flat mode */
private transient int size;
/** Hash, used while in flat mode */
private transient int hash1;
@ -709,6 +719,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
* This can be overridden by subclasses to provide a different map implementation.
* Not every AbstractHashedMap is suitable, identity and reference based maps
* would be poor choices.
* </p>
*
* @return a new AbstractHashedMap or subclass
* @since 3.1
@ -724,6 +735,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
* NOTE: from 4.0, the returned Map Entry will be an independent object and will
* not change anymore as the iterator progresses. To avoid this additional object
* creation and simply iterate through the entries, use {@link #mapIterator()}.
* </p>
*
* @return the entrySet view
*/
@ -895,6 +907,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>, Serializable, Cloneabl
* methods to get the key and value, and set the value.
* It avoids the need to create an entrySet/keySet/values object.
* It also avoids creating the Map Entry object.
* </p>
*
* @return the map iterator
*/

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

@ -193,6 +193,7 @@ public class LRUMap<K, V>
* Constructor copying elements from another map.
* <p>
* The maximum size is set from the map's size.
* </p>
*
* @param map the map to copy
* @throws NullPointerException if the map is null
@ -223,10 +224,12 @@ public class LRUMap<K, V>
* <p>
* This implementation checks the LRU size and determines whether to
* discard an entry or not using {@link #removeLRU(AbstractLinkedMap.LinkEntry)}.
* </p>
* <p>
* From Commons Collections 3.1 this method uses {@link #isFull()} rather
* than accessing {@code size} and {@code maxSize} directly.
* It also handles the scanUntilRemovable functionality.
* </p>
*
* @param hashIndex the index into the data array to store at
* @param hashCode the hash code of the key to add
@ -327,6 +330,7 @@ public class LRUMap<K, V>
* If {@code updateToMRU} is {@code true}, the position of the key in the map
* is changed to the most recently used position (last), otherwise the iteration
* order is not changed by this operation.
* </p>
*
* @param key the key
* @param updateToMRU whether the key shall be updated to the
@ -380,6 +384,7 @@ public class LRUMap<K, V>
* Moves an entry to the MRU position at the end of the list.
* <p>
* This implementation moves the updated entry to the end of the list.
* </p>
*
* @param entry the entry to update
*/
@ -421,6 +426,7 @@ public class LRUMap<K, V>
* <p>
* This method exists for subclasses to override. A subclass may wish to
* provide cleanup of resources when an entry is removed. For example:
* </p>
* <pre>
* protected boolean removeLRU(LinkEntry entry) {
* releaseResources(entry.getValue()); // release resources held by entry
@ -430,6 +436,7 @@ public class LRUMap<K, V>
* <p>
* Alternatively, a subclass may choose to not remove the entry or selectively
* keep certain LRU entries. For example:
* </p>
* <pre>
* protected boolean removeLRU(LinkEntry entry) {
* if (entry.getKey().toString().startsWith("System.")) {
@ -439,13 +446,16 @@ public class LRUMap<K, V>
* }
* }
* </pre>
* <p>
* The effect of returning false is dependent on the scanUntilRemovable flag.
* If the flag is true, the next LRU entry will be passed to this method and so on
* until one returns false and is removed, or every entry in the map has been passed.
* If the scanUntilRemovable flag is false, the map will exceed the maximum size.
* </p>
* <p>
* NOTE: Commons Collections 3.0 passed the wrong entry to this method.
* Note: Commons Collections 3.0 passed the wrong entry to this method.
* This is fixed in version 3.1 onwards.
* </p>
*
* @param entry the entry to be removed
* @return {@code true}
@ -502,6 +512,7 @@ public class LRUMap<K, V>
* <p>
* This implementation moves the updated entry to the end of the list
* using {@link #moveToMRU(AbstractLinkedMap.LinkEntry)}.
* </p>
*
* @param entry the entry to update
* @param newValue the new value to store

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

@ -227,8 +227,10 @@ public class LinkedMap<K, V> extends AbstractLinkedMap<K, V> implements Serializ
* the end of the list, which is an unexpected side effect of changing the
* value of a list. This occurs because changing the key, changes when the
* mapping is added to the map and thus where it appears in the list.
* </p>
* <p>
* An alternative to this method is to use {@link #keySet()}.
* </p>
*
* @see #keySet()
* @return The ordered list of keys.

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

@ -380,6 +380,7 @@ public class ListOrderedMap<K, V>
* Factory method to create an ordered map.
* <p>
* An {@code ArrayList} is used to retain order.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -425,9 +426,11 @@ public class ListOrderedMap<K, V>
* the end of the list, which is an unexpected side effect of changing the
* value of a list. This occurs because changing the key, changes when the
* mapping is added to the map and thus where it appears in the list.
* </p>
* <p>
* An alternative to this method is to use the better named
* {@link #keyList()} or {@link #keySet()}.
* </p>
*
* @see #keyList()
* @see #keySet()
@ -447,6 +450,7 @@ public class ListOrderedMap<K, V>
* Gets a view over the entries in the map.
* <p>
* The Set will be ordered by object insertion into the map.
* </p>
*
* @return the fully modifiable set view over the entries
*/
@ -506,6 +510,7 @@ public class ListOrderedMap<K, V>
* <p>
* The List will be ordered by object insertion into the map.
* The List is unmodifiable.
* </p>
*
* @see #keySet()
* @return the unmodifiable list view over the keys
@ -519,6 +524,7 @@ public class ListOrderedMap<K, V>
* Gets a view over the keys in the map.
* <p>
* The Collection will be ordered by object insertion into the map.
* </p>
*
* @see #keyList()
* @return the fully modifiable collection view over the keys
@ -542,7 +548,6 @@ public class ListOrderedMap<K, V>
return insertOrder.get(size() - 1);
}
// Implement OrderedMap
@Override
public OrderedMapIterator<K, V> mapIterator() {
return new ListOrderedMapIterator<>(this);
@ -587,10 +592,12 @@ public class ListOrderedMap<K, V>
* is removed and the new mapping added at the specified index.
* The remove may change the effect of the index. The index is
* always calculated relative to the original state of the map.
* </p>
* <p>
* Thus, the steps are: (1) remove the existing key-value mapping,
* then (2) insert the new key-value mapping at the position it
* would have been inserted had the remove not occurred.
* </p>
*
* @param index the index at which the mapping should be inserted
* @param key the key
@ -751,6 +758,7 @@ public class ListOrderedMap<K, V>
* <p>
* The List will be ordered by object insertion into the map.
* The List supports remove and set, but does not support add.
* </p>
*
* @see #values()
* @return the partially modifiable list view over the values
@ -764,9 +772,11 @@ public class ListOrderedMap<K, V>
* Gets a view over the values in the map.
* <p>
* The Collection will be ordered by object insertion into the map.
* </p>
* <p>
* From Commons Collections 3.2, this Collection can be cast
* to a list, see {@link #valueList()}
* </p>
*
* @see #valueList()
* @return the fully modifiable collection view over the values

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

@ -684,6 +684,7 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has one or more keys, and the first matches that specified.
* </p>
*
* @param key1 the first key
* @return true if any elements were removed
@ -707,6 +708,7 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has two or more keys, and the first two match those specified.
* </p>
*
* @param key1 the first key
* @param key2 the second key
@ -732,6 +734,7 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has three or more keys, and the first three match those specified.
* </p>
*
* @param key1 the first key
* @param key2 the second key
@ -759,6 +762,7 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has four or more keys, and the first four match those specified.
* </p>
*
* @param key1 the first key
* @param key2 the second key

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

@ -273,6 +273,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* Checks whether the map contains the value specified.
* <p>
* This checks all collections against all keys for the value, and thus could be slow.
* </p>
*
* @param value the value to search for
* @return true if the map contains the value
@ -312,6 +313,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* <p>
* This method can be overridden to perform your own processing
* instead of using the factory.
* </p>
*
* @param size the collection size that is about to be added
* @return the new collection
@ -323,9 +325,10 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
/**
* {@inheritDoc}
* <p>
* NOTE: the returned Entry objects will contain as value a {@link Collection}
* Note: the returned Entry objects will contain as value a {@link Collection}
* of all values that are mapped to the given key. To get a "flattened" version
* of all mappings contained in this map, use {@link #iterator()}.
* </p>
*
* @see #iterator()
*/
@ -351,9 +354,11 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* <p>
* The iterator will return multiple Entry objects with the same key
* if there are multiple values mapped to this key.
* </p>
* <p>
* NOTE: calling {@link java.util.Map.Entry#setValue(Object)} on any of the returned
* Note: calling {@link java.util.Map.Entry#setValue(Object)} on any of the returned
* elements will result in a {@link UnsupportedOperationException}.
* </p>
*
* @return the iterator of all mappings in this map
* @since 4.0
@ -408,6 +413,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* <p>
* Unlike a normal {@code Map} the previous value is not replaced.
* Instead, the new value is added to the collection stored against the key.
* </p>
*
* @param key the key to store against
* @param value the value to add to the collection at the key
@ -468,6 +474,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* added using {@code put(Object,Object)}.
* If you call this method with a multi map, each entry is
* added using {@code putAll(Object,Collection)}.
* </p>
*
* @param map the map to copy (either a normal or multi map)
*/
@ -504,9 +511,11 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* <p>
* The item is removed from the collection mapped to the specified key.
* Other values attached to that key are unaffected.
* </p>
* <p>
* If the last value for a key is removed, {@code null} will be returned
* from a subsequent {@code get(key)}.
* </p>
*
* @param key the key to remove from
* @param value the value to remove
@ -559,6 +568,7 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
* Gets a collection containing all the values in the map.
* <p>
* This returns a collection containing the combination of values from all keys.
* </p>
*
* @return a collection view of the values contained in this map
*/

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

@ -419,11 +419,12 @@ public class PassiveExpiringMap<K, V>
}
/**
* Add the given key-value pair to this map as well as recording the entry's expiration time based on
* the current time in milliseconds and this map's {@link #expiringPolicy}.
* <p>
* {@inheritDoc}
*/
* {@inheritDoc}
* <p>
* Add the given key-value pair to this map as well as recording the entry's expiration time based on the current time in milliseconds and this map's
* {@link #expiringPolicy}.
* </p>
*/
@Override
public V put(final K key, final V value) {
// remove the previous record

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

@ -63,6 +63,7 @@ public class PredicatedMap<K, V>
* <p>
* If there are any elements already in the list being decorated, they
* are validated.
* </p>
*
* @param <K> the key type
* @param <V> the value type

1
src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
View File

@ -63,6 +63,7 @@ public class PredicatedSortedMap<K, V> extends PredicatedMap<K, V> implements So
* <p>
* If there are any elements already in the list being decorated, they
* are validated.
* </p>
*
* @param <K> the key type
* @param <V> the value type

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

@ -173,6 +173,7 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
* Gets the hash code for the key specified.
* <p>
* This implementation uses the identity hash code.
* </p>
*
* @param key the key to get a hash code for
* @return the hash code
@ -186,6 +187,7 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
* Gets the hash code for a MapEntry.
* <p>
* This implementation uses the identity hash code.
* </p>
*
* @param key the key to get a hash code for, may be null
* @param value the value to get a hash code for, may be null
@ -202,6 +204,7 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
* <p>
* This implementation converts the key from the entry to a real reference
* before comparison and uses {@code ==}.
* </p>
*
* @param key1 the first key to compare passed in from outside
* @param key2 the second key extracted from the entry via {@code entry.key}
@ -217,6 +220,7 @@ public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> imple
* Compares two values for equals.
* <p>
* This implementation uses {@code ==}.
* </p>
*
* @param value1 the first value to compare passed in from outside
* @param value2 the second value extracted from the entry via {@code getValue()}

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

@ -488,6 +488,7 @@ public class SingletonMap<K, V>
* <p>
* An IllegalArgumentException is thrown if the key does not match as the map
* is fixed size.
* </p>
*
* @param key the key to set, must be the key of the map
* @param value the value to set
@ -508,6 +509,7 @@ public class SingletonMap<K, V>
* The map must be of size 0 or size 1.
* If it is size 1, the key must match the key of this map otherwise an
* IllegalArgumentException is thrown.
* </p>
*
* @param map the map to add, must be size 0 or 1, and the key must match
* @throws NullPointerException if the map is null

41
src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
View File

@ -383,21 +383,20 @@ public final class StaticBucketMap<K, V> extends AbstractIterableMap<K, V> {
}
/**
* Prevents any operations from occurring on this map while the
* given {@link Runnable} executes. This method can be used, for
* instance, to execute a bulk operation atomically:
* Prevents any operations from occurring on this map while the given {@link Runnable} executes. This method can be used, for instance, to execute a bulk
* operation atomically:
* <pre>
* staticBucketMapInstance.atomic(new Runnable() {
* public void run() {
* staticBucketMapInstance.putAll(map);
* }
* });
* </pre>
* <p>
* It can also be used if you need a reliable iterator:
* </p>
*
* <pre>
* staticBucketMapInstance.atomic(new Runnable() {
* public void run() {
* staticBucketMapInstance.putAll(map);
* }
* });
* </pre>
*
* It can also be used if you need a reliable iterator:
*
* <pre>
* <pre>
* staticBucketMapInstance.atomic(new Runnable() {
* public void run() {
* Iterator iterator = staticBucketMapInstance.iterator();
@ -406,15 +405,13 @@ public final class StaticBucketMap<K, V> extends AbstractIterableMap<K, V> {
* }
* }
* });
* </pre>
* </pre>
* <p>
* <b>Implementation note:</b> This method requires a lot of time and a ton of stack space. Essentially a recursive algorithm is used to enter each bucket's
* monitor. If you have twenty thousand buckets in your map, then the recursive method will be invoked twenty thousand times. You have been warned.
* </p>
*
* <b>Implementation note:</b> This method requires a lot of time
* and a ton of stack space. Essentially a recursive algorithm is used
* to enter each bucket's monitor. If you have twenty thousand buckets
* in your map, then the recursive method will be invoked twenty thousand
* times. You have been warned.
*
* @param runnable the code to execute atomically
* @param runnable the code to execute atomically
*/
public void atomic(final Runnable runnable) {
atomic(Objects.requireNonNull(runnable, "runnable"), 0);

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

@ -63,6 +63,7 @@ public class TransformedMap<K, V>
* If there are any elements already in the map being decorated, they
* will be transformed by this method.
* Contrast this with {@link #transformingMap(Map, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -90,6 +91,7 @@ public class TransformedMap<K, V>
* If there are any elements already in the map being decorated, they
* are NOT transformed.
* Contrast this with {@link #transformedMap(Map, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -117,6 +119,7 @@ public class TransformedMap<K, V>
* <p>
* If there are any elements already in the collection being decorated, they
* are NOT transformed.
* </p>
*
* @param map the map to decorate, must not be null
* @param keyTransformer the transformer to use for key conversion, null means no conversion
@ -199,6 +202,7 @@ public class TransformedMap<K, V>
* Transforms a map.
* <p>
* The transformer itself may throw an exception if necessary.
* </p>
*
* @param map the map to transform
* @return the transformed object
@ -220,6 +224,7 @@ public class TransformedMap<K, V>
* Transforms a value.
* <p>
* The transformer itself may throw an exception if necessary.
* </p>
*
* @param object the object to transform
* @return the transformed object

5
src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
View File

@ -59,6 +59,7 @@ public class TransformedSortedMap<K, V>
* If there are any elements already in the map being decorated, they
* will be transformed by this method.
* Contrast this with {@link #transformingSortedMap(SortedMap, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -88,6 +89,7 @@ public class TransformedSortedMap<K, V>
* <p>
* If there are any elements already in the map being decorated, they are NOT transformed.
* Contrast this with {@link #transformedSortedMap(SortedMap, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -108,7 +110,8 @@ public class TransformedSortedMap<K, V>
* Constructor that wraps (not copies).
* <p>
* If there are any elements already in the collection being decorated, they
* are NOT transformed.</p>
* are NOT transformed.
* </p>
*
* @param map the map to decorate, must not be null
* @param keyTransformer the predicate to validate the keys, null means no transformation

1
src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
View File

@ -269,6 +269,7 @@ public abstract class AbstractListValuedMap<K, V> extends AbstractMultiValuedMap
* Removes all values associated with the specified key.
* <p>
* A subsequent {@code get(Object)} would return an empty list.
* </p>
*
* @param key the key to remove values from
* @return the {@code List} of values removed, will return an empty,

1
src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
View File

@ -115,6 +115,7 @@ public abstract class AbstractSetValuedMap<K, V> extends AbstractMultiValuedMap<
* Removes all values associated with the specified key.
* <p>
* A subsequent {@code get(Object)} would return an empty set.
* </p>
*
* @param key the key to remove values from
* @return the {@code Set} of values removed, will return an empty,

5
src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
View File

@ -53,6 +53,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
* If there are any elements already in the map being decorated, they will
* be transformed by this method. Contrast this with
* {@link #transformingMap(MultiValuedMap, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -81,6 +82,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
* If there are any elements already in the map being decorated, they are
* NOT transformed. Contrast this with
* {@link #transformedMap(MultiValuedMap, Transformer, Transformer)}.
* </p>
*
* @param <K> the key type
* @param <V> the value type
@ -107,6 +109,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
* <p>
* If there are any elements already in the collection being decorated, they
* are NOT transformed.
* </p>
*
* @param map the MultiValuedMap to decorate, may not be null
* @param keyTransformer the transformer to use for key conversion, null means no conversion
@ -159,6 +162,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
* Transforms a key.
* <p>
* The transformer itself may throw an exception if necessary.
* </p>
*
* @param object the object to transform
* @return the transformed object
@ -174,6 +178,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
* Transforms a value.
* <p>
* The transformer itself may throw an exception if necessary.
* </p>
*
* @param object the object to transform
* @return the transformed object

1
src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
View File

@ -52,6 +52,7 @@ public final class UnmodifiableMultiValuedMap<K, V>
* Factory method to create an unmodifiable MultiValuedMap.
* <p>
* If the map passed in is already unmodifiable, it is returned.
* </p>
*
* @param <K> the type of key elements
* @param <V> the type of value elements

3
src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
View File

@ -484,7 +484,8 @@ public abstract class AbstractMapMultiSet<E> extends AbstractMultiSet<E> {
/**
* Sets the map being wrapped.
* <p>
* <b>NOTE:</b> this method should only be used during deserialization
* <b>Note:</b> this method should only be used during deserialization
* </p>
*
* @param map the map to wrap
*/

1
src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
View File

@ -71,6 +71,7 @@ public class PredicatedMultiSet<E> extends PredicatedCollection<E> implements Mu
* <p>
* If there are any elements already in the multiset being decorated, they
* are validated.
* </p>
*
* @param multiset the multiset to decorate, must not be null
* @param predicate the predicate to use for validation, must not be null

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

@ -48,6 +48,7 @@ public final class UnmodifiableMultiSet<E>
* Factory method to create an unmodifiable multiset.
* <p>
* If the multiset passed in is already unmodifiable, it is returned.
* </p>
*
* @param <E> the type of the elements in the multiset
* @param multiset the multiset to decorate, may not be null