SpaceIterator instead.@Deprecated public class GSIterator extends Object implements Iterator, Iterable
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 with timeout 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.
| Constructor and Description |
|---|
GSIterator(IJSpace spaceProxy,
Collection<?> templates)
Deprecated.
Equivalent to calling
GSIterator(IJSpace, Collection, com.gigaspaces.client.iterator.GSIteratorConfig). |
GSIterator(IJSpace spaceProxy,
Collection<?> templates,
GSIteratorConfig config)
Deprecated.
Constructs an iterator over a space using a collection of entity instances to be
incrementally returned.
|
GSIterator(IJSpace spaceProxy,
Collection<?> templates,
int bufferSize,
boolean withHistory,
long leaseDuration)
Deprecated.
Use
GSIterator(IJSpace, Collection, GSIteratorConfig) instead. |
| Modifier and Type | Method and Description |
|---|---|
void |
cancel()
Deprecated.
Used by the iterator holder to indicate that there is no further interest in this iterator.
|
long |
getExpiration()
Deprecated.
Returns the absolute time that the lease will expire, represented as milliseconds from the
beginning of the epoch, relative to the local clock.
|
boolean |
hasNext()
Deprecated.
Returns
true if the iterator has more elements to iterate over. |
Iterator<?> |
iterator()
Deprecated.
|
Object |
next()
Deprecated.
Removes one entity from the iterated buffered set and returns a copy to the caller.
|
Object |
next(long timeout)
Deprecated.
Same as
next() but with blocking behavior, blocking until a matched entity is
available or until timeout expires. |
Object[] |
nextBatch(int limit)
Deprecated.
Removes number of entities from the iterated buffered set and returns a copy to the caller.
|
void |
remove()
Deprecated.
Not supported operation.
|
void |
renew(long duration)
Deprecated.
Used to renew the iterator's lease for an additional period of time, specified in
milliseconds.
|
EntrySnapshot |
snapshot()
Deprecated.
Returns a snapshot, as defined in section JS.2.6 of the JavaSpaces specification, of the
entry returned by the last next call.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitforEachRemainingforEach, spliteratorpublic GSIterator(IJSpace spaceProxy, Collection<?> templates) throws RemoteException, UnusableEntryException
GSIterator(IJSpace, Collection, com.gigaspaces.client.iterator.GSIteratorConfig).
i.e. new GSIterator(spaceProxy, templates, new GSIteratorConfig());
spaceProxy - a Space instance to iterate over.templates - a Collection of entity instances, each representing a template. All the
entities added to the resulting match set will match one or more elements
of templates.RemoteException - if a communication error occurs.UnusableEntryException - if history contained an unusable entity.IllegalArgumentException - if any non-null element of templates is a mix
of ExternalEntry and Entry/POJO instance, if
templates is empty or null, if
bufferSize is non-positive, or if
leaseDuration is neither positive nor Lease.ANY.GSIterator(IJSpace, Collection, GSIteratorConfig)@Deprecated public GSIterator(IJSpace spaceProxy, Collection<?> templates, int bufferSize, boolean withHistory, long leaseDuration) throws RemoteException, UnusableEntryException
GSIterator(IJSpace, Collection, GSIteratorConfig) instead.GSIterator(IJSpace, Collection, GSIteratorConfig), translating
withHistory to CURRENT_AND_FUTURE or FUTURE.spaceProxy - a Space instance to iterate over.templates - a Collection of entity instances, each representing a template. All the
entities added to the resulting match set will match one or more
elements of templates.bufferSize - the maximum number of entities to pool each time from the space.withHistory - set true to initially contain all of the visible matching
entities in the space. Otherwise, will contain only visible matching
entities thereafter.leaseDuration - the requested initial lease time on the resulting match set.RemoteException - if a communication error occurs.UnusableEntryException - if history contained an unusable entity.IllegalArgumentException - if any non-null element of templates is a mix
of ExternalEntry and Entry/POJO instance, if
templates is empty or null, if
bufferSize is non-positive, or if
leaseDuration is neither positive nor Lease.ANY.public GSIterator(IJSpace spaceProxy, Collection<?> templates, GSIteratorConfig config) throws RemoteException, UnusableEntryException
GSIterator instance is used to access a set of
matches returned by next. The iterator will initially contain some
population of entities. These entities can be retrieved by calling next. A
successful call to next will remove the returned entity from the iteration. An
iterator can end up in one of two terminal states, invalidated or
exhausted.
A leased iterator which expires is considered as
invalidated. A canceled iterator is an exhausted iterator and will have no more
entities added to it. Calling next on an iterator with either state always
returns null or it may throw one of the allowed exceptions. In particular
next(timeout) may throw NoSuchObjectException to indicate that
no entity has been found during the allowed timeout. There is no guarantee that once
next(timeout) throws a NoSuchObjectException, or next
returns null, all future calls on that instance will do the same.
Between
the time an iterator is created and the time it reaches a terminal state, entities may be
added by the space. However, an entity that is removed by a next call may be
added back to the iterator if its uniqueness is equivalent. The space may also update or
remove entities that haven't yet been returned by a next call, and are not part
of the buffered set.
If there is a possibility that an iterator may become invalidated,
it must be leased. If there is no possibility that the iterator will become invalidated,
implementations should not lease it (i.e. use Lease.FOREVER). If there is no further
interest an iterator may be canceled.
An active lease on an iterator serves as a hint to the space that the client is still interested in matching entities, and as a hint to the client that the iterator is still functioning. There are cases, however, where this may not be possible in particular, it is not expected that iteration will maintain across crashes. If the lease expires or is canceled, the iterator is invalidated. Clients should not assume that the resources associated with a leased match set will be freed if the match set reaches the exhausted state, and should instead cancel the lease.
spaceProxy - a Space instance to iterate over.templates - a Collection of entity instances, each representing a template. All the
entities added to the resulting match set will match one or more elements
of templates.config - a set of configurations to determine the iterator's behaviour.RemoteException - if a communication error occurs.UnusableEntryException - if history contained an unusable entity.IllegalArgumentException - if any non-null element of templates is a mix
of ExternalEntry and Entry/POJO instance, if
templates is empty or null, if
bufferSize is non-positive, or if
leaseDuration is neither positive nor Lease.ANY.public EntrySnapshot snapshot() throws IllegalStateException
IllegalStateException - when last next call failedpublic boolean hasNext()
true if the iterator has more elements to iterate over. If the iterator
was constructed to initially contain matching entities, then hasNext() will
return true until the entire initial set has been iterated over. Still,
hasNext() may return false iterating over any additional matching
entities due to communication constraints - thus, it does not guarantee that the iterator is
in one of its terminal states. It is advised to use Thread.sleep(long) between
subsequent calls, to allow the iterator to receive possible additional matches.public Object[] nextBatch(int limit) throws NoSuchElementException
A given invocation of this method may perform remote communications, retrieving the next
buffer set, but generally the nextBatch method is not expected to have remote
method constraints that can vary from invocation to invocation.
limit - a limit on the number of entities to be returned. Use Integer.MAX_VALUE
for the uppermost limit.null if the iterated set is
empty or presumably complete.NoSuchElementExceptionpublic Object next()
null if a call to hasNext would have returned false.
A given invocation of this method may perform remote communications, retrieving the next
buffer set, but generally the next method is not expected to have remote method
constraints that can vary from invocation to invocation.
public Object next(long timeout) throws NoSuchElementException
next() but with blocking behavior, blocking until a matched entity is
available or until timeout expires.timeout - time to wait until a next element is available.NoSuchElementException - when timeout expires and no available match was found.public long getExpiration()
public void renew(long duration)
throws IllegalArgumentException,
LeaseDeniedException
An expired iterator is an
invalidated iterator and will have no more entities added to it. Subsequent calls to
next on this iterator will always return null.
duration - the requested duration in millisecondsIllegalArgumentException - if invalid lease expiration timeLeaseDeniedException - if the iterator's lease has already expiredpublic void cancel()
A cancelled iterator is an
exhausted iterator and will have no more entities added to it. Subsequent calls to
next on this iterator will always return null.
public void remove()
Iterator implementation.Copyright © GigaSpaces.