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 iterate on entries currently in the space, future entries or both. By default it will only iterate on future entries in the Space (entries that match the given template(s)). Use iteratorScope(IteratorScope) to set the iterator's scope.

Lease for the iterator can be controlled using leaseDuration(long). 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.

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.

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(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.
IteratorBuilder	eventSessionConfig(EventSessionConfig eventSessionConfig) The event session configuration to be used when subscribing for notifications.
GSIterator	iterate() Returns a new GSIterator based on the builder configuration.
IteratorBuilder	iteratorScope(IteratorScope iteratorScope) Determines iterator's scope: current entries, future entries or both.
IteratorBuilder	leaseDuration(long leaseDuration) The requested initial lease time on the resulting match set.
IteratorBuilder	withHistory() Deprecated.

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

@Deprecated
public IteratorBuilder withHistory()

Deprecated.

Sets to initially contain all of the visible matching entities in the space. If not called, will contain only visible matching entities thereafter. DEPRECATED: use iteratorScope(IteratorScope) instead.

iteratorScope

public IteratorBuilder iteratorScope(IteratorScope iteratorScope)

Determines iterator's scope: current entries, future entries or both.

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.

eventSessionConfig

public IteratorBuilder eventSessionConfig(EventSessionConfig eventSessionConfig)

The event session configuration to be used when subscribing for notifications.

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(Query query)

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

iterate

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