JS.2. Operations

There are four primary kinds of operations that you can invoke on a JavaSpaces service. Each operation has parameters that are entries, including some that are templates, which are a kind of entry. This chapter describes entries, templates, and the details of the operations, which are:

• write: Write the given entry into this JavaSpaces service.

• read: Read an entry from this JavaSpaces service that matches the given template.

• take: Read an entry from this JavaSpaces service that matches the given template, removing it from this space.

• notify: Notify a specified object when entries that match the given template are written into this JavaSpaces service.

As used in this document, the term “operation” refers to a single invocation of a method; for example, two different take operations may have different templates.

JS.2.1. Entries

The types Entry and UnusableEntryException that are used in this specification are from the package net.jini.core.entry and are described in detail in The Jini Technology Core Platform Specification, “Entry”. In the terminology of that specification write is a store operation; read and take are combination search and fetch operations; and notify sets up repeated search operations as entries are written to the space.

JS.2.2. net.jini.space.JavaSpace

All operations are invoked on an object that implements the JavaSpace interface. For example, the following code fragment would write an entry of type AttrEntry into the JavaSpaces service referred to by the identifier space:

JavaSpace space = getSpace(); 
AttrEntry e = new AttrEntry(); 
e.name = "Duke"; 
e.value = new GIFImage("dukeWave.gif"); 
space.write(e, null, 60 * 60 * 1000);// one hour 
// lease is ignored -- one hour will be enough 

The JavaSpace interface is:

package net.jini.space; 

import java.rmi.*; 
import net.jini.core.event.*; 
import net.jini.core.transaction.*; 
import net.jini.core.lease.*; 

public interface JavaSpace {
    Lease write(Entry e, Transaction txn, long lease) 
        throws RemoteException, TransactionException; 
    public final long NO_WAIT = 0; // don't wait at all 
    Entry read(Entry tmpl, Transaction txn, long timeout) 
        throws TransactionException, UnusableEntryException, 
               RemoteException, InterruptedException; 
    Entry readIfExists(Entry tmpl, Transaction txn, 
                       long timeout) 
        throws TransactionException, UnusableEntryException, 
               RemoteException, InterruptedException; 
    Entry take(Entry tmpl, Transaction txn, long timeout) 
        throws TransactionException, UnusableEntryException, 
               RemoteException, InterruptedException; 
    Entry takeIfExists(Entry tmpl, Transaction txn, 
                       long timeout) 
        throws TransactionException, UnusableEntryException, 
               RemoteException, InterruptedException; 
    EventRegistration notify(Entry tmpl, Transaction txn, 
              RemoteEventListener listener, long lease, 
              MarshalledObject handback) 
        throws RemoteException, TransactionException; 
    Entry snapshot(Entry e) throws RemoteException; 
} 

The Transaction and TransactionException types in the above signatures are imported from net.jini.core.transaction. The Lease type is imported from net.jini.core.lease. The RemoteEventListener and EventRegistration types are imported from net.jini.core.event.

In all methods that have the parameter, txn may be null, which means that no Transaction object is managing the operation (see Section JS.3, “Transactions”).

The JavaSpace interface is not a remote interface. Each implementation of a JavaSpaces service exports proxy objects that implement the JavaSpace interface locally on the client, talking to the actual JavaSpaces service through an implementation-specific interface. An implementation of any JavaSpace method may communicate with a remote JavaSpaces service to accomplish its goal; hence, each method throws RemoteException to allow for possible failures. Unless noted otherwise in this specification, when you invoke JavaSpace methods you should expect RemoteExceptions on method calls in the same cases in which you would expect them for methods invoked directly on an RMI remote reference. For example, invoking snapshot might require talking to the remote JavaSpaces server, and so might get a RemoteException if the server crashes during the operation.

The details of each JavaSpace method are given in the sections that follow.

JS.2.2.1. InternalSpaceException

The exception InternalSpaceException may be thrown by a JavaSpaces service that encounters an inconsistency in its own internal state or is unable to process a request because of internal limitations (such as storage space being exhausted). This exception is a subclass of RuntimeException. The exception has two constructors: one that takes a String description and another that takes a String and a nested exception; both constructors simply invoke the RuntimeException constructor that takes a String argument.

package net.jini.space; 

public class InternalSpaceException extends RuntimeException {
    public final Throwable nestedException; 
    public InternalSpaceException(String msg) {...} 
    public InternalSpaceException(String msg, Throwable e) {...} 
    public printStackTrace() {...} 
    public printStackTrace(PrintStream out) {...} 
    public printStackTrace(PrintWriter out) {...} 
} 

The nestedException field is the one passed to the second constructor, or null if the first constructor was used. The overridden printStackTrace methods print out the stack trace of the exception and, if nestedException is not null, print out that stack trace as well.

JS.2.3. write

A write places a copy of an entry into the given JavaSpaces service. The Entry passed to the write is not affected by the operation. Each write operation places a new entry into the specified space, even if the same Entry object is used in more than one write.

Each write invocation returns a Lease object that is lease milliseconds long. If the requested time is longer than the space is willing to grant, you will get a lease with a reduced time. When the lease expires, the entry is removed from the space. You will get an IllegalArgumentException if the lease time requested is negative.

If a write returns without throwing an exception, that entry is committed to the space, possibly within a transaction (see Section JS.3, “Transactions”). If a RemoteException is thrown, the write may or may not have been successful. If any other exception is thrown, the entry was not written into the space.

Writing an entry into a space might generate notifications to registered objects (see Section JS.2.7, “notify”).

JS.2.4. readIfExists and read

The two forms of the read request search the JavaSpaces service for an entry that matches the template provided as an Entry. If a match is found, a reference to a copy of the matching entry is returned. If no match is found, null is returned. Passing a null reference for the template will match any entry.

Any matching entry can be returned. Successive read requests with the same template in the same JavaSpaces service may or may not return equivalent objects, even if no intervening modifications have been made to the space. Each invocation of read may return a new object even if the same entry is matched in the JavaSpaces service.

A readIfExists request will return a matching entry, or null if there is currently no matching entry in the space. If the only possible matches for the template have conflicting locks from one or more other transactions, the timeout value specifies how long the client is willing to wait for interfering transactions to settle before returning a value. If at the end of that time no value can be returned that would not interfere with transactional state, null is returned. Note that, due to the remote nature of JavaSpaces services, read and readIfExists may throw a RemoteException if the network or server fails prior to the timeout expiration

A read request acts like a readIfExists except that it will wait until a matching entry is found or until transactions settle, whichever is longer, up to the timeout period.

In both read methods, a timeout of NO_WAIT means to return immediately, with no waiting, which is equivalent to using a zero timeout. An IllegalArgumentException will be thrown if a negative timeout value is used.

JS.2.5. takeIfExists and take

The take requests perform exactly like the corresponding read requests (see Section JS.2.4, “readIfExists and read”), except that the matching entry is removed from the space. Two take operations will never return copies of the same entry, although if two equivalent entries were in the JavaSpaces service the two take operations could return equivalent entries.

If a take returns a nonnull value, the entry has been removed from the space, possibly within a transaction (see Section JS.3, “Transactions”). This modifies the claims to once-only retrieval: A take is considered to be successful only if all enclosing transactions commit successfully. If a RemoteException is thrown, the take may or may not have been successful. If an UnusableEntryException is thrown, the take removed the unusable entry from the space; the contents of the exception are as described in The Jini Technology Core Platform Specification, “Entry”. If any other exception is thrown, the take did not occur, and no entry was removed from the space.

With a RemoteException, an entry can be removed from a space and yet never returned to the client that performed the take, thus losing the entry in between. In circumstances in which this is unacceptable, the take can be wrapped inside a transaction that is committed by the client when it has the requested entry in hand.

JS.2.6. snapshot

The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice. This is most likely to be an issue with templates that are used repeatedly to search for entries with read or take. The client-side implementations of read and take cannot reasonably avoid this duplicated effort, since they have no efficient way of checking whether the same template is being used without intervening modification.

The snapshot method gives the JavaSpaces service implementor a way to reduce the impact of repeated use of the same entry. Invoking snapshot with an Entry will return another Entry object that contains a snapshot of the original entry. Using the returned snapshot entry is equivalent to using the unmodified original entry in all operations on the same JavaSpaces service. Modifications to the original entry will not affect the snapshot. You can snapshot a null template; snapshot may or may not return null given a null template.

The entry returned from snapshot will be guaranteed equivalent to the original unmodified object only when used with the space. Using the snapshot with any other JavaSpaces service will generate an IllegalArgumentException unless the other space can use it because of knowledge about the JavaSpaces service that generated the snapshot. The snapshot will be a different object from the original, may or may not have the same hash code, and equals may or may not return true when invoked with the original object, even if the original object is unmodified.

A snapshot is guaranteed to work only within the virtual machine in which it was generated. If a snapshot is passed to another virtual machine (for example, in a parameter of an RMI call), using it—even with the same JavaSpaces service— may generate an IllegalArgumentException.

We expect that an implementation of JavaSpaces technology will return a specialized Entry object that represents a pre-serialized version of the object, either in the object itself or as an identifier for the entry that has been cached on the server. Although the client may cache the snapshot on the server, it must guarantee that the snapshot returned to the client code is always valid. The implementation may not throw any exception that indicates that the snapshot has become invalid because it has been evicted from a cache. An implementation that uses a server-side cache must therefore guarantee that the snapshot is valid as long as it is reachable (not garbage) in the client, such as by storing enough information in the client to be able to re-insert the snapshot into the server-side cache.

No other method returns a snapshot. Specifically, the return values of the read and take methods are not snapshots and are usable with any implementation of JavaSpaces technology.

JS.2.7. notify

A notify request registers interest in future incoming entries to the JavaSpaces service that match the specified template. Matching is done as it is for read. The notify method is a particular registration method under The Jini Technology Core Platform Specification, “Distributed Events”. When matching entries are written, the specified RemoteEventListener will eventually be notified. When you invoke notify you provide an upper bound on the lease time, which is how long you want the registration to be remembered by the JavaSpaces service. The service decides the actual time for the lease. You will get an IllegalArgumentException if the lease time requested is not Lease.ANY and is negative. The lease time is expressed in the standard millisecond units, although actual lease times will usually be of much larger granularity. A lease time of Lease.FOREVER is a request for an indefinite lease; if the service chooses not to grant an indefinite lease, it will return a bounded (non-zero) lease.

Each notify returns a net.jini.core.event.EventRegistration object. When an object is written that matches the template supplied in the notify invocation, the listener’s notify method is eventually invoked, with a RemoteEvent object whose evID is the value returned by the EventRegistration object’s getEventID method, fromWhom being the JavaSpaces service, seqNo being a monotonically increasing number, and whose getRegistrationObject being that passed as the handback parameter to notify. If you get a notification with a sequence number of 103 and the EventRegID object’s current sequence number is 100, there will have been three matching entries written since you invoked notify. You may or may not have received notification of the previous entries due to network failures or the space compressing multiple matching entry events into a single call.

If the transaction parameter is null, the listener will be notified when matching entries are written either under a null transaction or when a transaction commits. If an entry is written under a transaction and then taken under that same transaction before the transaction is committed, listeners registered under a null transaction will not be notified of that entry.

If the transaction parameter is not null, the listener will be notified of matching entries written under that transaction in addition to the notifications it would receive under a null transaction. A notify made with a nonnull transaction is implicitly dropped when the transaction completes.

The request specified by a successful notify is as persistent as the entries of the space. They will be remembered as long as an untaken entry would be, until the lease expires, or until any governing transaction completes, whichever is shorter.

The service will make a “best effort” attempt to deliver notifications. The service will retry at most until the notification request’s lease expires. Notifications may be delivered in any order.

See The Jini Technology Core Platform Specification, “Distributed Events” for details on the event types.

JS.2.8. Operation Ordering

Operations on a space are unordered. The only view of operation order can be a thread’s view of the order of the operations it performs. A view of inter-thread order can be imposed only by cooperating threads that use an application-specific protocol to prevent two or more operations being in progress at a single time on a single JavaSpaces service. Such means are outside the purview of this specification.

For example, given two threads T and U, if T performs a write operation and U performs a read with a template that would match the written entry, the read may not find the written entry even if the write returns before the read. Only if T and U cooperate to ensure that the write returns before the read commences would the read be ensured the opportunity to find the entry written by T (although it still might not do so because of an intervening take from a third entity).

JS.2.9. Serialized Form