net.jini.space

Interface JavaSpace05

All Superinterfaces:

JavaSpace

public interface JavaSpace05
extends JavaSpace

The JavaSpace05 interface extends the JavaSpace interface to provide methods that allow clients to perform batch operations on the space (which are generally more efficient than performing an equivalent set of singleton operations) and to more easily develop applications where a given Entry needs to be read by multiple clients. Implementations of the JavaSpace interface are not required to implement this interface.

Unless otherwise noted, the effects of any invocation of a method defined by this interface must be visible to any operation on the space that is started after the invocation returns normally. Note, the effects of a method invocation that throws a RemoteException are not necessarily visible when the exception is thrown.

All of the methods of this interface take one or more Collections as arguments. Each such Collection must be treated as immutable by implementations and must not be changed by the client during the course of any method invocation to which they have been passed.

This interface is not a remote interface. Each implementation of this interface exports a proxy object that implements this interface local to the client. Each method of the interface takes as one of its arguments a Collection of Entry instances. The entries themselves must be serialized in accordance with the Jini Entry Specification and will not be altered by the call. Typically, the Collection holding the entries will not be serialized at all. If one of these entries can't be serialized, a MarshalException will be thrown. Aside from the handling of these Collection of Entry parameters, all methods defined by this interface otherwise obey normal Java(TM) Remote Method Invocation remote interface semantics.

Since:

2.1

See Also:

JavaSpaces Service Specification, Jini Entry Specification

Field Summary

Fields inherited from interface net.jini.space.JavaSpace

NO_WAIT

Method Summary

Modifier and Type	Method and Description
MatchSet	contents(Collection tmpls, Transaction txn, long leaseDuration, long maxEntries) Creates a match set that can be used to exhaustively read through all of the matching entries in the space that are visible to the passed Transaction and remain visible for the lifetime of the match set.
EventRegistration	registerForAvailabilityEvent(Collection tmpls, Transaction txn, boolean visibilityOnly, RemoteEventListener listener, long leaseDuration, MarshalledObject handback) Register for events triggered when a matching Entry transitions from unavailable to available.
Collection	take(Collection tmpls, Transaction txn, long timeout, long maxEntries) This method provides an overload of the JavaSpace.take method that attempts to remove, optionally under a Transaction, and return one or more entries from the space.
List	write(List entries, Transaction txn, List leaseDurations) This method provides an overload of the JavaSpace.write method that allows new copies of multiple Entry instances to be stored in the space using a single call.

Methods inherited from interface net.jini.space.JavaSpace

notify, read, readIfExists, snapshot, take, takeIfExists, write

Method Detail

write

List write(List entries,
           Transaction txn,
           List leaseDurations)
    throws TransactionException,
           RemoteException

This method provides an overload of the JavaSpace.write method that allows new copies of multiple Entry instances to be stored in the space using a single call. The client may specify a Transaction for the operation to be performed under. Each Entry to be stored in the space has a separate requested initial lease duration.

The effect on the space of an invocation of this method successfully storing an Entry is the same as if the Entry had been successfully stored by a call to the singleton form of write under txn with the given requested initial lease duration. This method returns the proxies to the leases for each newly stored Entry by returning a List of Lease instances. The i th element of the returned List will be a proxy for the lease on the Entry created from the i th element of entries.

If an invocation of this method returns normally, then a new copy of each element of entries must have been stored in the space. A new copy of each element will be stored even if there are duplicates (either in terms of object identity or of entry equivalence) in entries.

The order in which the entries stored by an invocation of this method will become visible in the space is unspecified, and different observers may see the entries become visible in different orders.

If a TransactionException, SecurityException, IllegalArgumentException, or NullPointerException is thrown, no entries will have been added to the space by this operation. If a RemoteException is thrown, either new copies of all of the elements of entries will have been stored or no entries will have been stored; that is, in the case of a RemoteException, the storing of new entries in the space will either fail or succeed as a unit.

Parameters:

entries - a List of Entry instances to be written to the space

txn - the Transaction this operation should be performed under, may be null

leaseDurations - a List of Longs representing the requested initial lease durations

Returns:

a List of Lease instances, one for each element of entries, may be immutable. The space will not keep a reference to the result

Throws:

TransactionException - if txn is non-null and is not usable by the space

RemoteException - if a communication error occurs

IllegalArgumentException - if entries and leaseDurations are not the same length or are empty, if any element of entries is not an instance of Entry, if any element of leaseDurations is not an instance of Long, or if any element of leaseDurations is a negative value other than Lease.ANY

NullPointerException - if either entries or leaseDurations is null or contains a null value

take

Collection take(Collection tmpls,
                Transaction txn,
                long timeout,
                long maxEntries)
         throws UnusableEntriesException,
                TransactionException,
                RemoteException

This method provides an overload of the JavaSpace.take method that attempts to remove, optionally under a Transaction, and return one or more entries from the space. Each Entry taken will match one or more elements of the passed Collection of templates, and all of the taken entries will be visible to the passed Transaction. If there are initially no matches in the space that are visible to the passed Transaction, an invocation of this method will block for up to a specified timeout for one or more matches to appear.

The effect on the space of an invocation of this method successfully taking an Entry will be the same as if the Entry had been taken using the singleton version of this method and passing txn as the Transaction.

The tmpls parameter must be a Collection of Entry instances to be used as templates. All of the entries taken must match one or more of these templates. The tmpls parameter may contain null values and may contain duplicates. An Entry is said to be available to an invocation of this method if the Entry could have been returned by an invocation of the singleton take method using txn.

If the method succeeds, a non-null Collection will be returned. The Collection will contain a copy of each Entry that was taken. If no entries were taken, the Collection will be empty. Each Entry taken will be represented by a distinct Entry instance in the returned Collection, even if some of the entries are equivalent to others taken by the operation. There will be no null elements in the returned Collection.

If one or more of the entries taken cannot be unmarshalled in the client, an UnusableEntriesException is thrown. The exception's UnusableEntriesException.getEntries method will return a Collection with a copy of each Entry that could be unmarshalled. The UnusableEntriesException.getUnusableEntryExceptions method will return a Collection with an UnusableEntryException for each Entry that could not be unmarshalled. Every Entry taken by the invocation will either be represented in the Collection returned by getEntries or in the Collection returned by getUnusableEntryExceptions.

If there is at least one matching Entry available in the space, an invocation of this method must take at least one Entry. If more than one matching Entry is available, the invocation may take additional entries. It must not take more than maxEntries, but an implementation may chose to take fewer entries from the space than the maximum available or the maximum allowed by maxEntries. If for whatever reason, an invocation of this method takes fewer entries than the maximum number of available matching entries, how an implementation selects which entries should be taken by the invocation and which are left in the space is unspecified. How consumption of entries is arbitrated between conflicting queries is also unspecified.

If there are initially no matching entries in the space, an invocation of this method should block for up to timeout milliseconds for a match to appear. If one or more matches become available before timeout expires, one or more of the newly available entries should be taken and the method should return without further blocking. If for some reason the invocation can't block for the full timeout and no entries have been taken, the invocation must fail with a RemoteException or TransactionException as appropriate.

If an invocation of this method removes (or locks) more than one Entry, the order in which the removal (or locking) occurs is undefined, and different observers may see the removal or locking of the entries in different orders.

If a TransactionException, SecurityException, IllegalArgumentException, or NullPointerException is thrown, no entries will have been taken. If a RemoteException is thrown, up to maxEntries may have been taken by this operation.

Parameters:

tmpls - a Collection of Entry instances, each representing a template. All of the entries taken by an invocation of this method will match one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

timeout - if there are initially no available matches in the space, the maximum number of milliseconds to block waiting for a match to become available

maxEntries - the maximum number of entries that may be taken by this method

Returns:

a Collection that contains a copy of each Entry taken from the space by this method. The space will not keep a reference to this Collection. May be immutable

Throws:

UnusableEntriesException - if one or more of the entries taken can't be unmarshalled in the client

TransactionException - if txn is non-null and is not usable by the space.

RemoteException - if a communication error occurs

IllegalArgumentException - if any non-null element of tmpls is not an instance of Entry, if tmpls is empty, if timeout is negative, or if maxEntries is non-positive

NullPointerException - if tmpls is null

contents

MatchSet contents(Collection tmpls,
                  Transaction txn,
                  long leaseDuration,
                  long maxEntries)
           throws TransactionException,
                  RemoteException

Creates a match set that can be used to exhaustively read through all of the matching entries in the space that are visible to the passed Transaction and remain visible for the lifetime of the match set. May also yield additional entries that match but are only visible for part of the lifetime of the match set.

The tmpls parameter must be a Collection of Entry instances to be used as templates. All of the entries placed in the match set will match one or more of these templates. tmpls may contain null values and may contain duplicates. An Entry is said to be visible to an invocation of this method if the Entry could have been returned by a singleton JavaSpace.read using the same transaction.

The resulting match set must initially contain all of the visible matching entries in the space. During the lifetime of the match set an Entry may be, but is not required to be, added to the match set if it becomes visible. If the match set becomes empty, no more entries can be added and the match set enters the exhausted state.

Normally there are three conditions under which an Entry might be removed from the match set:

• Any Entry yielded by an invocation of the MatchSet.next method on the match set (either as the return value of a successful call or embedded in an UnusableEntryException) must be removed from the match set.
• Any Entry that remains in the match set after maxEntries entries are yielded by next invocations must be removed from the match set. In such a case, the criteria used to select which entries are yielded by next calls and which get removed from the set at the end is unspecified.
• Any Entry that during the lifetime of the match set becomes invisible may at the discretion of the implementation be removed from the match set.

An implementation may decide to remove an Entry from the set for other reasons. If it does so, however, it must invalidate the set.

If txn is non-null and still active, any Entry removed from the match set by a next call must be locked as if it had been returned by a read operation using txn. An implementation may establish the read lock on the Entry any time between when the Entry is added to the match set and when the Entry is removed from the match set by an invocation of next. These read locks are not released when the match set reaches either the exhausted state or the invalidated state. If from the space's perspective the txn leaves the active state, the space must remove from the match set any entries in the match set that have not yet been read locked. This may require the match set to be invalidated.

If the match set is leased and leaseDuration is positive, the initial duration of the lease must be less than or equal to leaseDuration. If leaseDuration is Lease.ANY, the initial duration of the lease can be any positive value desired by the implementation.

If there are remote method constraints associated with an invocation of this method, any remote communications performed by or on behalf of the match set's next method will be performed in compliance with these constraints, not with the constraints (if any) associated with next.

Parameters:

tmpls - a Collection of Entry instances, each representing a template. All the entries added to the resulting match set will match one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

leaseDuration - the requested initial lease time on the resulting match set

maxEntries - the maximum number of entries to remove from the set via MatchSet.next calls

Returns:

A proxy to the newly created match set

Throws:

TransactionException - if txn is non-null and is not usable by the space

RemoteException - if a communication error occurs

IllegalArgumentException - if any non-null element of tmpls is not an instance of Entry, if tmpls is empty, if leaseDuration is neither positive nor Lease.ANY, or if maxEntries is non-positive

NullPointerException - if tmpls is null

registerForAvailabilityEvent

EventRegistration registerForAvailabilityEvent(Collection tmpls,
                                               Transaction txn,
                                               boolean visibilityOnly,
                                               RemoteEventListener listener,
                                               long leaseDuration,
                                               MarshalledObject handback)
                                        throws TransactionException,
                                               RemoteException

Register for events triggered when a matching Entry transitions from unavailable to available. The resulting events will be instances of the AvailabilityEvent class and the AvailabilityEvent.getEntry method will return a copy of the Entry whose transition triggered the event.

An Entry makes a transition from unavailable to available when it goes from being in a state where it could not be returned by a JavaSpace.take using txn to a state where it could be returned. An Entry makes a transition from invisible to visible when it goes from being in a state where it could not be returned by a JavaSpace.read using txn to a state where it could be returned. Note, any transition from invisible to visible is also a transition from unavailable to available, but an already visible entry can be unavailable and then make a transition from unavailable to available. Because the entry was already visible, this transition would not be a transition from invisible to visible.

The tmpls parameter must be a Collection of Entry instances to be used as templates. Events will be generated when an Entry that matches one or more of these templates makes an appropriate transition. A single transition will generate only one event per registration, in particular the transition of an Entry that matches multiple elements of tmpls must still generate exactly one event for this registration. If a given Entry undergoes multiple applicable transitions while the registration is active, each must generate a separate event.

Events are not generated directly by the transition of matching entries, but instead by an abstract observer set up in the space for each registration. The observer may see the transitions out of order and as a result the order of the events generated for this registration (as determined by the sequence numbers assigned to the events) may be different from the order of the transitions themselves. Additionally, each registration will have its own abstract observer and different observers may see the same sequence of transitions in different orders. As a result, given a set of transitions that trigger events for two different registrations, the order of the events generated for one registration may differ from the order of the events generated for the other.

A non-null EventRegistration object will be returned. Each registration will be assigned an event ID. The event ID will be unique at least with respect to all other active event registrations for AvailabilityEvents on this space with a non-equivalent set of templates, a different transaction, and/or a different value for the visibilityOnly flag. The event ID can be obtained by calling the EventRegistration.getID method on the returned EventRegistration. The returned EventRegistration object's EventRegistration.getSource method will return a reference to the space.

Registrations are leased. leaseDurations represents the client's desired initial lease duration. If leaseDuration is positive, the initial lease duration will be a positive value less than or equal to leaseDuration. If leaseDuration is Lease.ANY, the space is free to pick any positive initial lease duration it desires. A proxy for the lease associated with the registration can be obtained by calling the returned EventRegistration's EventRegistration.getLease method.

A registration made with a non-null value for txn is implicitly dropped when the space observes txn has left the active state.

Parameters:

tmpls - a Collection of Entry instances, each representing a template. Events for this registration will be generated by the transitions of entries matching one or more elements of tmpls

txn - the Transaction this operation should be performed under, may be null

visibilityOnly - if true, events will be generated for this registration only when a matching Entry transitions from invisible to visible, otherwise events will be generated when a matching Entry makes any transition from unavailable to available

listener - the object to which events generated for this registration should be delivered

leaseDuration - the requested initial lease time on the resulting event registration

handback - the MarshalledObject to be returned by the RemoteEvent.getRegistrationObject method of the events generated for this registration

Returns:

an EventRegistration object with information on this registration

Throws:

TransactionException - if txn is non-null and is not usable by the space

RemoteException - if a communication error occurs

IllegalArgumentException - if any non-null element of tmpls is not an instance of Entry, if tmpls is empty, or if leaseDuration is neither positive nor Lease.ANY

NullPointerException - if tmpls or listener is null