net.markenwerk.commons.collections.sources

Interface Source<Payload>

Type Parameters:

Payload - The payload type

All Superinterfaces:

Iterable<Payload>, ProtectedIterable<Payload>

All Known Subinterfaces:

IndexedSource<Payload>, Sequence<Payload>, Stack<Payload>

All Known Implementing Classes:

AbstractIndexedSource, AbstractLinkedStack, AbstractListSequence, AbstractSequence, AbstractSource, AbstractStack, ArraySource, CollectionSource, EmptySource, LinkedStack, ListSequence, ListSource, MapKeySource, MapValueSource, ObjectSource, OptionalSource

public interface Source<Payload>
extends ProtectedIterable<Payload>

A Source is a read-only data structure.

A Source is intended to be used in APIs that want to expose read-only access to a collection of payload values.

It is, amongst other things, intended as a more expressive replacement for Collections.unmodifiableCollection(java.util.Collection) that prevents unnecessary runtime exceptions.

Since:

1.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Method Summary

Modifier and Type	Method and Description
boolean	contains(Object reference) Returns whether this Source contains, by equality, the given reference payload value.
boolean	containsAll(Iterable<?> references) Returns whether this Source contains, by equality, all of the given reference payload values.
boolean	containsAll(Object... references) Returns whether this Source contains, by equality, all of the given reference payload values.
boolean	containsMatch(Predicate<? super Payload> predicate) Returns whether this Source contains a payload value that satisfies the given Predicate.
Source<Payload>	getAll(Payload reference) Returns all occurrences, by equality, of the given reference payload value.
Source<Payload>	getAllMatches(Predicate<? super Payload> predicate) Returns the payload values that satisfy the given Predicate.
Payload	getFirst() Returns the first (i.e.
Optional<Payload>	getFirst(Payload reference) Returns the first (i.e.
Optional<Payload>	getFirstMatch(Predicate<? super Payload> predicate) Returns the first (i.e.
boolean	isEmpty() Returns whether this Source is empty.
int	size() Returns the number of payload values of this Source.

Methods inherited from interface net.markenwerk.commons.iterables.ProtectedIterable

iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

isEmpty

boolean isEmpty()

Returns whether this Source is empty.

Returns:

Whether this Source is empty.

size

int size()

Returns the number of payload values of this Source.

Returns:

The number of payload values of this Source.

getFirst

Payload getFirst()
          throws NoSuchElementException

Returns the first (i.e. first payload value in an iterator) payload value.

Returns:

The payload value.

Throws:

NoSuchElementException - If this IndexedSource is empty.

getFirst

Optional<Payload> getFirst(Payload reference)

Returns the first (i.e. first occurrence in an iterator of this Source) occurrences, by equality, of the given reference payload value.

Parameters:

reference - The reference payload to be used.

Returns:

An Optional yielding the payload value.

getFirstMatch

Optional<Payload> getFirstMatch(Predicate<? super Payload> predicate)
                         throws IllegalArgumentException

Returns the first (i.e. first occurrence in an iterator of this Source) payload value that satisfies the given Predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the payload value.

Throws:

IllegalArgumentException - If the given Predicate is null.

getAll

Source<Payload> getAll(Payload reference)

Returns all occurrences, by equality, of the given reference payload value.

Parameters:

reference - The reference payload to be used.

Returns:

A Source yielding the payload values.

getAllMatches

Source<Payload> getAllMatches(Predicate<? super Payload> predicate)
                       throws IllegalArgumentException

Returns the payload values that satisfy the given Predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

A Source yielding the payload values.

Throws:

IllegalArgumentException - If the given Predicate is null.

contains

boolean contains(Object reference)

Returns whether this Source contains, by equality, the given reference payload value.

Parameters:

reference - The reference payload value to be checked.

Returns:

Whether this Source contains the given reference payload value.

containsMatch

boolean containsMatch(Predicate<? super Payload> predicate)
               throws IllegalArgumentException

Returns whether this Source contains a payload value that satisfies the given Predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

Whether this Source contains a payload value that satisfies the given Predicate.

Throws:

IllegalArgumentException - if the given Predicate is null.

containsAll

boolean containsAll(Object... references)
             throws IllegalArgumentException

Returns whether this Source contains, by equality, all of the given reference payload values.

Parameters:

references - The array of reference payload values to be checked.

Returns:

Whether this Source contains all of the given payload values.

Throws:

IllegalArgumentException - If the given array of reference payload values is null.

containsAll

boolean containsAll(Iterable<?> references)
             throws IllegalArgumentException

Returns whether this Source contains, by equality, all of the given reference payload values.

Parameters:

references - The Iterable of reference payload values to be checked.

Returns:

Whether this Source contains all of the given payload values.

Throws:

IllegalArgumentException - If the given Iterable of reference payload values is null.