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.

Security

To implement a ciphered connection between the client and SAP CC, use setSslContext(javax.net.ssl.SSLContext )

Since SAP CC 4.1 SP2, SAP CC is able to require an authenticated connection from a client application (see the MESSAGE_API_AUTHENTICATION_REQUIRED parameter in the parameter reference guide). The client must setup some valid user credentials by calling the setUserCredentials() method. Then, the client application will be authenticated and authorized to connect to the SAP CC server by calling one of the following connect() methods:

• connect(String, int )

Code Snippet

The following code snippet provides an example of how to authenticate a client application to the SAP CC server :

    private static final String DISPATCHER_HOST = "localhost";
    private static final int DISPATCHER_EXT_PORT = 2000;

    // Initialize the notification service client by (always) calling the empty builder (other builders are deprecated)
    NotificationServiceClient client = new NotificationServiceClient();

    // Set the user credentials for the new created client
    // These credentials must refer to an existing service user in SAP CC having the "messageChargingClient" role.
    client.setUserCredentials("clientX", "foopasswd");

    //Call one of the connect() methods provided in Service Client classes according to the
    //  willing behavior.
    ConnectionStatus status = client.connect(DISPATCHER_HOST, DISPATCHER_EXT_PORT);

    // Check the result of the  connect() method.
    if (!status.isServiceAvailable()) { // No dispatcher can be reached
    } // else at least one CC dispatcher has been reached and charging is available
 

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

Fields

Modifier and Type	Field and Description
static int	NO_TIMEOUT Constant describing no timeout (see the method connect(String, int)); It is '-1'.

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
int	addAllConnections(InstanceMap currentMap) Registers all the dispatcher instances included in the specified instance map as system instance to be connected to.
void	addAuthenticationListener(IAuthenticationListener listener) Add a listener which will be triggered on authentication events.
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.
ConnectionStatus	getConnectionStatus() Returns the connection status of the client.
java.lang.String	getName() Returns the name of this client
javax.net.ssl.SSLContext	getSslContext() Returns the SSL context used with secure connections.
boolean	isAtLeastOneConnectionIsRegistered() Return true if at least one of the connection to the dispatchers is registered, false otherwise.
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.
void	setUserCredentials(java.lang.String userId, java.lang.String userPassword) Set the credentials that will be used to authenticate the client.

Methods inherited from class java.lang.Object

equals, 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

getConnectionStatus

public ConnectionStatus getConnectionStatus()

Returns the connection status of the client.

Returns:

the connection status of the client

isAtLeastOneConnectionIsRegistered

public boolean isAtLeastOneConnectionIsRegistered()

Return true if at least one of the connection to the dispatchers is registered, false otherwise.

Returns:

true if at least one of the connection to the dispatchers is registered, false otherwise

setUserCredentials

public void setUserCredentials(java.lang.String userId,
                               java.lang.String userPassword)

Set the credentials that will be used to authenticate the client.

Parameters:

userId - the user identifier

userPassword - the user password

addAuthenticationListener

public void addAuthenticationListener(IAuthenticationListener listener)

Add a listener which will be triggered on authentication events.

Parameters:

listener - the listener which will be triggered on authentication events

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