util
Class Shelf<E>

java.lang.Object
  util.Shelf<E>

All Implemented Interfaces:

Iterable<E>, Collection<E>, List<E>

public class Shelf<E>
extends Object
implements List<E>

A Shelf is an implementation of a special queue. It has a distinct size, specified at construct. Adding values to the end of the queue behaves normally, until the size is reached. Further addition of objects to the end of the Shelf result in the loss of the very first object.

Implementation detail: A LinkedList is used by the shelf. Unwanted methods, like add(int, Object) throw an UnsupportedOperationException.

To avoid unwanted functions to be available, we do not subclass but rather compose this Shelf from a LinkedList

Field Summary

private int	accumulated The number of elements added during the liftime of the shelf.
static int	DEFSIZE The default size of a shelf.
private int	maxsize The defined maximal size of the shelf.
private E	recent The most recently removed object.
private LinkedList<E>	shelflist The backing linked list of this shelf.

Constructor Summary

Shelf()
Creates a Shelf with the default size.

Shelf(Collection<E> all)
Creates a Shelf from a collection.

Shelf(Collection<E> all, int max)
Creates a Shelf from a collection.

Shelf(int max)
Creates a Shelf with the given size.

Method Summary

int	accumulated() Returns the cummulated number of items.
boolean	add(E toadd) Adds the object to the end of the list.
void	add(int index, E toadd) Removes the first element, if the new list is too big.
boolean	addAll(Collection<? extends E> toadd) Only allowed if the size of the collection is less then the maximum size.
boolean	addAll(int index, Collection<? extends E> toadd) Not supported.
void	clear() Empties the shelf, resets the accumulated count to zero.
boolean	contains(Object that) Returns true if this list contains the specified element.
boolean	containsAll(Collection<?> that) Returns true if this list contains all specified element.
boolean	equals(Object that) Returns true, if two shelfs are equal.
E	get(int index) Returns the Object on the given index.
E	getFirst() Returns the first element in this Shelf.
E	getLast() Returns the last element in the Shelf.
int	getMaxSize() Used for equals method.
(package private) LinkedList	getShelf() Used for equals method.
int	hashCode() Returns a unique hash code.
int	indexOf(Object that) Returns the index of the specified object.
boolean	isEmpty() Returns true if the shelf is empty.
boolean	isFull() Returns true, if the shelf is full.
Iterator<E>	iterator() Returns an iterator over the shelf's objects.
int	lastIndexOf(Object that) Returns the last index of the specified object.
ListIterator<E>	listIterator() Returns a list iterator of the shelf's objects.
ListIterator<E>	listIterator(int index) Returns a list iterator of the elements in this Shelf.
Object	recentlyRemoved() Returns the object that has just fallen off the shelf.
E	remove(int index) Removes and returns the Object on the specified index.
boolean	remove(Object that) Removes the specified object, if possible.
boolean	removeAll(Collection<?> that) Remove all Objects specified.
E	removeFirst() Returns and removes the first element in this Shelf.
E	removeLast() Returns and removes the last element in the Shelf.
boolean	retainAll(Collection<?> that) Retain only the specified objects.
E	set(int index, E that) Sets the object on the specified index.
int	size() Return the actual size of the Shelf.
List<E>	subList(int from, int to) Returns a part of the Shelf as a list.
Object[]	toArray() Returns all elements in this Shelf in proper sequence.
<T> T[]	toArray(T[] type) Returns all elements in this Shelf in proper sequence using the same type of object as specified in the argument.
String	toString() Returns my internale list as a string.

Methods inherited from class java.lang.Object

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

Field Detail

DEFSIZE

public static final int DEFSIZE

The default size of a shelf.

See Also:

Constant Field Values

maxsize

private int maxsize

The defined maximal size of the shelf.

accumulated

private int accumulated

The number of elements added during the liftime of the shelf.

shelflist

private LinkedList<E> shelflist

The backing linked list of this shelf.

recent

private E recent

The most recently removed object. Updated at any call to add(int, E).

Constructor Detail

Shelf

public Shelf()

Creates a Shelf with the default size.

Shelf

public Shelf(int max)

Creates a Shelf with the given size. If the Shelf's size is less then one, an IllegalArgumentException is thrown.

Shelf

public Shelf(Collection<E> all)

Creates a Shelf from a collection. The collection's size defines the maximum number of entries.

Shelf

public Shelf(Collection<E> all,
             int max)

Creates a Shelf from a collection. The maximum number of entries is specified in the second parameter. If max is smaller than the Collection's size, the Collection's size is used as the maximum size of this Shelf.

Method Detail

add

public void add(int index,
                E toadd)

Removes the first element, if the new list is too big.

Specified by:

add in interface List<E>

add

public boolean add(E toadd)

Adds the object to the end of the list. If the Shelf has reached its maximal size, the element on top of the Shelf is removed but can be recovered with the recentlyRemoved() method.

Specified by:

add in interface Collection<E>

Specified by:

add in interface List<E>

Parameters:

toadd - The object to put on the shelf.

Returns:

True, as per the general contract of Collection.

recentlyRemoved

public Object recentlyRemoved()

Returns the object that has just fallen off the shelf. Use this method after a call to add(int, E) to get the object that was removed when the new object was inserted.

Returns:

null - If the shelf is still not at its capacitiy.

addAll

public boolean addAll(Collection<? extends E> toadd)

Only allowed if the size of the collection is less then the maximum size. Then, each object in the collection is added separately. If the collection is bigger then the maximum size, an unsupported operation exception is thrown.

Specified by:

addAll in interface Collection<E>

Specified by:

addAll in interface List<E>

addAll

public boolean addAll(int index,
                      Collection<? extends E> toadd)

Not supported.

Specified by:

addAll in interface List<E>

clear

public void clear()

Empties the shelf, resets the accumulated count to zero.

Specified by:

clear in interface Collection<E>

Specified by:

clear in interface List<E>

contains

public boolean contains(Object that)

Returns true if this list contains the specified element. Uses the LinkedList.contains() method.

Specified by:

contains in interface Collection<E>

Specified by:

contains in interface List<E>

Parameters:

that - The object to search.

containsAll

public boolean containsAll(Collection<?> that)

Returns true if this list contains all specified element. Uses the LinkedList.containsAll() method.

Specified by:

containsAll in interface Collection<E>

Specified by:

containsAll in interface List<E>

Parameters:

that - The Collection to search.

getShelf

LinkedList getShelf()

Used for equals method.

getMaxSize

public int getMaxSize()

Used for equals method. Returns the maximal size of this shelf.

isFull

public boolean isFull()

Returns true, if the shelf is full.

equals

public boolean equals(Object that)

Returns true, if two shelfs are equal. Additionally to comparing their underlying LinkedList, their maximal size must be equal.

Specified by:

equals in interface Collection<E>

Specified by:

equals in interface List<E>

Overrides:

equals in class Object

Parameters:

that - The Shelf this one should be compared to.

get

public E get(int index)

Returns the Object on the given index.

Specified by:

get in interface List<E>

Parameters:

index - The index of the object to retrieve.

getFirst

public E getFirst()

Returns the first element in this Shelf. This object changes, as objectes are added beyond the maximal capacity of this shelf.

removeFirst

public E removeFirst()

Returns and removes the first element in this Shelf. This object changes, as objectes are added beyond the maximal capacity of this shelf.

getLast

public E getLast()

Returns the last element in the Shelf.

removeLast

public E removeLast()

Returns and removes the last element in the Shelf.

hashCode

public int hashCode()

Returns a unique hash code.

Specified by:

hashCode in interface Collection<E>

Specified by:

hashCode in interface List<E>

Overrides:

hashCode in class Object

indexOf

public int indexOf(Object that)

Returns the index of the specified object. If the object is not present in this shelf -1 is returned.

Specified by:

indexOf in interface List<E>

isEmpty

public boolean isEmpty()

Returns true if the shelf is empty.

Specified by:

isEmpty in interface Collection<E>

Specified by:

isEmpty in interface List<E>

iterator

public Iterator<E> iterator()

Returns an iterator over the shelf's objects. Don't use this iterator to add elements!

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in interface List<E>

lastIndexOf

public int lastIndexOf(Object that)

Returns the last index of the specified object. If the object is not present in this shelf -1 is returned.

Specified by:

lastIndexOf in interface List<E>

listIterator

public ListIterator<E> listIterator()

Returns a list iterator of the shelf's objects. Don't use this iterator to add elements!

Specified by:

listIterator in interface List<E>

listIterator

public ListIterator<E> listIterator(int index)

Returns a list iterator of the elements in this Shelf. If index is too high, an IndexOutOfBoundsException is thrown. Don't use this iterator to add elements!

Specified by:

listIterator in interface List<E>

remove

public E remove(int index)

Removes and returns the Object on the specified index.

Specified by:

remove in interface List<E>

remove

public boolean remove(Object that)

Removes the specified object, if possible.

Specified by:

remove in interface Collection<E>

Specified by:

remove in interface List<E>

Parameters:

that - The object to remove.

removeAll

public boolean removeAll(Collection<?> that)

Remove all Objects specified.

Specified by:

removeAll in interface Collection<E>

Specified by:

removeAll in interface List<E>

Parameters:

that - The collection to remove.

retainAll

public boolean retainAll(Collection<?> that)

Retain only the specified objects.

Specified by:

retainAll in interface Collection<E>

Specified by:

retainAll in interface List<E>

Parameters:

that - The collection to keep.

set

public E set(int index,
             E that)

Sets the object on the specified index.

Specified by:

set in interface List<E>

Parameters:

index - The index, where the object should squeeze in.

that - The object to set.

Returns:

The object that has been replaced.

size

public int size()

Return the actual size of the Shelf.

Specified by:

size in interface Collection<E>

Specified by:

size in interface List<E>

accumulated

public int accumulated()

Returns the cummulated number of items. This number is equal to the size as long as the shelf is not entirely filled.

subList

public List<E> subList(int from,
                       int to)

Returns a part of the Shelf as a list.

Specified by:

subList in interface List<E>

Parameters:

from - The index to start (inclusively).

to - The index to end (exclusively).

toArray

public Object[] toArray()

Returns all elements in this Shelf in proper sequence.

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface List<E>

toArray

public <T> T[] toArray(T[] type)

Returns all elements in this Shelf in proper sequence using the same type of object as specified in the argument.

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface List<E>

Parameters:

type - The object template.

toString

public String toString()

Returns my internale list as a string.

Overrides:

toString in class Object