com.highdeal.notification
Class NotificationServiceClient

java.lang.Object
  com.highdeal.notification.NotificationServiceClient

All Implemented Interfaces:

com.highdeal.barbus.ISSLContextProvider

public class NotificationServiceClient
extends java.lang.Object
implements com.highdeal.barbus.ISSLContextProvider

This Java class implements the notification service client that you must instantiate to be able to handle asychronous notifications in your client application; Your notification client is informed when asynchronous notifications are sent by the connected SAP CC system via the Message TCP/IP technical interface.

To process the received notifications, you must implement your own NotificationHandler class and the assign it to your notification client (see the method setNotificationHandler(..)).

Note

Consult the SAP CC Notification Reference for an overview of the notifications sent by the SAP CC system.

Features

This notification client benefits from the functions provided by the Message TCP/IP technical interface.

Refer to its main features about:

• High Availability Management
• High Volume Management
• High Performance Management

Implementation in Your Client Application

Initializing and Connecting

You initialize your notification client with a list of instance information objects describing the notification service servers to be connected to.

Invoking the methods connect(..), the client opens the connection with all the servers and becomes able to receive notifications.

Customizing Sequence

Perform the following steps to develop your program:

• Design and implement a customized NotificationHandler class according to your business requirements
• Instantiate your own NotificationHandler
• Instantiate an instance map with the searchInstanceMap(..) inherited method
• Instantiate a NotificationServiceClient object
• Initialize this notification client with the setNotificationHandler() method
• Prepare the connection to the distant SAP CC system with the addAllConnections(..) methods
• Connect the notification client to the SAP CC system to receive and process the asynchronous notifications

Example

This notification client must be initialized via establishing a connection to one of more dispatcher instances available in the distant SAP CC system. Once at least one dispatcher of the SAP CC system is connected from your client application, the client application retrieves automatically the list of all available dispatcher instances on the server system side. It establishes a connection with every one of them automatically. Here is an example:

     NotificationHandler notifHandler = ...
     InstanceMap map = NotificationServiceClient.searchInstanceMap(serverUrl, login, password);
     client = new NotificationServiceClient();
     client.setNotificationHandler(notifHandler);
     client.addAllConnections(map);
     client.connect(null, 10000);
 

Notes on SAP CC Implementation

Communication Error Handling

If a connection with a dispatcher instance of the SAP CC system is lost because this server instance is stopped or crashed, the reconnection process is activated to retry to open the connection between this notification client and the lost instance and this during all its life.

See Also:

NotificationHandler, Notification

Field Summary

static int

NO_TIMEOUT Constant describing no timeout (see the method connect(String, int)); It is '-1'.

Constructor Summary

NotificationServiceClient()
Initializes an empty NotificationServiceClient with default name: NotificationServiceClient.

NotificationServiceClient(java.lang.String name)
Initializes an empty NotificationServiceClient with a name; The name of this client is used to prefix the name of the created thread.

Method Summary

int	addAllConnections(InstanceMap currentMap) Registers all the dispatcher instances included in the specified instance map as system instance to be connected to.
void	addConnection(InstanceInfo info) Registers the specified instance as instance to be connected with; The instance must have a notification service port defined and must not be a guider instance.
void	clearConnections() Clears the instance list.
void	close() Closes this client shutting down all the connections with the dispatcher instances of the SAP CC system; Having invoking this method the method connect(String, int) can be invoked again.
void	connect() Connects this client with all the already declared instances; The address of this client is a choosen local address and the connection has no timeout.
void	connect(java.lang.String bindAddress, int timeout) Connects this client with all the already declared instances; The thread invoking this method is made free as soon as this client is connected.
java.lang.String	getName() Returns the name of this client
javax.net.ssl.SSLContext	getSslContext() Returns the SSL context used with secure connections.
boolean	isConnected() Returns true if this client is connected to the instance, false otherwise.
static InstanceMap	searchInstanceMap(java.lang.String bootHostName, int bootPort, BootMode bootMode) Deprecated. Deprecated since version 2.0 of SAP CC and replaced by the method searchInstanceMap(java.lang.String, java.lang.String, java.lang.String)
static InstanceMap	searchInstanceMap(java.lang.String serverUrl, java.lang.String login, java.lang.String password) Gets the current instance map from the specified dispatcher instance of the SAP CC system; The following protocols are accepted: http, https, tcp, and tcps.
void	setNotificationHandler(NotificationHandler handler) Sets the notification handler responsible for processing the notification.
void	setSslContext(javax.net.ssl.SSLContext sslContext) Sets the SSL context used with secure connections.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_TIMEOUT

public static final int NO_TIMEOUT

Constant describing no timeout (see the method connect(String, int)); It is '-1'.

See Also:

Constant Field Values

Constructor Detail

NotificationServiceClient

public NotificationServiceClient()

Initializes an empty NotificationServiceClient with default name: NotificationServiceClient.

NotificationServiceClient

public NotificationServiceClient(java.lang.String name)

Initializes an empty NotificationServiceClient with a name; The name of this client is used to prefix the name of the created thread.

Parameters:

name - The name of this client; If null, default name is NotificationServiceClient.

Method Detail

getSslContext

public javax.net.ssl.SSLContext getSslContext()

Returns the SSL context used with secure connections.

Specified by:

getSslContext in interface com.highdeal.barbus.ISSLContextProvider

Returns:

The SSL context used with secure connections

setSslContext

public void setSslContext(javax.net.ssl.SSLContext sslContext)

Sets the SSL context used with secure connections.

Parameters:

sslContext - The SSL context used with secure connections

searchInstanceMap

@Deprecated
public static InstanceMap searchInstanceMap(java.lang.String bootHostName,
                                                       int bootPort,
                                                       BootMode bootMode)
                                     throws java.io.IOException

Deprecated. Deprecated since version 2.0 of SAP CC and replaced by the method searchInstanceMap(java.lang.String, java.lang.String, java.lang.String)

Gets the current instance map from the specified instance of the SAP CC system.

Parameters:

bootHostName - The name of the host where the boot instance is running.

bootPort - The port of the host on which the boot instance is listening. Must be in range [1, 65535]. This port need to be a MESSAGE port as the BootMode.HTTP_BOOT_MODE and BootMode.HTTPS_BOOT_MODE are deprecated.

bootMode - The protocol type used to retrieve the instance map. null means MESSAGE_BOOT_MODE. BootMode.HTTP_BOOT_MODE and BootMode.HTTPS_BOOT_MODE are deprecated. Even if they are used, the method will use MESSAGE_BOOT_MODE.

Returns:

The current instance map

Throws:

java.io.IOException - if the boot instance cannot be connected.

java.lang.IllegalArgumentException - if bootHostName is null or if bootPort is out of range.

searchInstanceMap

public static InstanceMap searchInstanceMap(java.lang.String serverUrl,
                                            java.lang.String login,
                                            java.lang.String password)
                                     throws java.io.IOException

Gets the current instance map from the specified dispatcher instance of the SAP CC system; The following protocols are accepted: http, https, tcp, and tcps.

Parameters:

serverUrl - The URL of the server to contact to retrieve the instance map

login - The name of the SAP CC user to use to retrieve the instance map, optional for non HTTP connections

password - The password of the SAP CC user to use to retrieve the instance map, optional for non HTTP connections

Returns:

The current instance map

Throws:

java.io.IOException - if the dispatcher instance cannot be connected to.

getName

public java.lang.String getName()

Returns the name of this client

Returns:

The name specified in the constructor NotificationServiceClient(String)

isConnected

public boolean isConnected()

Returns true if this client is connected to the instance, false otherwise.

Returns:

true if connected, false otherwise

setNotificationHandler

public void setNotificationHandler(NotificationHandler handler)

Sets the notification handler responsible for processing the notification.

Recommendation

SAP strongly recommends to release the calling thread as soon as possible in the NotificationHandler since it may be the thread responsible for reading the notifications from the network. If you execute a long process with this thread, some notifications could be refused by this client.

Parameters:

handler - The notification handler (if not set, the notifications are lost)

addAllConnections

public int addAllConnections(InstanceMap currentMap)

Registers all the dispatcher instances included in the specified instance map as system instance to be connected to.

Parameters:

currentMap - The current instance map retrieved from a running dispatcher instance of the distant SAP CC system; Can be null.

Returns:

The available dispatcher instance count or zero if currentMap is null; The client will connect to all these instances.

Throws:

java.lang.IllegalStateException - If this client is already connected

addConnection

public void addConnection(InstanceInfo info)

Registers the specified instance as instance to be connected with; The instance must have a notification service port defined and must not be a guider instance.

Parameters:

info - The instance info of the instance to be added

Throws:

java.lang.IllegalStateException - if this client is already connected

clearConnections

public void clearConnections()

Clears the instance list.

Throws:

java.lang.IllegalStateException - if this client is already connected

connect

public void connect()
             throws java.io.IOException

Connects this client with all the already declared instances; The address of this client is a choosen local address and the connection has no timeout.

Throws:

java.io.IOException - if this client cannot be connected to the network

java.lang.IllegalStateException - if this client is already connected or if no instance is declared

connect

public void connect(java.lang.String bindAddress,
                    int timeout)
             throws java.io.IOException

Connects this client with all the already declared instances; The thread invoking this method is made free as soon as this client is connected.

Parameters:

bindAddress - The local address of this client. If not set, a local address is choosen

timeout - The timeout for this connect; A negative value means no timeout.

Throws:

java.io.IOException - if this client cannot be connected to the network

java.lang.IllegalStateException - if this client is already connected or if no instance is declared

close

public void close()

Closes this client shutting down all the connections with the dispatcher instances of the SAP CC system; Having invoking this method the method connect(String, int) can be invoked again.

Throws:

java.lang.IllegalArgumentException - If this client is already connected