com.j_spaces.core.client
Class NotifyDelegator

java.lang.Object
  com.j_spaces.core.client.NotifyDelegator

All Implemented Interfaces:

INotifyDelegator, Serializable, Remote, EventListener, RemoteEventListener

public class NotifyDelegator
extends Object
implements INotifyDelegator, Serializable

Just like the call to JavaSpace.notify(), it 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 event listener will be called. In comparison to JavaSpace.notify() there is no need to set the client codebase. Both clients and server agree on this proxy object to be used for notifications.

1. Registering for notifications

We use com.j_spaces.core.client.NotifyModifiers as the notification interest. You could either register for all notifications with NotifyModifiers.NOTIFY_ALL or you could use bitwise or operator "|" and have several notifications: e.g. NotifyModifiers.NOTIFY_WRITE | NotifyModifiers.NOTIFY_READ

 NotifyDelegator ntfyDelegator =
        new NotifyDelegator((IJSpace) spaceProxy,
                                new MyEntry(),
                                theTransaction,
                                theListener,
                                Lease.FOREVER,
                                null,
                                fifoEnabled,
                                NotifyModifiers.NOTIFY_ALL);
 

theListener has to implement RemoteEventListener and its inherited method notify().
theTransaction could be either a null transaction or an obtained one from a TransactionManager.

2. The notification event

When new entries that match the template arrive at the space, the supplied listener's notify() method will be called by the delegator. From the notification event you can access the entry that triggered the event in the space, and act upon each interested notification.

 public void notify(RemoteEvent event)
 {
        EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)event;
        int notifyType = arrivedRemoteEvent.getNotifyType();

        // section for write notifications
        if (notifyType == NotifyModifiers.NOTIFY_WRITE)
        {
                MyEntry myEntry = (MyEntry)((EntryArrivedRemoteEvent)event).getEntry();
                ...
        }
 }
 

3. Canceling the registration

In order to cancel the notify registration, you can use the Event Registration object of this delegator:

 ntfyDelegator.getEventRegistration().getLease().cancel();
 

4. Closing the listener

Leasing does not close the NotifyDelegator once the lease expires. Although no notifications will be delegated, it is good practice to close any excess resources.

 ntfyDelegator.close()
 

See Also:

EntryArrivedRemoteEvent, Serialized Form

Constructor Summary

NotifyDelegator(IJSpace space, Entry template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback)
Deprecated. Use NotifyDelegator(IJSpace, Entry, Transaction, RemoteEventListener, long, MarshalledObject, boolean, int)

NotifyDelegator(IJSpace space, Entry template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, boolean fifoEnabled)
Deprecated. NotifyDelegator(IJSpace, Entry, Transaction, RemoteEventListener, long, MarshalledObject, boolean, int)

NotifyDelegator(IJSpace space, Entry template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, boolean fifoEnabled, int notifyMask)
Creates a new delegator that can receive ordered notifications.

NotifyDelegator(IJSpace space, Object template, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback, boolean fifoEnabled, int notifyMask)
Creates a new delegator that can receive ordered notifications.

NotifyDelegator(IJSpace space, RemoteEventListener listener, boolean fifoEnabled)
ADVANCE USAGE, this constructor uses for Wrapping simple notify request.

NotifyDelegator(RemoteEventListener listener)
Deprecated. Use NotifyDelegator(RemoteEventListener, boolean)

NotifyDelegator(RemoteEventListener listener, boolean fifoEnabled)
A supplied listener for use with JavaSpace.notify(Entry, Transaction, RemoteEventListener, long, MarshalledObject).

Method Summary

void	close() Cancels all the registered notify template and un-exports this instance of NotifyDelegator.
EventRegistration	getEventRegistration() Returns an EventRegistration object that can be used to cancel or renew the notification lease, to get the unique id of the registration, to get the sequence number at the time of registration and the space that is the source of the registration.
IJSpace	getSpace() Returns space proxy or null if NotifyDelegator was constructed as listener, not via constructor with spaceProxy as parameter.
void	notify(RemoteEvent theEvent) This is a callback method invoked by the space when an entry that matches the notify templates is written to the space.
void	setSpace(IJSpace space) Set space proxy.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotifyDelegator

public NotifyDelegator(IJSpace space,
                       RemoteEventListener listener,
                       boolean fifoEnabled)

ADVANCE USAGE, this constructor uses for Wrapping simple notify request.

NotifyDelegator

public NotifyDelegator(RemoteEventListener listener)

Deprecated. Use NotifyDelegator(RemoteEventListener, boolean)

Using this constructor only for get notification from supplied listener. This constructor will not notify the template.

Parameters:

listener - Supplied listener to notify delegator.

NotifyDelegator

public NotifyDelegator(RemoteEventListener listener,
                       boolean fifoEnabled)

A supplied listener for use with JavaSpace.notify(Entry, Transaction, RemoteEventListener, long, MarshalledObject). This listener will be embedded at the server-side, handling events remotely. Client, will not receive event notifications.

Parameters:

listener - Supplied listener to notify delegator.

fifoEnabled - enables/disables ordered notifications.

See Also:

NotifyModifiers

NotifyDelegator

public NotifyDelegator(IJSpace space,
                       Entry template,
                       Transaction txn,
                       RemoteEventListener listener,
                       long lease,
                       MarshalledObject handback,
                       boolean fifoEnabled,
                       int notifyMask)
                throws TransactionException,
                       RemoteException

Creates a new delegator that can receive ordered notifications.

Parameters:

space - the space to register for notification.

template - the template to use for notification.

txn - the transaction to use for notification.

listener - user supplied listener (implementing RemoteEventListener).

lease - the lease of the notification template.

handback - the handback to use for notification.

fifoEnabled - enables/disables ordered notifications.

notifyMask - Available Notify Types: NotifyModifiers.NOTIFY_WRITE NotifyModifiers.NOTIFY_UPDATE NotifyModifiers.NOTIFY_TAKE NotifyModifiers.NOTIFY_LEASE_EXPIRATION NotifyModifiers.NOTIFY_ALL NotifyDelegator nd = new NotifyDelegator(space, template, transaction, listener, Lease.FOREVER, handback, true, NotifyModifiers.NOTIFY_WRITE | NotifyModifiers.NOTIFY_TAKE );

Throws:

TransactionException - if the transaction is not valid

RemoteException - if a communication error occurs

See Also:

NotifyModifiers

NotifyDelegator

public NotifyDelegator(IJSpace space,
                       Object template,
                       Transaction txn,
                       RemoteEventListener listener,
                       long lease,
                       MarshalledObject handback,
                       boolean fifoEnabled,
                       int notifyMask)
                throws TransactionException,
                       RemoteException

Creates a new delegator that can receive ordered notifications.

Parameters:

space - the space to register for notification.

template - the template to use for notification.

txn - the transaction to use for notification.

listener - user supplied listener (implementing RemoteEventListener).

lease - the lease of the notification template.

handback - the handback to use for notification.

fifoEnabled - enables/disables ordered notifications.

notifyMask - Available Notify Types: NotifyModifiers.NOTIFY_WRITE NotifyModifiers.NOTIFY_UPDATE NotifyModifiers.NOTIFY_TAKE NotifyModifiers.NOTIFY_LEASE_EXPIRATION NotifyModifiers.NOTIFY_ALL NotifyDelegator nd = new NotifyDelegator(space, template, transaction, listener, Lease.FOREVER, handback, true, NotifyModifiers.NOTIFY_WRITE | NotifyModifiers.NOTIFY_TAKE );

Throws:

TransactionException - if the transaction is not valid

RemoteException - if a communication error occurs

See Also:

NotifyModifiers

NotifyDelegator

public NotifyDelegator(IJSpace space,
                       Entry template,
                       Transaction txn,
                       RemoteEventListener listener,
                       long lease,
                       MarshalledObject handback)
                throws TransactionException,
                       RemoteException

Deprecated. Use NotifyDelegator(IJSpace, Entry, Transaction, RemoteEventListener, long, MarshalledObject, boolean, int)

Creates a new delegator.

Parameters:

space - the space to register for notification.

template - the template to use for notification.

txn - the transaction to use for notification.

listener - user supplied listener.

lease - the lease of the notification template.

handback - the handback to use for notification.

Throws:

TransactionException - if the transaction is not valid

RemoteException - if a communication error occurs

NotifyDelegator

public NotifyDelegator(IJSpace space,
                       Entry template,
                       Transaction txn,
                       RemoteEventListener listener,
                       long lease,
                       MarshalledObject handback,
                       boolean fifoEnabled)
                throws TransactionException,
                       RemoteException

Deprecated. NotifyDelegator(IJSpace, Entry, Transaction, RemoteEventListener, long, MarshalledObject, boolean, int)

Creates a new delegator that can receive ordered notifications triggered by write operations. Equivalent to calling NotifyDelegator(IJSpace, Entry, Transaction, RemoteEventListener, long, MarshalledObject, boolean, int) with NotifyModifiers.NOTIFY_WRITE

Parameters:

space - the space to register for notification.

template - the template to use for notification.

txn - the transaction to use for notification.

listener - user supplied listener.

lease - the lease of the notification template.

handback - the handback to use for notification.

fifoEnabled - enables/disables ordered notifications.

Throws:

TransactionException - if the transaction is not valid

RemoteException - if a communication error occurs

Method Detail

getEventRegistration

public EventRegistration getEventRegistration()

Returns an EventRegistration object that can be used to cancel or renew the notification lease, to get the unique id of the registration, to get the sequence number at the time of registration and the space that is the source of the registration.

Returns:

the EventRegistration object returned from calling notify() on the space.

notify

public void notify(RemoteEvent theEvent)
            throws UnknownEventException,
                   RemoteException

This is a callback method invoked by the space when an entry that matches the notify templates is written to the space. This method delegates the call to the user supplied listener.

Specified by:

notify in interface RemoteEventListener

Parameters:

theEvent - the event that the space sent. This event includes the event id, the source, the handback and the sequence number of the notification.

Throws:

UnknownEventException - if the user-supplied listener throws this event.

RemoteException - if the user-supplied listener throws this event.

getSpace

public IJSpace getSpace()

Returns space proxy or null if NotifyDelegator was constructed as listener, not via constructor with spaceProxy as parameter.

Returns:

space proxy.

setSpace

public void setSpace(IJSpace space)

Set space proxy. For internal use

Parameters:

space - space proxy to set.

close

public void close()

Cancels all the registered notify template and un-exports this instance of NotifyDelegator.