Notification System

This page will introduce you to the NotificationSystem that is bundled with the Core

The NotificationSystem allows you to send data (serialized to Strings) from one "Core instance" to another. Please keep in mind that a Core Instance is running on every Velocity and Paper server and on the Master. So it is possible to send notifications from each of them to specific or all others.

What is a Notification?

A Notification is designed to be easily used without a deep dive into Hazelcast. It should be used for the simple transfer of data or distribution of information, updated via "pushes" and not stored to be queried. If you want to distribute data that can be requested and updated by the cores, then please use the HazelDataAPI (example below)

Map<String,String> name_of_your_distributed_map 
                  = API.get().getHazelDataApi().getMap("name_of_your_distributed_map");

It is also possible to set custom Types for Key and Value, but then you need to make sure that they can be serialized and deserialized by Hazelcast. For further information about this, please check out the Hazelcast Serialization Documentation

So the Notification is used if you need to send stuff like a "push notification". It is only possible to receive a notification when your core is ready to receive them and actively listening for them (this is normally done fully automatically as long as the core is connected and running)

Structure of a Notification:

The Notification consists of four components:

1. Notification Header: "Name" or "Identifier" for your notification
2. Notification Message: The Content (String) of your notification
3. The Member who sent it
4. The time (milliseconds), the notification was sent

Important: 3 and 4 are not accessible via the NotificationAPI and need to be accessed via Hazelcast´s internal "Message / Topic System" - In normal operation, you will not need this information (and if you do, you can include them in your "message")!!!

Send a notification

There are exactly four methods that can be used to send a notification. The first distinction you need to make is, if you want to address selected UUIDs (These can be acquired by the ClusterAPI) or if you want to send them to all cores (broadcast). In the following I will show two examples to show you hands-on, how to send a notification:

Broadcast:

API.get().getNotificationApi().getNotificationSender().broadcastNotification("your_header", "your_message");

Send to selected UUIDs (cores):

API.get().getNotificationApi().getNotificationSender().sendNotification("your_header","your_message", uuids);

You could also implement the SimpleNotification interface and "reuse" it. That could look like this:

Own SimpleNotification (Broadcast)

SimpleNotification notification = new MyOwnCustomNotification();
API.get().getNotificationApi().getNotificationSender().broadcastNotification(notification);

or like this:

Own SimpleNotification:

SimpleNotification notification = new MyOwnCustomNotification();
API.get().getNotificationApi().getNotificationSender().sendNotification(notification,uuids);

Receive notifications

The core handles the "receiving" of the notifications fully automatically, the only thing you need to do, is to tell the core that you want to listen to incoming notifications. For this, you need to provide a NotificationListener. This can be done by implementing it, creating an anonymous class, or using a Lambda. Here I will show two examples (with Anonymous class and with Lambda) that simply print the message using a pre-defined Logger:

Anonymous class:

        API.get().getNotificationApi().registerListener(new NotificationListener() {
            @Override
            public void onNotification(Notification notification) {
                if(notification.header().equals("print_message")) {
                    logger.info("New notification: " + notification.message());
                }
            }
        });

Lambda:

        API.get().getNotificationApi().registerListener(notification1 -> {
            if(notification1.header().equals("print_message"))
                logger.info("New notification: " + notification1.message());
        });

In both of these examples, I check if the header matches my desired header "print_message", to avoid printing every notification that comes in.

If you should have any questions, then think about sending me an email