Top Description Fields Constructors Methods
org.apache.commons.collections4.collection

public Class IndexedCollection<K, C>

extends AbstractCollectionDecorator<C>
Class Inheritance
Type Parameters
<K>
the type of object in the index.
<C>
the type of object in the collection.
Imports
java.util.Collection, .HashMap, .Iterator, .Objects, java.util.function.Predicate, org.apache.commons.collections4.MultiMap, .Transformer, org.apache.commons.collections4.map.MultiValueMap
An IndexedCollection is a Map-like view onto a Collection. It accepts a keyTransformer to define how the keys are converted from the values.

Modifications made to this decorator modify the index as well as the decorated Collection. However, modifications to the underlying Collection will not update the index and it will get out of sync.

If modification of the decorated Collection is unavoidable, then a call to reindex() will update the index to the current contents of the Collection.

Since
4.0

Field Summary

Modifier and TypeField and Description
private final MultiMap<K, C>
index

The map of indexes to collected objects.

private final Transformer<C, K>
keyTransformer

The Transformer for generating index keys.

private static final long
serialVersionUID

Hides org.apache.commons.collections4.collection.AbstractCollectionDecorator.serialVersionUID.

Serialization version
private final boolean
uniqueIndex

The uniqueness constraint for the index.

Constructor Summary

AccessConstructor and Description
public
IndexedCollection(final Collection<C>
decorated Collection
coll, final Transformer<C, K>
Transformer for generating index keys
keyTransformer, final MultiMap<K, C>
map to use as index
map, final boolean
if the index shall enforce uniqueness of index keys
uniqueIndex)

Deprecated as a consequence of MultiMap being deprecated.
Create a IndexedCollection.

Method Summary

Modifier and TypeMethod and Description
public boolean
add(final C
element whose presence in this collection is to be ensured
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements java.util.Collection.add.

Ensures that this collection contains the specified element (optional operation).
public boolean
addAll(final Collection<? extends C>
collection containing elements to be added to this collection
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Collection.addAll.

Adds all of the elements in the specified collection to this collection (optional operation).
private void
addToIndex(final C
the object to index
object)

Provides checking for adding the index.

public void
clear()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.clear.

Implements java.util.Collection.clear.

Removes all of the elements from this collection (optional operation).
public boolean
contains(final Object
element whose presence in this collection is to be tested
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.contains.

Implements java.util.Collection.contains.

Returns true if this collection contains the specified element.
public boolean
containsAll(final Collection<?>
collection to be checked for containment in this collection
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.containsAll.

Implements java.util.Collection.containsAll.

Returns true if this collection contains all of the elements in the specified collection.
public C

Returns:

element found
get(final K
key to look up
key)

Get the element associated with the given key.

public static <
the index object type.
K,
the collection type.
C> IndexedCollection<K, C>

Returns:

the created IndexedCollection.
nonUniqueIndexedCollection(final Collection<C>
the decorated Collection.
coll, final Transformer<C, K>
the Transformer for generating index keys.
keyTransformer)

Create an IndexedCollection for a non-unique index.

public void
reindex()

Clears the index and re-indexes the entire decorated Collection.

public boolean
remove(final Object
element to be removed from this collection, if present
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements java.util.Collection.remove.

Removes a single instance of the specified element from this collection, if it is present (optional operation).
public boolean
removeAll(final Collection<?>
collection containing elements to be removed from this collection
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements java.util.Collection.removeAll.

Removes all of this collection's elements that are also contained in the specified collection (optional operation).
private void
removeFromIndex(final C
the object to remove
object)

Removes an object from the index.

public boolean
removeIf(final Predicate<? super C>
a predicate which returns true for elements to be removed
filter)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeIf.

Overrides default java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate.
public boolean
retainAll(final Collection<?>
collection containing elements to be retained in this collection
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements java.util.Collection.retainAll.

Retains only the elements in this collection that are contained in the specified collection (optional operation).
public static <
the index object type.
K,
the collection type.
C> IndexedCollection<K, C>

Returns:

the created IndexedCollection.
uniqueIndexedCollection(final Collection<C>
the decorated Collection.
coll, final Transformer<C, K>
the Transformer for generating index keys.
keyTransformer)

Create an IndexedCollection for a unique index.

public Collection<C>

Returns:

a collection of elements found, or null if contains(key) == false
values(final K
key to look up
key)

Get all elements associated with the given key.

Inherited from org.apache.commons.collections4.collection.AbstractCollectionDecorator:
decoratedisEmptyiteratorsetCollectionsizetoArraytoArraytoString

Field Detail

indexback to summary
private final MultiMap<K, C> index

Deprecated

as a consequence of MultiMap being deprecated. See corresponding docs for further information.

The map of indexes to collected objects.

keyTransformerback to summary
private final Transformer<C, K> keyTransformer

The Transformer for generating index keys.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.collections4.collection.AbstractCollectionDecorator.serialVersionUID.

Serialization version

uniqueIndexback to summary
private final boolean uniqueIndex

The uniqueness constraint for the index.

Constructor Detail

IndexedCollectionback to summary
public IndexedCollection(final Collection<C> coll, final Transformer<C, K> keyTransformer, final MultiMap<K, C> map, final boolean uniqueIndex)

Deprecated

as a consequence of MultiMap being deprecated. See corresponding docs for further information.

Create a IndexedCollection.

Parameters
coll:Collection<C>

decorated Collection

keyTransformer:Transformer<C, K>

Transformer for generating index keys

map:MultiMap<K, C>

map to use as index

uniqueIndex:boolean

if the index shall enforce uniqueness of index keys

Method Detail

addback to summary
public boolean add(final C object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements java.util.Collection.add.

Doc from java.util.Collection.add.

Ensures that this collection contains the specified element (optional operation). Returns true if this collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.)

Collections that support this operation may place limitations on what elements may be added to this collection. In particular, some collections will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added.

If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns.

Parameters
object:C

element whose presence in this collection is to be ensured

Returns:boolean

true if this collection changed as a result of the call

Annotations
@Override
Exceptions
IllegalArgumentException:
if the object maps to an existing key and the index enforces a uniqueness constraint
addAllback to summary
public boolean addAll(final Collection<? extends C> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Collection.addAll.

Doc from java.util.Collection.addAll.

Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.) If the specified collection has a defined encounter order, processing of its elements generally occurs in that order.

Parameters
coll:Collection<? extends C>

collection containing elements to be added to this collection

Returns:boolean

true if this collection changed as a result of the call

Annotations
@Override
addToIndexback to summary
private void addToIndex(final C object)

Provides checking for adding the index.

Parameters
object:C

the object to index

Exceptions
IllegalArgumentException:
if the object maps to an existing key and the index enforces a uniqueness constraint
clearback to summary
public void clear()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.clear.

Implements java.util.Collection.clear.

Doc from java.util.Collection.clear.

Removes all of the elements from this collection (optional operation). The collection will be empty after this method returns.

Annotations
@Override
containsback to summary
public boolean contains(final Object object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.contains.

Implements java.util.Collection.contains.

Doc from java.util.Collection.contains.

Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that Objects.equals(o, e).

Note

uses the index for fast lookup

Parameters
object:Object

element whose presence in this collection is to be tested

Returns:boolean

true if this collection contains the specified element

Annotations
@SuppressWarnings:unchecked
@Override
containsAllback to summary
public boolean containsAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.containsAll.

Implements java.util.Collection.containsAll.

Doc from java.util.Collection.containsAll.

Returns true if this collection contains all of the elements in the specified collection.

Note

uses the index for fast lookup

Parameters
coll:Collection<?>

collection to be checked for containment in this collection

Returns:boolean

true if this collection contains all of the elements in the specified collection

Annotations
@Override
getback to summary
public C get(final K key)

Get the element associated with the given key.

In case of a non-unique index, this method will return the first value associated with the given key. To retrieve all elements associated with a key, use values(Object).

Parameters
key:K

key to look up

Returns:C

element found

See Also
values(Object)
nonUniqueIndexedCollectionback to summary
public static <K, C> IndexedCollection<K, C> nonUniqueIndexedCollection(final Collection<C> coll, final Transformer<C, K> keyTransformer)

Create an IndexedCollection for a non-unique index.

Parameters
<K>
the index object type.
<C>
the collection type.
coll:Collection<C>

the decorated Collection.

keyTransformer:Transformer<C, K>

the Transformer for generating index keys.

Returns:IndexedCollection<K, C>

the created IndexedCollection.

reindexback to summary
public void reindex()

Clears the index and re-indexes the entire decorated Collection.

removeback to summary
public boolean remove(final Object object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements java.util.Collection.remove.

Doc from java.util.Collection.remove.

Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element e such that Objects.equals(o, e), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

Parameters
object:Object

element to be removed from this collection, if present

Returns:boolean

true if an element was removed as a result of this call

Annotations
@SuppressWarnings:unchecked
@Override
removeAllback to summary
public boolean removeAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements java.util.Collection.removeAll.

Doc from java.util.Collection.removeAll.

Removes all of this collection's elements that are also contained in the specified collection (optional operation). After this call returns, this collection will contain no elements in common with the specified collection.

Parameters
coll:Collection<?>

collection containing elements to be removed from this collection

Returns:boolean

true if this collection changed as a result of the call

Annotations
@Override
removeFromIndexback to summary
private void removeFromIndex(final C object)

Removes an object from the index.

Parameters
object:C

the object to remove

removeIfback to summary
public boolean removeIf(final Predicate<? super C> filter)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeIf.

Overrides default java.util.Collection.removeIf.

Doc from java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate. Errors or runtime exceptions thrown during iteration or by the predicate are relayed to the caller.

Parameters
filter:Predicate<? super C>

a predicate which returns true for elements to be removed

Returns:boolean

true if any elements were removed

Annotations
@Override
Since
4.4
retainAllback to summary
public boolean retainAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements java.util.Collection.retainAll.

Doc from java.util.Collection.retainAll.

Retains only the elements in this collection that are contained in the specified collection (optional operation). In other words, removes from this collection all of its elements that are not contained in the specified collection.

Parameters
coll:Collection<?>

collection containing elements to be retained in this collection

Returns:boolean

true if this collection changed as a result of the call

Annotations
@Override
uniqueIndexedCollectionback to summary
public static <K, C> IndexedCollection<K, C> uniqueIndexedCollection(final Collection<C> coll, final Transformer<C, K> keyTransformer)

Create an IndexedCollection for a unique index.

If an element is added, which maps to an existing key, an IllegalArgumentException will be thrown.

Parameters
<K>
the index object type.
<C>
the collection type.
coll:Collection<C>

the decorated Collection.

keyTransformer:Transformer<C, K>

the Transformer for generating index keys.

Returns:IndexedCollection<K, C>

the created IndexedCollection.

valuesback to summary
public Collection<C> values(final K key)

Get all elements associated with the given key.

Parameters
key:K

key to look up

Returns:Collection<C>

a collection of elements found, or null if contains(key) == false

Annotations
@SuppressWarnings:unchecked