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 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 {@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-nullelement 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