jut.util.concurrent
Class BlockingOpenIterable<T>

java.lang.Object
  jut.lang.AbstractOneTimeIterable<T>
      jut.util.concurrent.BlockingOpenIterable<T>

All Implemented Interfaces:

Iterable<T>, OneTimeIterable<T>

public class BlockingOpenIterable<T>
extends AbstractOneTimeIterable<T>

consumer/producer utility class for asynchronous use. the producer(s) add items that are cached in a bounded cache - if the cache is full, the addItem(Object) method waits for the consumer(s) to remove items. the consumer(s) remove items using the sole Iterator of this object, usually in a for (Itemtype item : blockingOpenIterable) loop.

as alternative to asynchronous use, the item cache can be filled in advance, close() can be called and the items be consumed in a for loop - all in one thread.

note that the consumer(s) will keep waiting for items even if the cache is empty until the close() method is called.

this class adds a utility for consumer/producer scenarios to the utilities of the standard JDK.

Author:

Georg Dietrich

Constructor Summary

BlockingOpenIterable()
create a consumer/producer Iterable with an unbounded internal cache.

BlockingOpenIterable(int capacity)
create a consumer/producer Iterable with a defined internal cache capacity.

Method Summary

BlockingOpenIterable<T>	addItem(T item) add a new item to this BlockingOpenIterable, waiting if the cache is full.
BlockingOpenIterable<T>	addItems(Iterable<T> items) add new items to this BlockingOpenIterable, waiting if the cache is full.
BlockingOpenIterable<T>	close() close this BlockingOpenIterable so no more items may be added by addItem(Object).
protected boolean	iteratorHasNext() returns true if the iterator has more elements.
protected T	iteratorNext() returns the next element in the iterator.

Methods inherited from class jut.lang.AbstractOneTimeIterable

iterator, onNext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BlockingOpenIterable

public BlockingOpenIterable()

create a consumer/producer Iterable with an unbounded internal cache.

BlockingOpenIterable

public BlockingOpenIterable(int capacity)

create a consumer/producer Iterable with a defined internal cache capacity.

Parameters:

capacity - - the capacity of the items cache. if set to 0 or less, the capacity is set to Integer.MAX_VALUE.

Method Detail

close

public BlockingOpenIterable<T> close()

close this BlockingOpenIterable so no more items may be added by addItem(Object).

Returns:

a reference to the object itself.

addItem

public BlockingOpenIterable<T> addItem(T item)
                                throws IllegalStateException

add a new item to this BlockingOpenIterable, waiting if the cache is full.

Parameters:

item - - the item to add.

Returns:

a reference to the object itself.

Throws:

IllegalStateException - if this BlockingOpenIterable has already been closed. waiting threads may also return with this exception.

addItems

public BlockingOpenIterable<T> addItems(Iterable<T> items)
                                 throws IllegalStateException

add new items to this BlockingOpenIterable, waiting if the cache is full.

Parameters:

items - - the items to add.

Returns:

a reference to the object itself.

Throws:

IllegalStateException - if this BlockingOpenIterable has already been closed. waiting threads may also return with this exception.

iteratorHasNext

protected boolean iteratorHasNext()

returns true if the iterator has more elements. (in other words, returns true if AbstractOneTimeIterable.iteratorNext() would return an element rather than throwing an exception.) if no items are cached in this BlockingOpenIterable, waits until either items become available or close() is called.

Specified by:

iteratorHasNext in class AbstractOneTimeIterable<T>

Returns:

true if the iterator has more elements, false if not.

iteratorNext

protected T iteratorNext()
                  throws NoSuchElementException

returns the next element in the iterator. if no items are cached in this BlockingOpenIterable, waits until either items become available or close() is called.

Specified by:

iteratorNext in class AbstractOneTimeIterable<T>

Returns:

the next element in the iterator.

Throws:

NoSuchElementException - the iteration has no more elements (close() was called).