E
- element class@ParametersAreNonnullByDefault public interface SmartCollection<E> extends Collection<E>
This interface overcomes various shortcomings of the Collection
interface from the Java Collections
Framework, and also introduces other features not present in other libraries (such as the Apache Commons Collections
Library).
Efficiently operating on collections data structures is often hampered by the insufficient interface provided by the standard Java collections.
For example, linked lists allow constant time removal if the element to be removed is known. However, using List.remove(int)
requires linear time in the provided parameter (and thus, in the worst case, linear time in the
size of the list). Removal in constant time is possible when iterating manually using the Iterator.remove()
method, but this is not only inconvenient, but also does not work if one wants to remove the elements later, because
Iterator
s can't be cloned, and additionally are invalidated by other modifications of the underlying
collection during their existence.
This collection interface introduces a reference concept: References (represented by the marker interface
ElementReference
) to the elements allow efficient (in terms of what the data structure itself supports)
operations on the elements, if the reference to the respective element is known. References can be acquired right at
the point when an element is added to the collection (using referencedAdd(Object)
), by explicitly searching
for an element (using find(Object)
) or during iteration (using the referenceIterator()
resp. references()
method).
The validity of references is retained through all operations on the collection, except for those that cause removal of the respective elements.
Modifier and Type | Method and Description |
---|---|
void |
addAll(Iterable<? extends E> iterable)
Adds all elements from a given iterable.
|
<T extends E> |
addAll(T[] array)
Adds all elements from the specified array.
|
E |
choose()
Retrieves an arbitrary element from the collection.
|
ElementReference |
chooseRef()
Retrieves the reference to an arbitrary element from the collection.
|
void |
deepClear()
Thoroughly clears the collection, fixing all issues that may have been caused by a call of the above
quickClear() . |
ElementReference |
find(Object element)
Retrieves the reference for a given element.
|
E |
get(ElementReference ref)
Retrieves an element by its reference.
|
void |
quickClear()
Quickly clears this collection.
|
ElementReference |
referencedAdd(E elem)
Adds an element to the collection, returning a reference to the newly added element.
|
Iterator<ElementReference> |
referenceIterator()
Retrieves an iterator for iterating over the references of elements in this collection.
|
Iterable<ElementReference> |
references()
This is a method provided for convenience, which allows iterating over the element references using a
foreach-style
for -loop. |
void |
remove(ElementReference elem)
Removes an element (by its reference) from the collection.
|
boolean |
remove(Object element)
Deprecated.
|
void |
replace(ElementReference ref,
E newElement)
Replaces the element referenced by the given reference with the specified element.
|
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray
@Nullable E get(ElementReference ref)
If the reference belongs to another collection, the behavior is undefined.
ref
- the element's reference.@Nonnull ElementReference referencedAdd(@Nullable E elem)
elem
- the element to be added.void remove(ElementReference elem)
If the reference does not belong to this collection, the behavior is undefined.
elem
- the reference to the element to be removed.@Deprecated boolean remove(@Nullable Object element)
remove(ElementReference)
.remove
in interface Collection<E>
Collection.remove(Object)
@Nullable E choose() throws NoSuchElementException
NoSuchElementException
is thrownNoSuchElementException
@Nonnull ElementReference chooseRef()
NoSuchElementException
is thrown.@Nonnull Iterator<ElementReference> referenceIterator()
@Nonnull Iterable<ElementReference> references()
for
-loop.Iterable
with the above referenceIterator()
as its iterator.void addAll(Iterable<? extends E> iterable)
Collection
, because the number of elements to be added is not known a priori.iterable
- the iterable of elements to add.<T extends E> void addAll(T[] array)
T
- array element class, may be a subclass of E
.array
- the array of elements to be added.void replace(ElementReference ref, @Nullable E newElement)
ref
- the reference of the element to be replaced.newElement
- the replacement.ElementReference find(@Nullable Object element)
null
is returned.element
- the element to search for.null
.void quickClear()
Depending on the implementation, this may be just the same as Collection.clear()
. However, this could
also have side-effects like hampering the garbage collection or such.
After calling this method, even a call of the normal Collection.clear()
is not guaranteed to fix all
these issues. This can only be achieved by the method deepClear()
below.
void deepClear()
quickClear()
.Copyright © 2018. All rights reserved.