Register for events triggered when a matching {@link Entry}transitions from unavailable to available. The resulting events will be instances of the {@link AvailabilityEvent}class and the {@link AvailabilityEvent#getEntry AvailabilityEvent.getEntry} method will return a copy ofthe
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 {@link JavaSpace#take JavaSpace.take} using txn
to astate 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 {@link JavaSpace#read JavaSpace.read} usingtxn
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 {@link Collection} of Entry
instances to be used astemplates. 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
{@link EventRegistration} objectwill 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 AvailabilityEvent
s 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 {@link EventRegistration#getID EventRegistration.getID} method on the returnedEventRegistration
. The returned EventRegistration
object's {@link EventRegistration#getSource 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 {@link Lease#ANY 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 {@link EventRegistration#getLease 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.
@param tmpls a {@link Collection} of {@link 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
@param txn the {@link Transaction} this operation should beperformed under, may be null
@param visibilityOnly if true
, events willbe 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
@param listener the object to which events generated forthis registration should be delivered
@param leaseDuration the requested initial lease time onthe resulting event registration
@param handback the {@link MarshalledObject} to be returned by the {@link RemoteEvent#getRegistrationObject RemoteEvent.getRegistrationObject} method ofthe events generated for this registration
@return an {@link EventRegistration} object withinformation on this registration
@throws TransactionException if txn
isnon-null
and is not usable by the space
@throws RemoteException if a communication error occurs
@throws 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 {@link Lease#ANY Lease.ANY}
@throws NullPointerException if tmpls
orlistener
is null