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, {@link JavaSpace05#contents 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 {@link #next 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 {@link NoSuchObjectException} to indicate that the matchset 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 {@link #getLease getLease} method. If there isno 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 {@linkplain #next description}it deviates in a number of ways from normal Java(TM) Remote Method Invocation remote method semantics.
@since 2.1
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |