net.jini.space

Interface TupleSpace

All Superinterfaces:

JavaSpace, JavaSpace05

public interface TupleSpace
extends JavaSpace05

Author:

peter

Field Summary

Fields inherited from interface net.jini.space.JavaSpace

NO_WAIT

Method Summary

Modifier and Type	Method and Description
EventRegistration	notify(Entry tmpl, Transaction txn, RemoteEventListener listener, long lease, MarshalledInstance handback) When entries are written that match this template notify the given listener with a RemoteEvent that includes the handback object.
EventRegistration	registerForAvailabilityEvent(Collection tmpls, Transaction txn, boolean visibilityOnly, RemoteEventListener listener, long leaseDuration, MarshalledInstance handback) Register for events triggered when a matching Entry transitions from unavailable to available.

Methods inherited from interface net.jini.space.JavaSpace05

contents, registerForAvailabilityEvent, take, write

Methods inherited from interface net.jini.space.JavaSpace

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

Method Detail

notify

EventRegistration notify(Entry tmpl,
                         Transaction txn,
                         RemoteEventListener listener,
                         long lease,
                         MarshalledInstance handback)
                  throws TransactionException,
                         RemoteException

When entries are written that match this template notify the given listener with a RemoteEvent that includes the handback object. Matching is done as for read.

Parameters:

tmpl - The template used for matching. Matching is done against tmpl with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").

txn - The transaction (if any) under which to work.

listener - The remote event listener to notify.

lease - the requested lease time, in milliseconds

handback - An object to send to the listener as part of the event notification.

Returns:

the event registration to the the registrant

Throws:

TransactionException - if a transaction error occurs

RemoteException - if a communication error occurs

IllegalArgumentException - if the lease time requested is not Lease.ANY and is negative

See Also:

JavaSpace.read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long), EventRegistration

registerForAvailabilityEvent

EventRegistration registerForAvailabilityEvent(Collection tmpls,
                                               Transaction txn,
                                               boolean visibilityOnly,
                                               RemoteEventListener listener,
                                               long leaseDuration,
                                               MarshalledInstance 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 TupleSpace.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 TupleSpace.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 MarshalledInstance 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