Java SDK

The cloud notification service enables server-side applications to send interactive notifications with support for hierarchical organizational structures, flexible targeting options, and cross-platform delivery. The service communicates with your server-side applications via the TypeScript SDK or the Java SDK.

For an overview, see HERE cloud notification service overview

Initialization

Initialize the CloudNotificationAPI with your service configuration to begin working with notifications.

import com.openfin.*;

// Create API settings
CloudNotificationSettings settings = new CloudNotificationSettings(
    "https://<env>/notifications"
);

// Initialize the API
CloudNotificationAPI notificationApi = new CloudNotificationAPI(settings);

Authentication and connection

Establish a connection to the notification service using either basic authentication or JWT tokens.

Basic authentication

// Configure basic authentication
ConnectParameters.BasicAuthenticationParameters basicAuth = 
    new ConnectParameters.BasicAuthenticationParameters(
        USERNAME,
        PASSWORD
    );

ConnectParameters connectParams = new ConnectParameters(
    PLATFORM,
    SOURCE_ID, 
    basicAuth
);

// Connect to the service
notificationApi.connect(connectParams);

JWT authentication

// Configure JWT authentication
ConnectParameters.JwtAuthenticationParameters jwtAuth = 
    new ConnectParameters.JwtAuthenticationParameters(
        () -> JWT_TOKEN,  // Token supplier
        AUTHENTICATION_ID
    );

ConnectParameters connectParams = new ConnectParameters(
    PLATFORM,
    SOURCE_ID,
    jwtAuth
);

// Connect to the service
notificationApi.connect(connectParams);

Event listeners

Register listeners to handle incoming notifications, events, and connection status changes.

Notification listener

notificationApi.onNotification(new NotificationListener() {
    @Override
    public void onNotification(Notification notification) {
        System.out.println("Notification received:");
        System.out.println("ID: " + notification.notificationId);
        System.out.println("Correlation ID: " + notification.correlationId);
        System.out.println("Target: " + notification.target);
        System.out.println("Target Type: " + notification.targetType);
        System.out.println("Action: " + notification.action);
        System.out.println("Payload: " + notification.payload);
    }
});

Notification event listener

notificationApi.onNotificationEvent(new NotificationEventListener() {
    @Override
    public void onNotificationEvent(NotificationEvent event) {
        System.out.println("Notification event received:");
        System.out.println("Notification ID: " + event.notificationId);
        System.out.println("Event Type: " + event.type);
        System.out.println("Category: " + event.category);
        System.out.println("User ID: " + event.userId);
        System.out.println("User Name: " + event.userName);
        System.out.println("Payload: " + event.payload);
    }
});

Disconnection listener

// Disconnection listener
notificationApi.onDisconnected(new DisconnectedListener() {
    @Override
    public void onDisconnected() {
        System.out.println("Disconnected from notification service");
    }
});

Publishing notifications

Send notifications to specific users and groups with customizable payloads and delivery options.

info

Notification payloads in the cloud service are structured in the same way as notification objects in notification center.

Basic notification

info

The correlation Id is an optional, user-defined ID that correlates a notification with the users' custom data.

// Define notification targets
String[] groups = {GROUP_MEMBER, GROUP_MEMBER};
String[] users = {USER_EMAIL};
NotificationTargets targets = new NotificationTargets(groups, users);

// Create notification options
NotificationOptions options = new NotificationOptions(
    CORRELATION_ID,
    targets
);

// Define the payload
Map<String, Object> payload = new HashMap<>();
payload.put("template", TEMPLATE_TYPE);
payload.put("title", TITLE);
payload.put("body", BODY_TEXT);
payload.put("category", CATEGORY_TYPE);
payload.put("icon", ICON_FILE_PATH);

// Publish the notification
String notificationId = notificationApi.raiseNotification(options, payload);
System.out.println("Notification published with ID: " + notificationId);

Notification with TTL

// Create notification options with 300 second TTL
NotificationOptions options = new NotificationOptions(
    CORRELATION_ID,
    targets,
    300  // TTL in seconds
);

String notificationId = notificationApi.raiseNotification(options, payload);

Updating notifications

Modify the content of existing notifications that have already been published.

// Update notification payload
Map<String, Object> updatedPayload = new HashMap<>();
updatedPayload.put("template", TEMPLATE_TYPE);
updatedPayload.put("title", TITLE);
updatedPayload.put("body", BODY_TEXT);

// Create update options
NotificationUpdateOptions updateOptions = new NotificationUpdateOptions();

// Update the notification
notificationApi.updateNotification(
    notificationId,
    updateOptions, 
    updatedPayload
);

Deleting notifications

Remove notifications from the system, triggering delete events for all recipients.

// Delete a notification
notificationApi.deleteNotification(notificationId);

Group hierarchies and targeting

Target notifications using hierarchical group structures for efficient and flexible notification distribution.

The service supports hierarchical group targeting. For example, given this group structure:

• Targeting London sends to direct London group members only
• Targeting Scotland sends to Scotland, Edinburgh, and Glasgow members
• Targeting UK sends to all members in the hierarchy

info

In the case of duplication, all members receive only one notification.

// Target specific hierarchy level
String[] groups = {"Scotland"};  // Reaches Scotland, Edinburgh, Glasgow
NotificationTargets targets = new NotificationTargets(groups, null);

Notification events

Post custom events related to existing notifications to provide additional context or user interaction data.

// Create event options with targets
NotificationEventOptions eventOptions = new NotificationEventOptions(targets);

// Post a notification event
notificationApi.postNotificationEvent(
    notificationId,
    FORM_VALUES_CHANGED,
    USER_INTERACTION,
    eventPayload,
    eventOptions
);

Removing notifications from notification center

Remove notifications from specific users' or groups' notification centers without deleting the notification entirely:

// Remove notification from specific user groups
String[] removalGroups = {"london"};
NotificationTargets removalTargets = new NotificationTargets(removalGroups, null);

notificationApi.removeFromNotificationCenter(notificationId, removalTargets);

Complete example

A comprehensive example demonstrating connection, event handling, and notification publishing in a single application.

import com.openfin.*;
import java.util.HashMap;
import java.util.Map;

public class NotificationExample {
    public static void main(String[] args) {
        try {
            // Initialize the API
            CloudNotificationSettings settings = new CloudNotificationSettings(
                "https://<env>/notifications"
            );
            CloudNotificationAPI api = new CloudNotificationAPI(settings);
            
            // Configure authentication
            ConnectParameters.BasicAuthenticationParameters auth = 
                new ConnectParameters.BasicAuthenticationParameters(
                    System.getenv("NOTIFICATION_USERNAME"),
                    System.getenv("NOTIFICATION_PASSWORD")
                );
            
            ConnectParameters connectParams = new ConnectParameters(
                PLATFORM,
                SOURCE_ID,
                auth
            );

            // Connect to the service
            api.connect(connectParams);
            
            // Set up event listeners
            api.onNotification(notification -> {
                System.out.println("Received notification: " + 
                    notification.notificationId);
            });
            
            api.onDisconnected(() -> {
                System.out.println("Disconnected from notification service");
            });
            
            // Define notification targets and payload
            String[] groups = {"london"};
            NotificationTargets targets = new NotificationTargets(groups, null);
            NotificationOptions options = new NotificationOptions(
                CORRELATION_ID,
                targets
            );
            
            Map<String, Object> payload = new HashMap<>();
            payload.put("template", TEMPLATE_TYPE);
            payload.put("title", TITLE);
            payload.put("body", BODY_TEXT);
            payload.put("category", CATEGORY);
            
            // Send the notification
            String notificationId = api.raiseNotification(options, payload);
            System.out.println("Notification sent: " + notificationId);
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Configuration options

Configure the CloudNotificationSettings with various settings to control connection behavior and retry logic.

// Basic configuration
CloudNotificationSettings settings = new CloudNotificationSettings(
    HTTPS_HOST
);

// With reconnection settings
CloudNotificationSettings settings = new CloudNotificationSettings(
    HTTPS_HOST,
    30,  // keep-alive interval (seconds)
    5    // reconnect retry limit
);

// With just retry limit
CloudNotificationSettings settings = new CloudNotificationSettings(
    HTTPS_HOST,
    5    // reconnect retry limit
);