net.jini.space
Interface MatchSet

public interface MatchSet

A collection of Entry instances to be incrementally returned from a JavaSpaces(TM) service. Some operations on a space must return more entries than can be conveniently returned by a single call, generally because returning all the entries in one result would consume too many resources in the client or introduce too much latency before the first entry could be processed. In these cases, match sets are returned to incrementally return the necessary entries. A MatchSet instance is a proxy object that can be used to access a match set created by a space.

Typically match sets are created by some factory method on the space (for example, JavaSpace05.contents) which returns a MatchSet instance that will serve as a proxy to the match set. The match set will initially contain some population of entries specified by the operation that created it. These entries can be retrieved by calling next. A successful call to next will remove the returned Entry from the match set. Match sets can end up in one of two terminal states, exhausted or invalidated. Under what conditions a match set enters one of these states is specified by the operation that created it. An exhausted match set is empty and will have no more entries added. Calling next on an exhausted match set must always return null. Calling next on an invalidated match set may return a non-null value, or it may throw one of the allowed exceptions. In particular it may throw NoSuchObjectException to indicate that the match set has been invalidated. Once next throws a NoSuchObjectException, all future next calls on that instance must also throw NoSuchObjectException. Calling next on an invalidated match set must never return null. Implementations must not add entries to an invalidated match set.

Between the time a match set is created and the time it reaches a terminal state, entries may be added by the space. However, an Entry that is removed by a next call must not be added back to a match set (though if there is a distinct but equivalent entry in the space it may be added). The space may also remove entries independent of next calls. The conditions under which entries will be removed independent of next calls or added after the initial creation of the match set are specified by the operation that created the match set.

If there is a possibility that a match set may become invalidated, it must be leased and an appropriate proxy must be returned by the getLease method. If there is no possibility that the match set will become invalidated, implementations should not lease the match set. If a match set is not leased, then getLease must return null.

An active lease on a match set serves as a hint to the space that the client is still interested in the match set, and as a hint to the client that the match set is still functioning. However, implementations are allowed to invalidate match sets associated with active leases and to unilaterally cancel leases associated with functioning match sets. If a match set is leased and the lease is active, implementations should, to the best of their ability, maintain the match set and not invalidate it. There are cases, however, where this may not be possible in particular, it is not expected that implementations will maintain match sets across crashes. If the lease expires or is canceled, an implementation should invalidate the match set. An implementation must unilaterally cancel a match set's lease if the match set is invalidated. An implementation may unilaterally cancel the lease at other times without necessarily invalidating the match set. 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. This interface is not a remote interface; though in general a MatchSet is a proxy for some remote match set, only the next method is considered to be a remote method, and as outlined in its description it deviates in a number of ways from normal Java(TM) Remote Method Invocation remote method semantics.

Since:

2.1

Method Summary

Lease	getLease() Returns a proxy to the Lease associated with this match set, or null if this match set is not leased.
Entry	getSnapshot() Returns a snapshot of the Entry removed by the last call to next.
Entry	next() Removes one Entry from the match set and returns a copy to the caller.

Method Detail

next

Entry next()
           throws RemoteException,
                  UnusableEntryException

Removes one Entry from the match set and returns a copy to the caller. Returns null if the match set is empty. The returned Entry must be unmarshalled in accordance with the Jini(TM) Entry Specification.

A given invocation of this method may perform remote communications, but generally the next method is not expected to have remote method constraints that can vary from invocation to invocation. Instead the set of constraints associated with the next method will be fixed at the time the match set was created, even if this object implements an interface like RemoteMethodControl that would otherwise allow the set of constraints associated with the next method to be altered.

Returns:

an Entry from the match set, or null if the match set is empty

Throws:

UnusableEntryException - if the entry removed from the match set could not be unmarshalled

RemoteException - if a communication error occurs. If a RemoteException is thrown, no Entry was removed from the match set because of this call

getLease

Lease getLease()

Returns a proxy to the Lease associated with this match set, or null if this match set is not leased.

Returns:

a proxy for the match set's lease, or null if there is no lease associated with this match set

getSnapshot

Entry getSnapshot()

Returns a snapshot of the Entry removed by the last call to next. Snapshots are defined in section JS.2.6 of the JavaSpaces Service Specification and are an alternative representation of a given Entry produced by a particular space for use with that same space. Passing a snapshot to a space is generally more efficient than passing the original representation.

Any snapshot returned by this method will meet the same contract as the object returned by passing the result of the last next invocation to JavaSpace.snapshot.

Generally there is a cost associated with calling the JavaSpace.snapshot method. Thus creating a snapshot using that method is usually only worthwhile if the resulting snapshot is used more than once. The cost of invoking this method should be low and should be worthwhile even if the resulting snapshot is used only once.

Returns:

a snapshot of the Entry removed from the match set by the last call to next

Throws:

IllegalStateException - if the last call to next did not remove an Entry from the match set, or no call to next has been made