//(c):Benja Fallenstein
package gzz.storm;
import java.util.*;
/** A Collection
representing the results
* of a lookup that may be continuing on another thread.
*
*/
public interface Collector extends Collection {
/** Get the number of milliseconds since this request was started.
* This may be useful in deciding whether to re-lookup the data.
*/
int getAge();
boolean isReady();
/**
* Returns false if the lookup was terminated by a timeout
* or error, rather than completed regularly.
* @throws IllegalStateException if isReady() == false
.
*/
boolean isComplete() throws IllegalStateException;
/** Block this thread until this Collection
* has been fully loaded.
* This method does nothing but waiting for the collection
* to become complete, i.e. until isReady()
is true.
* It returns this object as a convenience, so that
* you can, for example, write:
*
* for(Iterator i=pool.getIds().block().iterator(); i.hasNext();) { * BlockId id = (BlockId)i.next(); * // do something * } ** In other words, given a method that returns a
Collector
,
* you can write method().block()
to get the synchronous
* behavior of first completing a lookup and the returning
* the complete results.
* * Obviously, if the lookup has been completed already, * this returns immediately. * @return This object. */ Collector block(); /** Send the elements in this collection to a callback interface * as they arrive. * All elements already in the collection are also sent * to the listener-- this is really more like a reverse iterator, * where the iterating code doesn't call the iterator, * but is called through a callback interface (XXX explain better, * possibly rename). */ void addCollectionListener(CollectionListener listener); }