This page describes an older version of the product. The latest stable version is 14.5.

Notify Container

The notify event container uses the space inherited support for notifications (continuous query) using a GigaSpaces unified event session API. If a notification occurs, the data event listener is invoked with the event. A notify event operation is mainly used when simulating Topic semantics.

Life Cycle Events

The notify container life cycle events described below. You may implement each of of these to perform the desired activity.

@EventDriven , @Polling , @Notify can’t be placed on interface classes. You should place these on the implementation class.

The above example registers with the space for write notifications using the provided template (a Data object with its processed flag set to false). If a notification occurs, the SimpleListener is invoked. Registration for notifications is performed on the configured GigaSpace bean. (In this case, if working in a clustered topology, the notification is performed directly on the cluster member.)

Primary/Backup

By default, the notify event container registers for notifications only when the relevant space it is working against is in primary mode. When the space is in backup mode, no registration occurs. If the space moves from backup mode to primary mode, the container registers for notifications, and if it moved to backup mode, the registrations are canceled.

This mostly applies when working with an embedded space directly with a cluster member. When working with a clustered space (performing operations against the whole cluster), the mode of the space is always primary.

Note

Notifications for expired objects (NOTIFY_LEASE_EXPIRATION type) are sent both from the primary and the backup space. To avoid this, you should set the Notify Container replicateNotifyTemplate to false and run the notify container collocated with the space. This will start the Notify Container only with the primary and will avoid duplicated notifications.

Template Definition

When performing receive operations, a template is defined, creating a virtualized subset of data in the space, matching it. GigaSpaces supports templates based on the actual domain model (with null values denoting wildcards), which are shown in the examples. GigaSpaces allows the use of SQLQuery in order to query the space, which can be easily used with the event container as the template. Here is an example of how it can be defined:

A polling container or notify container could have only one template. If you need multiple event handlers you will need to create another polling container or notify container or use the Session Based Messaging API that support multiple listeners with one Session. If you use multiple polling containers make sure the different templates does not overlap each other.

Multiple Event Handlers

It is possible to define multiple event handlers for a notify container. If you have a superclass that has subclasses, and you want to define event handlers for each subclass, you can define the
event template for the superclass and a @SpaceDataEvent for each subclass.

Here is an example where HostInfo, MachineInfo and LdapInfo are subclasses of the MonitorInfo class:

Multiple Values Template

You may use a SQLQuery having IN operator with multiple values to register a Template with multiple values. This can be a simple alternative avoiding using multiple notify containers. See below example:

Free Notify Container Resources

To free the resources used by the notify container make sure you close it properly. A good life cycle event to place the destroy() call would be within the @PreDestroy or DisposableBean.destroy() method.

Transaction Support

The notify container can be configured with transaction support, so the event action can be performed under a transaction. Exceptions thrown by the event listener cause the operations performed within the listener to be rolled back automatically.

Note

When using transactions, only the event listener operations are rolled back. The notifications are not sent again in case of a transaction rollback. In case this behavior is required, please consider using the Polling Event Container.

Masking Notifications

The notify container allows you to mask which operations performed against the space, should cause notifications. By default (if none is defined), notifications are sent for write operations. The operations are:

Operation

Description

write

An entry matching the template has been written to the space.

update

An entry matching the template has been updated in the space.

take

An entry matching the template has been taken from the space.

leaseExpire

An entry matching the template lease has been expired.

unmatched

An entry matching the template no longer matches the template.

all

All the above.

Here is an example of the notify container configured to trigger notifications for both write and update operations:

The UNMATCHED NotifyActionType

The UNMATCHEDNotifyActionType should be used when you would like to receive notifications for objects which got their value been updated where the object that was initially matches the template no longer matches the template.
Example:
You would like to maintain within the client side a list for all the objects which got their status as true. You register for notifications using a template which had the status field as true.

An object with status as true is written into the space. This triggers a notification about the existence of this object. In some point the object is read from the space, the status field value changed from true to false and the object is written back into the space with its updated data.

Registering a notification using a template which got status=true with the NOTIFY_UPDATENotifyActionType without using the UNMATCHED NotifyActionType as well, will not trigger a notification when the status field value changed from true to false.

You have to include the UNMATCHED NotifyActionType to receive a notification when the object changing status=true to status=false.

Scaling Notification Delivery

To increase the number of space threads that are dealing with notification delivery you should increase the space-config.engine.notify_max_threads space property. Its default is 128 threads.
Here is an example how you can configure the minimum and the maximum of the thread pool responsible for notification delivery:

Note that you can always delegate the notification processing to a separate application defined thread pool, if you’d like to manage the processing thread pool yourself. This can be done by configuring a separate thread pool within your application, for example using Spring’s TaskExecutor abstraction.
In your pu.xml file you can define a ThreadPoolTaskExecutor as follows:

Batch Events

OpenSpaces, through the Session Based Messaging API, allows batching of notifications. Batching causes the space to accumulate the notifications at the space side for the specified operation(s) with objects that match the template/SQL criteria. Once a certain amount of time has been elapsed or a certain amount of objects have been accumulated, the events are sent to the client.

Batching is very useful when working with a remote space, since it reduces the network roundtrip operations. The downside of this approach is a potential delay when events are delivered to the client.

Below is an example how batch notification should be configured. With this example the eventListener method will be called having one event passed as an argument each time (since the pass-array-as-is is not enabled) once there were 10 matching objects accumulated within the space or every 5000 millisecond since the last time a batch was sent to the client. In this case (notification delivery based on elapsed time), there might be less than 10 objects that will be sent to the client.

Tip

Make sure you set a reasonable batch size to avoid overloading the listener with a large burst of events to process. A value under 100 will be acceptable for most cases.

Pass Array as is

When batching is enabled an array of Entries is received from the notification. By default, the notify container serializes the execution of the array into invocation of the event listener for each element in the array. If you want the event to operate on the whole array (receive the array as a parameter), the pass-array-as-is configuration attribute should be set to true.

Note

Listener argument has to be defined as Object[] when using passArrayAsIs and converted to appropriate class as part of the listener code.

For the above example when using passArrayAsIs equivalent listener code will be,

FIFO Events

By default the notify event container running on non-FIFO mode. This means the event listener will be called simultaneously by multiple threads in case there are concurrent notifications sent from the space. To have a sequential event listener calls, you should run the notify event container in a FIFO mode.

For full FIFO support, the actual template also has to be marked as FIFO. For more details, refer to the Space FIFO support section.

Here is an example of how FIFO events can be configured with the notify container:

Re-Register after complete space shutdown and restart

The Notify Container can recover from partial disconnections (e.g failover) automatically, but if the entire cluster is shut down and restarted, the event registrations are lost and the notify container needs to be restarted.

To get a notification about such disconnections, the Auto Renew feature needs to be enabled, and the container needs to implement a LeaseListener and register if to be triggered when the container becomes disconnected. For example:

To make sure the client application will manage to reconnect automatically to the space cluster once it was restarted you may want to change the default configuration. See the Proxy Connectivity for details.

Resending Notifications after a Space-Client Disconnection

When a network failure occurs and the space can’t communicate with the client, the space attempts to trigger the remote client listener several times. The space-config.notifier-retries property controls the re-try attempts. The default is 3 attempts.

Durable Notifications

Due to the asynchronous nature of notification delivery, when a primary space fails right after replicating an operation to the backup space and before sending the notification to the registered client, the backup space might not be able to send the missing notifications, since it is in the process of moving to active mode.
This means that during this very short period of time, the registered client might not receive events that occurred in the primary space and were replicated to the backup space.

Durable notifications allows configuring the notify container to withstand failover and short network disconnections with no notifications lost.

Durable notifications are based on the replication mechanism and as such have some different semantics regarding other notify container configuration parameters.
For further details see Durable Notifications.

Important

Durable Notification does not support an embedded Space, it can only be used with a remote proxy. The alternative is to use a Polling Container using SingleReadReceiveOperationHandler.

Take on Notify

The notify event container can be configured to automatically perform a take on the notification data event. It can also be further configured to filter out events if the take operation returned null. (This usually happens when several clients receive this event, and only one succeeds with the take.)

Note

Pojo properties should implement hashcode and equals methods for matching to succeed.(avoid using take on notify when one of the object fields is a primitive array)

GigaSpaces extends this interface by providing the EntryArrivedRemoteEvent, which holds additional information regarding the event that occurred. The notify container, by default, uses the EntryArrivedRemoteEvent in order to extract the actual data event represented by the event, and passes it as the first parameter. If access to the EntryArrivedRemoteEvent is still needed, it is passed as the last parameter to the space data event listener. Here is an example of how it can be used:

When using the different listener adapters, such as the annotation adapter, it can be accessed in the following manner (since adapters use reflection, there is no need to cast to EntryArrivedRemoteEvent):

Default Values of Notify Container Configuration Parameters

The default values for all of the notify container configuration parameters, such as perform-take-on-notify, ignore-event-on-null-take and others can be found in the JavaDoc (and sources) of the class SimpleNotifyEventListenerContainer and its super class, namely AbstractNotifyEventListenerContainer.
For example, perform-take-on-notify default value is documented in the method SimpleNotifyEventListenerContainer.setPerformTakeOnNotify(boolean).