//(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); }