The JavaSpace Interface (Java Distributed Computing)

C.4. The JavaSpace Interface

The JavaSpace specification also defines a JavaSpace class that provides an interface to a remote JavaSpace. The JavaSpace interface provides read(), write(), take(), and notify() methods, which allow clients to perform the basic operations on the JavaSpace. Each of these methods takes an EntryRep (used as either an entry to put into the space, or a template to use for matching an entry already in the space), an optional Transaction within which the operation should be carried out, and an optional Identity, which can be used to verify the client's access to the JavaSpace entries against an access-control list. The Identity can be used to verify the caller's right to execute the given operation on the JavaSpace, perhaps by checking an access-control list. The current specification is not clear about whether this Identity argument will use the Identity class from the Java Security API, but it seems likely that it would.

The rest of this section describes the methods available on the JavaSpace interface for executing operations and transactions against the space.

C.4.1. write()

void write(EntryRep r, Transaction t, Identity i)  
    throws RemoteException, TransactionException, SecurityException

A write() call adds an EntryRep to the JavaSpace. Each field in the enclosed Entry is serialized independently, and the serialized bytes making up the entire Entry are sent to the JavaSpace for storage and later lookup. If a Transaction is included in the write() call, then the new entry isn't visible to other clients of the JavaSpace until the entire Transaction executes. If the entry is taken during the course of the rest of the Transaction, then the Transaction, including the write operation, will succeed, but the new entry will never be seen by other clients of the JavaSpace.

C.4.2. read()

EntryRep read(EntryRep template, Transaction t, Identity i) 
    throws RemoteException, TransactionException, SecurityException

If an entry in the JavaSpace matches the EntryRep template, it is returned from the method call as an EntryRep object. If a non-nullTransaction is included in the read() call, then a matching EntryRep will only be returned if the entire Transaction succeeds. Any entries that are read during the course of the enclosing Transaction are put on a pending list, and can't be taken by other operations or transactions until the read and its Transaction are finished (successfully executed or aborted). If all entries matching the read()'s template entry are pending in unfinished transactions, then a TransactionConflictException is thrown.

C.4.3. take()

EntryRep take(EntryRep template, Transaction t, Identity i) 
    throws RemoteException, TransactionException, SecurityException

The take() operation on the JavaSpace interface behaves much like the read() operation, except that a matching entry is also removed from the space. If the Transaction argument is non-null, then a matching entry won't be returned until the Transaction completes. If a RemoteException is raised by the take() call, then it's possible that the entry was removed from the space but not returned in its entirety.

C.4.4. notify()

EventRegID notify(EntryRep template, EventCatcher c, Transaction t, 
                  Identity i, int timeout) 
    throws RemoteException, TransactionException, SecurityException

A call to notify() serves to register interest in matching entries for a specific period of time. If a matching entry is written to the space before the notification request expires, then the notify() method on the given EventCatcher will be called. The EventRegID object returned to the client contains a set of long values, including an event ID that will come with the notification, a cookie value that can be used to renew or cancel the notification, and the actual timeout period assigned to the notification request by the JavaSpace. If a non-nullTransaction is passed into the method call, then the event catcher will be notified of matching entries for the duration of the enclosing Transaction. At the end of the transaction, the notification request will be dropped from the space.

The JavaSpace interface also includes the following two methods for controlling notification requests that have been previously issued to the space.

C.4.5. renew()

long renew(long cookie, long extension) 
    throws RemoteException, NotRegisteredException

This method allows a client to request an extension to a notification request. The cookie argument is the value returned in the EventRegID from the original notify() call and the extension is the desired extension to the registered notification. The method returns the actual time extension granted by the JavaSpace, if any. The units of these time values have not yet been detailed in the JavaSpaces specification.

C.4.6. cancel()

void cancel(long cookie) throws RemoteException, NotRegisteredException

The notification request associated with the cookie is cancelled.