Creates an iterator that can be used to exhaustively read through all of the visible matching
entities in the space and any additional entities that match.
The templates
parameter must be a
Collection of entity instances (
Entry or plain java objects)
to be used as templates, but can't coexist with an
ExternalEntry as a template. All of
the entities iterated will match one or more of these templates. templates
may
contain null
values and may contain duplicates. An entity is said to be visible to
an invocation of this iterator if the entity could have been returned by a singleton read using a
null
transaction.
The resulting iterator must initially contain all of the
visible matching entities in the space (note the iteratorScope
parameter). During
the lifetime of the iterator an entity may be added to the iterator if it becomes visible. If the
iterator's leaseDuration
expires, no more entries can be added.
Iteration is
done by polling results into a buffer. The buffer size can be configured using
GSIteratorConfig
. The buffer serves as a static snapshot of the entities in space
and remains unchanged during the life of its iteration. Modifications only affect unbuffered
entities. Once the buffer has been iterated over, a new buffer is polled from the space.
Generally speaking, it is impossible to make any hard guarantees in the presence of concurrent
modifications.
The iterator's lease duration can be configured using
GSIteratorConfig
. If the iteration is leased the lease duration must be positive. If
leaseDuration
is
Lease#ANY, the initial duration of the lease can be any
positive value desired by the implementation - in this case
Lease#FOREVER.
If there
are remote method constraints associated with an invocation of this iterator, any remote
communications performed by or on behalf of the iterator's next
methods will be
performed in compliance with these constraints, not with the constraints (if any) associated with
next. The
#next(long) blocks until a next entity is available or
timeout expires.
Sample usage: Here is an example of using an iterator for
iterating over matching entities:
GSIteratorConfig config = new GSIteratorConfig();
config.setBufferSize(100);
config.setIteratorScope(IteratorScope.CURRENT_AND_FUTURE);
Collection<Entry> templates = new LinkedList<Entry>();
templates.add(new MyEntry());
GSIterator iterator = new GSIterator(space, templates, config);
long LATENCY = 30000; //30 seconds
//may return false due to communication constraints
while (iterator.hasNext())
{
Entry next = (Entry) iterator.next();
Thread.sleep(LATENCY);
}
Here is an example of using a blocking iterator for iterating over matching entities:
Collection<Entry> templates = new LinkedList<Entry>();
templates.add(new MyEntry());
GSIterator iterator = new GSIterator(space, templates, config);
long NEXT_TIMEOUT = 30000; //30 seconds
try
{
while (true)
{
Entry next = (Entry) iterator.next(NEXT_TIMEOUT);
}
}
catch (NoSuchElementException nsee)
{
System.out.println("iteration presumably complete.");
}
Note that this implementation is not synchronized. If multiple threads access this
iterator concurrently, it must be synchronized externally.
The GSIterator also implements Iterable
allowing to use the iterator within a
foreach
element. Note, when using the iterator within a foreach element, at the end
of the foreach, the iterator will be canceled.