org.openspaces.core
Class IteratorBuilder

java.lang.Object
  org.openspaces.core.IteratorBuilder

public class IteratorBuilder
extends Object

A utility builder class for GSIterator. Allows to use method chaining for simple configuration of an iterator and then call iterate() to get the actual iterator.

By default, when no template is added (using addTemplate(Object) or addTemplate(com.j_spaces.core.client.Query), a null template will be used to iterate over all the content of the Space.

The iterator can also iterate on history entries. By default it will only iterate on future entries in the Space (entries that match the given template(s)). When calling withHistory() the iterator will also iterate over existing entries.

Lease for the iterator can be controlled using leaseDuration(long). A leased iterator which expires is considered as invalidated. A cancelled 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.

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 cancelled.

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.

The maximum number of entries to pull from the space can be controlled using bufferSize(int) and defaults to 100.

Author:

kimchy

See Also:

GigaSpace.iterator()

Constructor Summary

IteratorBuilder(GigaSpace gigaSpace)
Constructs a new iterator builder using the given GigaSpace.

Method Summary

IteratorBuilder	addTemplate(Object template) Adds a template that will be used to control the matching entries the iterator will iterate over.
IteratorBuilder	addTemplate(com.j_spaces.core.client.Query query) Adds a template that will be used to control the matching entries the iterator will iterate over.
IteratorBuilder	bufferSize(int bufferSize) The maximum number of entries to pull from the space can be controlled using bufferSize(int) and defaults to 100.
com.j_spaces.core.client.GSIterator	iterate() Returns a new GSIterator based on the builder configuration.
IteratorBuilder	leaseDuration(long leaseDuration) The requested initial lease time on the resulting match set.
IteratorBuilder	withHistory() Sets to initially contain all of the visible matching entities in the space.

Methods inherited from class java.lang.Object

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

Constructor Detail

IteratorBuilder

public IteratorBuilder(GigaSpace gigaSpace)

Constructs a new iterator builder using the given GigaSpace.

Method Detail

withHistory

public IteratorBuilder withHistory()

Sets to initially contain all of the visible matching entities in the space. If not called, will contain only visible matching entities thereafter.

bufferSize

public IteratorBuilder bufferSize(int bufferSize)

The maximum number of entries to pull from the space can be controlled using bufferSize(int) and defaults to 100.

leaseDuration

public IteratorBuilder leaseDuration(long leaseDuration)

The requested initial lease time on the resulting match set. Defaults to FOREVER.

addTemplate

public IteratorBuilder addTemplate(Object template)

Adds a template that will be used to control the matching entries the iterator will iterate over.

addTemplate

public IteratorBuilder addTemplate(com.j_spaces.core.client.Query query)

Adds a template that will be used to control the matching entries the iterator will iterate over.

iterate

public com.j_spaces.core.client.GSIterator iterate()

Returns a new GSIterator based on the builder configuration. If no templates were added, a null template will be added which will cause the iterator to iterate over all the entries in the Space.