Overview

The NotifyDelegator is a convenient and efficient mechanism for registering notifications. These notifications are delivered as remote events for matching entries.

A Notify registration triggers notification only when there is an exact match between a specified template and an entry arriving into the space. Thus, an entry can only match a single notify template. In situations where an entry must match different templates, multiple write/update operations are required, which impact on performance and scalability.

Tokenized templates provide a simple and scalable mechanism that allows notifications of several different notify templates (each with a different token field value) to be triggered for a single space operation. This approach relies on fast indexes to effectively locate matching templates, without impacting on performance and scalability due to the fact that numerous notify templates have been registered.

How it Works

A TokenQuery object is constructed with the user's entry and the chosen tokenized field. The TokenQuery object is used as the template object of the NotifyDelegator constructor.. Each token-template is automatically indexed by its token field value (It is not advisable, and in effect useless, to define it as an index field in the class). The token-template is then used to register notifications.

MyEntry myEntry = new MyEntry(...);
myEntry.tokenField = "token1"; 

TokenQuery tkTemplate = new TokenQuery( myEntry, "tokenField" );
NotifyDelegator nDelegator = new NotifyDelegator(space, tkTemplate,...);

When a user Entry is written to the space, the tokenized field will be used for matching notify templates. The tokenized field is a string of tokens separated by a defined delimiter (a separator character). By default, this is a single space-character, but can be configured through the space configuration file, using the following parameter:

<engine>
<tokenized_fields_delimiter>;</tokenized_fields_delimiter>
   ...
</engine>

When performing space operations, each token (in the tokenized field of the written Entry) will trigger notifications for matching templates. Thus, a single operation can trigger different notify registrations.

For example, consider a mailing list with different defined groups. You can send mail to all members in the group, or explicitly define sub-groups. A single write operation will trigger notifications for each of the different tokens (assuming a matching template was registered).

MyEntry myEntry = new MyEntry(...);
myEntry.tokenField = "token1;token2;token3";
spaceProxy.write(myEntry, null, lease);

If you need to terminate the NotifyDelegator before the lease expires, it is recommended to use the method NotifyDelegator.close(). This cancels the template lease and destroys the NotifyDelegator object. It is not recommended to use NotifyDelegator.getEventRegistration().getLease().cancel() because this cancels the lease but leaves the NotifyDelegator idle in memory.

In the following figure, a client has registered three notify templates, each with a different token field, with a corresponding listener. By setting the tokenized field, a space operation triggers each notify registration for a matching Entry and a valid token.

Limitations

1. The tokenized field must be accessible (public) and of type java.lang.String..
2. There can only be one such field per class.
3. The tokenized field is applicable only for Notify operations (otherwise the following: IllegalArgumentException: "TokenQuery is only applicable for Notify operations" is thrown).
4. Recovery of tokenized template registrations, in a persistent space after a server failure occurs, is currently not supported.

Example

The example demonstrates a mailing list, as mentioned above. The mailing list has recipients joining for specific groups. Each registration is based on a TokenQuery constructed with a MailMessage Entry and recipients as the tokenized field. By having the groupName and recipients fields set, we can trigger notifications for messages both per group or for a list of recipients.

1. Registering for a Notification:

   MailMessage msg = new MailMessage;()
   msg.setGroup(groupName);
   msg.addRecipients(recipientName);
   TokenQuery template = new TokenQuery(msg, "recipients");
   {{NotifyDelegator}} nDelegator = new {{NotifyDelegator}}(spaceProxy, template, ...);
   

2. Sending a message to the whole group or to a partial list of recipients in that group, involves manipulation of the tokenized field recipients. The defined delimiter character should separate each recipient.

String listOfRecipients = recipient_name1 + DELIMITER + recipient_name2 + ... ; 

MailMessage msg = new MailMessage( from, subject, body  ); 

msg.setGroup(groupName);
msg.addRecipients(listOfRecipients); 

spaceProxy.write(msg, null, 30 * 1000);

com.j_spaces.core.client.EntryArrivedRemoteEvent

The RemoteEvent parameter passed to the notify callback method can be used to retrieve the entry that triggered the notify operation using the EntryArrivedRemoteEvent.getEntry() method.

The EntryArrivedRemoteEvent is the object sent to the RemoteEventListener.notify method.

This class includes the following methods:

com.j_spaces.core.client.NotifyModifiers

The NotifyModifiers class provides the notify types flag constants and helper methods that allow you to identify the event type revived at the notify listener class method.

The Notify Types:

NotifyModifiers helper Methods: