07 March 2024

Notify Container

The notify event container implements the IEventListenerContainer interface, and uses the space inheritance support for notifications, using a GigaSpaces data event session API. If a notification occurs, the DataEventArrived event is invoked with the event. A notify event operation is mainly used when simulating Topic semantics.

The examples in this page follow a certain pattern – each code example has two tabs: Using EventListenerContainerFactory and NotifyEventListenerContainer Code Construction.

The first tab demonstrates how to create and configure a notify container using the EventListenerContainerFactory, and the second tab demonstrates how to build and configure a NotifyEventListenerContainer with a constructor and setting the different properties.

The following is a simple example of notify event container construction:

[NotifyEventDriven]
public class SimpleListener
{
    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

Constructing the notify container that uses the SimpleListener class as the event listener, and starting it.

ISpaceProxy spaceProxy = // either create the SpaceProxy or obtain a reference to it
IEventListenerContainer<Data> eventListenerContainer = EventListenerContainerFactory.CreateContainer<Data>(spaceProxy, new SimpleListener());

eventListenerContainer.Start();

// when needed dispose of the container
eventListenerContainer.Dispose()

ISpaceProxy spaceProxy = // either create the SpaceProxy or obtain a reference to it

NotifyEventListenerContainer<Data> notifyEventListenerContainer = new NotifyEventListenerContainer<Data>(spaceProxy);

notifyEventListenerContainer.Template = new Data(false);
notifyEventListenerContainer.DataEventArrived += new DelegateDataEventArrivedAdapter<Data,Data>(ProcessData).WriteBackDataEventHandler;

// when needed dispose of the container
notifyEventListenerContainer.Dispose();

Event processing method

public Data ProcessData(IEventListenerContainer<Data> sender, DataEventArgs<Data> e)
{
    Data data = e.Data;
    //process Data here and return processed data
}

DelegateDataEventArrivedAdapter is a class that adapts the supplied user method to the DataEventHandler delegate, and contains a built in logic of writing back event results to the space.

The above example registers with the Space for write notifications using the provided template, which can be any .NET object (in this case, 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 supplied Space proxy.

Primary/Backup

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.

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. The following is an example of how it can be defined:

[NotifyEventDriven]
public class SimpleListener
{
    [EventTemplate]
    public SqlQuery<Data> UnprocessedData
    {
        get
        {
            SqlQuery<Data> templateQuery = new SqlQuery<Data>(template, "Processed = ?");
            templateQuery.SetParameter(1, false);

            return templateQuery;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

SqlQuery query = new SqlQuery<Data>("Processed = ?");
query.SetParameter (1, false);
notifyEventListenerContainer.Template = query;

Masking Notifications

The notify container allows you to mask which operations should cause notifications when performed against the Space. By default (if none is defined), notifications are sent for write operations. The operations are 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), lease expiration (an entry matching the template lease has been expired), and all. The following is an example of the notify container configured to trigger notifications for both write and update operations:

[NotifyEventDriven(NotifyType = DataEventType.Write | DataEventType.Update)]
public class SimpleListener
{
    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

notifyEventListenerContainer.NotifyType = DataEventType.Write | DataEventType.Update;

Batch Events

The notify container, through the unified event API, allows batching of notifications. Batching causes the Space to accumulate the notifications, and when a certain amount of time has passed or a certain size is reached, causes the events to be raised to the client. Batching is very useful when working with a remote Space, since it reduces the network round-trip operations. Moreover, when using Batch notification, it is possible (but not mandatory) to work with the BatchDataEventArrived instead, and handle a batch of notifications at once.

The following is an example of batching, where if the number of notifications has passed 10, or the time passed is 5 seconds (since the last batch was sent), a batch of notifications is sent to the client:

[NotifyEventDriven]
public class SimpleListener
{
    [EventSessionConfig]
    public EventSessionConfig BatchConfig
    {
        get
        {
            EventSessionConfig sessionConfig = new EventSessionConfig();
            sessionConfig.Batch = true;
            sessionConfig.BatchSize = 10;
            sessionConfig.BatchTime = 5000;
            return config;
        }
    }

    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data[] ProcessData(Data[] event)
    {
        //process batch Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

EventSessionConfig sessionConfig = new EventSessionConfig();
sessionConfig.Batch = true;
sessionConfig.BatchSize = 10;
sessionConfig.BatchTime = 5000;
notifyEventListenerContainer.EventSessionConfig = sessionConfig;
notifyEventListenerContainer.BatchDataEventArrived += new DelegateDataEventArrivedAdapter<Data,Data[]>(ProcessData).WriteBackBatchDataEventHandler;

FIFO Events

The notify event container can register for events or notifications, and have the events delivered in a FIFO order.

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

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

[NotifyEventDriven]
public class SimpleListener
{
    [EventSessionConfig]
    public EventSessionConfig FifoConfig
    {
        get
        {
            EventSessionConfig sessionConfig = new EventSessionConfig();
            sessionConfig.Fifo = true;
            return config;
        }
    }

    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

EventSessionConfig sessionConfig = new EventSessionConfig();
sessionConfig.Fifo = true;
notifyEventListenerContainer.EventSessionConfig = sessionConfig;

Durable Notifications

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

The following is an example of how Durable Notifications can be configured with the notify container:

[NotifyEventDriven]
public class SimpleListener
{
    [EventSessionConfig]
    public EventSessionConfig DurableNotificationConfig
    {
        get
        {
            EventSessionConfig sessionConfig = new EventSessionConfig();
            sessionConfig.DurableNotifications = true;
            return config;
        }
    }

    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

EventSessionConfig sessionConfig = new EventSessionConfig();
sessionConfig.DurableNotifications = true;
notifyEventListenerContainer.EventSessionConfig = sessionConfig;

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 returns null. (This usually happens when several clients receive this event, and only one succeeds with the take.)

The notify container can be configured as follows:

[NotifyEventDriven(PerformTakeOnNotify = true, IgnoreEventOnNullTake = true)]
public class SimpleListener
{
    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

notifyEventListenerContainer.PerformTakeOnNotify = true;
notifyEventListenerContainer.IgnoreEventOnNullTake = true;

Space Data Event Args

The notify container uses the GigaSpaces data event session API under the hood. When a notification is triggered, it contains SpaceDataEventArgs, which holds more information about the notification itself, such as the template and the DataEventType (for example, whether this notification was triggered by a write or an update operation). When using the notify container, it is possible to receive that additional information as a parameter of the event listener method:

[NotifyEventDriven]
public class SimpleListener
{
    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event, ISpaceProxy proxy, ITransaction tx, SpaceDataEventArgs<object> e)
    {
        DataEventType eventType = e.EventType;
        //process Data here and return processed data
    }
}

ISpaceProxy spaceProxy = // either create the SpaceProxy or obtain a reference to it

NotifyEventListenerContainer<Data> notifyEventListenerContainer = new NotifyEventListenerContainer<Data>(spaceProxy);

notifyEventListenerContainer.Template = new Data(false);
notifyEventListenerContainer.DataEventArrived += new DelegateDataEventArrivedAdapter<Data,Data>(ProcessData).WriteBackDataEventHandler;

// when needed dispose of the container
notifyEventListenerContainer.Dispose();

Event processing method

public Data ProcessData(IEventListenerContainer sender, DataEventArgs<Data> e)
{
    SpaceDataEventArgs eventArgs = (SpaceDataEventArgs)e.CustomEventArgs;
    Data data = e.Data;
    //process Data here and return processed data
}

DelegateDataEventArrivedAdapter is a class that adapts the supplied user method to the DataEventHandler delegate, and contains a built-in logic of writing event results back to the Space.

Queued Event Handling

When a notification is received, it occurs asynchronously in a separate thread. That thread is part of the Space proxy resource pool that is in charge of receiving and executing notifications code. As a result, special care should be taken when the event listening method execution is not very short, because it could hold the proxy resource for too long and eventually exhaust it, which causes notifications to get lost. If the event listening method needs to execute code that takes some time, it is recommended to use the QueuedEventHandling feature.

When this feature is enabled, each event that is received is put into a queue, and the notifying thread is released immediately. The queue is processed by a different thread or threads. Doing this keeps the proxy resource pool free. The number of threads that are processing the events together, can be determined using the QueuedEventHandlersPoolSize property. The queue size limit is configured using the QueuedEventsSizeLimitProperty. When the limit is reached, the notify thread blocks until it can insert the event into the queue. This is done in order to avoid the client running out of memory when it process events too slowly, and the queue keeps accumulating.

The notify container can be configured as follows:

[NotifyEventDriven(QueuedEventHandling = true, QueuedEventHandlersPoolSize = 3)]
public class SimpleListener
{
    [EventTemplate]
    public Data UnprocessedData
    {
        get
        {
            Data template = new Data();
            template.Processed = false;
            return template;
        }
    }

    [DataEventHandler]
    public Data ProcessData(Data event)
    {
        //process Data here and return processed data
    }
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

notifyEventListenerContainer.QueuedEventHandling = true;
notifyEventListenerContainer.QueuedEventHandlersPoolSize = 3;

Sometimes, it is convenient to have a listener instance per concurrent queue processing thread. This allows a thread-safe instance variable to be constructed without worrying about concurrent access. In this case, the event listener containing class should implement System.ICloneable, and the CloneEventListenersPerThread property should be set to true. The following is an example:

[NotifyEventDriven(QueuedEventHandling = true, QueuedEventHandlersPoolSize = 3, CloneEventListenersPerThread = true]
public class SimpleListener : ICloneable
{
 ...
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

notifyEventListenerContainer.QueuedEventHandling = true;
notifyEventListenerContainer.QueuedEventHandlersPoolSize = 3;
notifyEventListenerContainer.CloneEventListenersPerThread = true;

Handling Exceptions

During the life-cycle of the polling container, two types of exceptions might be thrown:

User Exception
Container Exception

A User Exception is an exception that occurs during the invocation of the user event listener. A Container Exception is an exception that occurs anywhere else during the life-cycle of the container (for example, during the receive or trigger operation handler).

Subscribing to the ContainerExceptionOccurred Event

It is possible to be notified when a container exception occurs by subscribing to the ContainerExceptionOccurred event, and getting a reference to the exception.

The following is an example of how to subscribe to this event:

[NotifyEventDriven]
public class SimpleListener
{
    [ContainerException]
    public void ExceptionHandler(IEventListenerContainer<Data> sender, ContainerExceptionEventArgs e)
    {
         Console.WriteLine("Container Name: " + ((IEventListenerContainer<Data>)sender).Name);
         Console.WriteLine(e.Exception.Message);
    }

    ...
}

NotifyEventListenerContainer<Data> notifyEventListenerContainer = // create or obtain a reference to a notify container

notifyEventListenerContainer.ContainerExceptionOccured += ExceptionHandler;

public void ExceptionHandler(object sender, ContainerExceptionEventArgs e)
{
     Console.WriteLine("Container Name: " + ((IEventListenerContainer<Data>)sender).Name);
     Console.WriteLine(e.Exception.Message);
}

Subscribing to the UserExceptionOccured Event

It is possible to be notified when a user exception occurs by subscribing to the UserExceptionOccurred event. This arguments of this event contain the entire DataEventArgs of the original DataEventArrived. By default, any event that is thrown inside the event listener scope results in transaction rollback if the container is set to be transactional. This can be overridden if the user exception handler sets the event state to "ignored".