net.markenwerk.commons.collections.stacks

Class AbstractStack<Payload>

java.lang.Object

net.markenwerk.commons.collections.sources.AbstractSource<Payload>

net.markenwerk.commons.collections.stacks.AbstractStack<Payload>

Type Parameters:

Payload - The payload type.

All Implemented Interfaces:

Iterable<Payload>, Source<Payload>, Stack<Payload>, ProtectedIterable<Payload>

Direct Known Subclasses:

AbstractLinkedStack

public abstract class AbstractStack<Payload>
extends AbstractSource<Payload>
implements Stack<Payload>

An AbstractStack is an abstract base implementation of Stack.

An AbstractStack has two sets of protected methods.

• A first set of abstract methods, prefixed with do, must be implemented by concrete implementations to perform the necessary structural modifications to the underlying data structure.
• A second set of methods, prefixed with on, may be implemented by concrete implementations to perform additional actions after a structural modification has occurred.

Since:

1.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Constructor Summary

Constructors

Constructor and Description
AbstractStack(Nullity nullity) Creates a new AbstractStack.

Method Summary

Modifier and Type	Method and Description
Source<Payload>	clear() Removes all payload values.
protected abstract Source<Payload>	doClear() Removes all payload value.
protected abstract Payload	doGetFirst() Returns the first (i.e.
protected abstract ProtectedIterator<Payload>	doIterator() Returns a fail-fast ProtectedIterator that starts with the payload value at the given first index, where 0 is the index of most recently pushed value.
protected abstract Payload	doPop() Removes the first (i.e.
protected abstract void	doPush(Payload payload) Pushes the given payload value as the new first value.
protected abstract Payload	doReplace(Payload replacement) Replaces the payload value at the given index with the given replacement payload value.
protected abstract int	doSize() Returns the number of payload values of this Stack.
boolean	equals(Object object) Compares the given object with this Stack for equality.
Optional<Integer>	firstIndexOf(Payload reference) Returns the index of the first occurrence, by equality, of the given reference payload value, where 0 is the index of most recently pushed value.
Optional<Integer>	firstIndexOfMatch(Predicate<? super Payload> predicate) Returns the index of the first occurrence of a reference payload value that satisfies the given Predicate, where 0 is the index of most recently pushed value.
Payload	get(int index) Returns the payload value at the given index, where 0 is the index of most recently pushed value.
Nullity	getNullity() Returns the Nullity this AbstractStack has been created with.
int	hashCode() Returns the hash code of this Stack.
ProtectedIterator<Payload>	iterator() Returns a fail-fast ProtectedIterator that starts with the first (i.e.
protected void	onCleared(Source<Payload> iterable) Called after all payload values have been removed.
protected void	onPopped(Payload payload) Called after the first (i.e.
protected void	onPushed(Payload payload) Called after the given payload value has been pushed as the new first value.
Payload	pop() Removes the first (i.e.
Source<Payload>	popAll(int number) Removes the given number of payload values.
Source<Payload>	popAllMatches(Predicate<? super Payload> predicate) Removes the first (i.e.
Stack<Payload>	push(Payload payload) Pushes the given payload value as the new first value.
Stack<Payload>	pushAll(Iterable<? extends Payload> payloads) Pushes the given payload values in the given order.
Stack<Payload>	pushAll(Payload... payloads) Pushes the given payload values in the given order.
Payload	replace(Payload replacement) Replaces the first (i.e.
int	size() Returns the number of payload values of this Source.

Methods inherited from class net.markenwerk.commons.collections.sources.AbstractSource

contains, containsAll, containsAll, containsMatch, createPredicate, firstIndexOf, getAll, getAllMatches, getFirst, getFirst, getFirstMatch, isEmpty, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.markenwerk.commons.collections.stacks.Stack

getFirst, getFirst, getFirstMatch

Methods inherited from interface net.markenwerk.commons.collections.sources.Source

contains, containsAll, containsAll, containsMatch, getAll, getAllMatches, isEmpty

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

AbstractStack

public AbstractStack(Nullity nullity)
              throws IllegalArgumentException

Creates a new AbstractStack.

Parameters:

nullity - The Nullity to be used.

Throws:

IllegalArgumentException - If the given Nullity is null;

Method Detail

getNullity

public final Nullity getNullity()

Returns the Nullity this AbstractStack has been created with.

Returns:

The Nullity.

size

public final int size()

Description copied from interface: Source

Returns the number of payload values of this Source.

Specified by:

size in interface Source<Payload>

Returns:

The number of payload values of this Source.

doSize

protected abstract int doSize()

Returns the number of payload values of this Stack.

Returns:

The number of payload values of this Stack.

push

public final Stack<Payload> push(Payload payload)
                          throws IllegalArgumentException

Description copied from interface: Stack

Pushes the given payload value as the new first value.

Specified by:

push in interface Stack<Payload>

Parameters:

payload - The payload value to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

pushAll

public final Stack<Payload> pushAll(Payload... payloads)
                             throws IllegalArgumentException,
                                    IllegalStateException

Description copied from interface: Stack

Pushes the given payload values in the given order.

This is a short hand for a multiple pushes.

Specified by:

pushAll in interface Stack<Payload>

Parameters:

payloads - The array of payload values to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given array of payload values is null or if one of the given payload values is null and this Sequence doesn't allow a null to be added.

IllegalStateException

pushAll

public final Stack<Payload> pushAll(Iterable<? extends Payload> payloads)
                             throws IllegalArgumentException,
                                    IllegalStateException

Description copied from interface: Stack

Pushes the given payload values in the given order.

This is a short hand for a multiple pushes.

Specified by:

pushAll in interface Stack<Payload>

Parameters:

payloads - The Iterable of payload values to be pushed.

Returns:

This Stack.

Throws:

IllegalArgumentException - If the given Iterable of payload values is null or if one of the given payload values is null and this Sequence doesn't allow a null to be added.

IllegalStateException

doPush

protected abstract void doPush(Payload payload)

Pushes the given payload value as the new first value.

Parameters:

payload - The payload value to be pushed, which is guaranteed to be not null, unless the Nullity of this Stack is Nullity.ALLOW.

onPushed

protected void onPushed(Payload payload)

Called after the given payload value has been pushed as the new first value.

Parameters:

payload - The pushed payload value, which is guaranteed to be not null, unless the Nullity of this Stack is Nullity.ALLOW.

pop

public final Payload pop()
                  throws NoSuchElementException

Description copied from interface: Stack

Removes the first (i.e. most recently pushed) payload value.

Specified by:

pop in interface Stack<Payload>

Returns:

The removed payload value.

Throws:

NoSuchElementException - If this Stack is empty.

popAll

public final Source<Payload> popAll(int number)
                             throws IllegalArgumentException

Description copied from interface: Stack

Removes the given number of payload values.

Specified by:

popAll in interface Stack<Payload>

Parameters:

number - The number of payload values to be popped.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given index is negative or if the given index is larger than the size of this Stack .

popAllMatches

public final Source<Payload> popAllMatches(Predicate<? super Payload> predicate)
                                    throws IllegalArgumentException

Description copied from interface: Stack

Removes the first (i.e. most recently pushed) payload values as long as this Stack is not empty and the first payload value satisfies the given predicate.

Specified by:

popAllMatches in interface Stack<Payload>

Parameters:

predicate - The Predicate to be used.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given Predicate is null.

doPop

protected abstract Payload doPop()

Removes the first (i.e. most recently pushed) payload value.

Only called if this AbstractStack is not empty.

Returns:

The removed payload value.

onPopped

protected void onPopped(Payload payload)

Called after the first (i.e. most recently pushed) payload value has been removed.

Parameters:

payload - The popped payload value, which is guaranteed to be not null, unless the Nullity of this Stack is Nullity.ALLOW.

replace

public final Payload replace(Payload replacement)
                      throws IllegalArgumentException,
                             NoSuchElementException

Description copied from interface: Stack

Replaces the first (i.e. most recently pushed) payload value with the given payload value.

This is a short hand for a pop and a push.

Specified by:

replace in interface Stack<Payload>

Parameters:

replacement - The payload value to be used.

Returns:

The replaced payload value.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

NoSuchElementException - If this Stack is empty.

doReplace

protected abstract Payload doReplace(Payload replacement)

Replaces the payload value at the given index with the given replacement payload value.

Parameters:

replacement - The replacement payload value to be used.

Returns:

The replaced payload value.

get

public final Payload get(int index)
                  throws IndexOutOfBoundsException

Description copied from interface: Stack

Returns the payload value at the given index, where 0 is the index of most recently pushed value.

Specified by:

get in interface Stack<Payload>

Parameters:

index - The index to be used.

Returns:

The payload value at the given index.

Throws:

IndexOutOfBoundsException - If the given index is negative or if the given index is equal to or larger than the size of this Stack.

doGetFirst

protected abstract Payload doGetFirst()

Returns the first (i.e. most recently pushed) payload value.

Only called if this AbstractStack is not empty.

Overrides:

doGetFirst in class AbstractSource<Payload>

Returns:

The first payload value.

clear

public final Source<Payload> clear()

Description copied from interface: Stack

Removes all payload values.

This may be a bulk operation and not a short hand for a multiple pops.

Specified by:

clear in interface Stack<Payload>

Returns:

A Source yielding the removed payload values.

doClear

protected abstract Source<Payload> doClear()

Removes all payload value.

Returns:

An Iterable that yields all removed payload values, even after further structural modifications have been made to this AbstractStack.

onCleared

protected void onCleared(Source<Payload> iterable)

Called after all payload values have been removed.

Parameters:

iterable - An Iterable that yields all removed payload values.

firstIndexOf

public final Optional<Integer> firstIndexOf(Payload reference)
                                     throws NoSuchElementException

Description copied from interface: Stack

Returns the index of the first occurrence, by equality, of the given reference payload value, where 0 is the index of most recently pushed value.

Specified by:

firstIndexOf in interface Stack<Payload>

Parameters:

reference - The reference payload value to be used.

Returns:

An Optional yielding the index.

Throws:

NoSuchElementException

firstIndexOfMatch

public final Optional<Integer> firstIndexOfMatch(Predicate<? super Payload> predicate)
                                          throws IllegalArgumentException,
                                                 NoSuchElementException

Description copied from interface: Stack

Returns the index of the first occurrence of a reference payload value that satisfies the given Predicate, where 0 is the index of most recently pushed value.

Specified by:

firstIndexOfMatch in interface Stack<Payload>

Parameters:

predicate - The Predicate value to be used.

Returns:

An Optional yielding the index.

Throws:

IllegalArgumentException - If the given Predicate is null.

NoSuchElementException

iterator

public final ProtectedIterator<Payload> iterator()

Description copied from interface: Stack

Returns a fail-fast ProtectedIterator that starts with the first (i.e. most recently pushed) payload value.

Specified by:

iterator in interface Iterable<Payload>

Specified by:

iterator in interface Stack<Payload>

Specified by:

iterator in interface ProtectedIterable<Payload>

Returns:

A fail-fast ProtectedIterator.

doIterator

protected abstract ProtectedIterator<Payload> doIterator()

Returns a fail-fast ProtectedIterator that starts with the payload value at the given first index, where 0 is the index of most recently pushed value.

Returns:

A fail-fast ProtectedIterator.

equals

public final boolean equals(Object object)

Description copied from interface: Stack

Compares the given object with this Stack for equality.

Returns true if and only if the given object is also a Stack, both Stacks have the same size, and all corresponding pairs of elements in the two Stacks are equal.

Specified by:

equals in interface Stack<Payload>

Overrides:

equals in class Object

Parameters:

object - The object to be used.

Returns:

If the given object is equal to this Stack.

hashCode

public final int hashCode()

Description copied from interface: Stack

Returns the hash code of this Stack.

The hash code of a Stack is defined to be the result of the following calculation:

 int hashCode = 1;
 Iterator<Payload> iterator = stack.iterator();
 while (iterator.hasNext()) {
        Payload payload = iterator.next();
        hashCode = 31 * hashCode + (null == payload ? 0 : payload.hashCode());
 }
 

Specified by:

hashCode in interface Stack<Payload>

Overrides:

hashCode in class Object

Returns:

The hash code of this Stack.