Package com.highdeal.notification

Class NotificationServiceClient

java.lang.Object
com.highdeal.notification.NotificationServiceClient
All Implemented Interfaces:
com.highdeal.barbus.ISSLContextProvider
public class NotificationServiceClient extends Object implements com.highdeal.barbus.ISSLContextProvider
This Java class implements the notification service client that you must instantiate to be able to handle asynchronous 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 assign it to your notification client (see the setNotificationHandler(...) method).

Note

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

Security

If user authentication between the client and SAP CC is required (i.e., if the MESSAGE_API_AUTHENTICATION_REQUIRED system parameter is set to true), you must set valid user credentials in the notification client, using the setUserCredentials() method.
Then, you must call one of the connect(...) methods to proceed with the authentication and the connection to the SAP CC server.

Code Snippet

The following code snippet provides an example of how to authenticate a client application: 

    private static final String DISPATCHER_HOST = "sapcc-dispatcher-1";
    private static final int DISPATCHER_EXT_PORT = 2000;
    private static final boolean USE_SECURED_CONNECTION = false;
    private static final int TIMEOUT_MS = 10000;

    // Initialize the notification service client by calling the constructor
    NotificationServiceClient client = new NotificationServiceClient();

    // Set the user credentials for the newly 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, according to the desired behavior
    ConnectionStatus status = client.connect(DISPATCHER_HOST, DISPATCHER_EXT_PORT, USE_SECURED_CONNECTION, null, TIMEOUT_MS);

    // 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

The simplest approach is to invoke the connect(java.lang.String,int,boolean,java.lang.String,int) method directly.
This initiates a connection to a chosen dispatcher, and lets the notification client automatically request the current list of instance information objects, describing the notification service servers to be connected to.
Then, the notification client opens a connection to each of the automatically detected servers and becomes able to receive notifications.

Alternatively, you may first initialize your notification client with a previously constructed list of instance information objects, and then invoke one of the connect(...) methods which don't require a dispatcher's address in their arguments.
Doing this, the notification client opens a connection to each of the previously specified servers and becomes able to receive notifications.

For illustrations of these approaches, please refer to the example code snippets below.

Customizing Sequence

Perform the following steps to implement your notification client:

  1. Design and implement a customized NotificationHandler class according to your business requirements
  2. Instantiate your own NotificationHandler
  3. Instantiate a NotificationServiceClient object
  4. Initialize this notification client with the setNotificationHandler() method
  5. Using any of the approaches below, connect the notification client to the SAP CC system to receive and process the asynchronous notifications
    1. automated instance map retrieval and connection in one statement (with or without secured communication)
      1. To connect to the specified dispatcher, use that connection to retrieve the full instance map, and then automatically connect to all the available dispatchers, invoke one of:
    2. connection based on a previously obtained instance map (secured communication not supported)
      1. Retrieve the instance map with the searchInstanceMap(...) method
      2. To connect to all the dispatchers listed in the retrieved instance map, invoke:
    3. connection after having manually assigned a previously obtained instance map (secured communication not supported)
      1. Retrieve the instance map with the searchInstanceMap(...) method
      2. Prepare the connection to the remote SAP CC system with the addAllConnections(...) method
      3. To connect to all the dispatchers listed in the retrieved instance map, invoke one of:

Examples

Each notification client must be initialized by establishing a connection to one or more dispatchers available in the remote SAP CC system.

  1. direct connection using the address of a chosen dispatcher
    In this example, the user application specifies the address of one known dispatcher to get an initial connection.
    The notification client then automatically uses that initial connection to fetch the list of all available dispatchers, and to establish a connection to each of them. 
         NotificationHandler notifHandler = ... // your own implementation of NotificationHandler
     client = new NotificationServiceClient();
     client.setNotificationHandler(notifHandler);
     client.connect(dispatcherAddress, dispatcherPort, true, null, 10000);

  2. explicit retrieval of the instance map, and connection to all the dispatchers listed in it
    In this second example, the user application explicitly retrieves the full instance map and then invokes connect(InstanceMap, String, int), in order to create a connection to each listed dispatcher.
    Fetching the instance map separately can be useful if you need to log or otherwise process the details contained in it. 
         NotificationHandler notifHandler = ... // your own implementation of NotificationHandler
     InstanceMap instanceMap = NotificationServiceClient.searchInstanceMap(serverUrl, login, password);
     // here, you may read the instance map to process the details about the instances detected in the SAP CC system
     client = new NotificationServiceClient();
     client.setNotificationHandler(notifHandler);
     client.connect(instanceMap, null, 10000); // alternatively, you may separately call "addAllConnections(instanceMap)" followed by "connect(null, 10000)"

    3. In all cases, the notification client requires the explicit address of an available dispatcher, to retrieve the instance map.

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 try to reopen the connection between this notification client and the lost instance. This process stays active until the notification client is closed or terminated.

See Also:

  • Field Details

  • Constructor Details

    • NotificationServiceClient

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

    • NotificationServiceClient

      public NotificationServiceClient(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 Details

    • getSslContext

      public 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(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(String bootHostName, int bootPort, BootMode bootMode) throws 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:
      IOException - if the boot instance cannot be connected.
      IllegalArgumentException - if bootHostName is null or if bootPort is out of range.

    • searchInstanceMap

      public static InstanceMap searchInstanceMap(String serverUrl, String login, String password) throws 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:
      IOException - if the dispatcher instance cannot be connected to.

    • getName

      public 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 remote 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:
      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:
      IllegalStateException - if this client is already connected

    • clearConnections

      public void clearConnections()
      Clears the instance list.
      Throws:
      IllegalStateException - if this client is already connected

    • connect

      public void connect() throws IOException
      Connects this client with all the already declared instances. The address of this client is a chosen local address and the connection has no timeout.
      Throws:
      IOException - if this client cannot be connected to the network
      IllegalStateException - if this client is already connected or if no instance is declared

    • connect

      public void connect(String bindAddress, int timeout) throws 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 chosen.
      timeout - The timeout for this connection attempt. A negative value means no timeout.
      Throws:
      IOException - if this client cannot be connected to the network
      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(String userId, 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:
      IllegalArgumentException - If this client is already connected

    • connect

      public final void connect(InstanceMap imap, String bindAddress, int timeout) throws IOException
      Connects this notification client with the SAP CC system by using an instance map. A timeout must be specified.
      Parameters:
      imap - The instance map that describes the SAP CC system to connect to. Cannot be null.
      bindAddress - The address to bind to, can be null
      timeout - The timeout in milliseconds for the connection attempt (or -1 to wait indefinitely).
      Throws:
      IOException - if the client cannot connect to the remote SAP CC system (if the server is not running, for example).

    • connect

      public final void connect(String hostname, int port, String bindAddress, int timeout) throws IOException
      Connects this notification client with the dispatcher instances.

      First of all, this client contacts the boot instance defined by the hostname and port arguments, to retrieve the instance map. Then this client opens one connection with each dispatcher instance defined in the instance map.

      Parameters:
      hostname - The host name of a dispatcher, to retrieve the instance map
      port - The port on which the dispatcher waits for requests
      bindAddress - The address to bind to, can be null
      timeout - The timeout in milliseconds for the connection attempt (or -1 to wait indefinitely).
      Throws:
      IOException - if the client cannot connect to a server (if the server is not running, for example).
      IllegalArgumentException - if hostname is null or if the port is out of range.

    • connect

      public final void connect(String hostname, int port, boolean secure, String bindAddress, int timeout) throws IOException
      Connects this notification client with the dispatcher instances.

      First of all, this client contacts the boot instance defined by the arguments hostname and port to get its instance map. Then this client opens connections with all the dispatcher instances defined in the instance map.

      Parameters:
      hostname - The host name of the server
      port - The port on which the server waits for requests
      secure - true if the connection to the server is secure
      bindAddress - The address to bind to, can be null
      timeout - The timeout in milliseconds for the connection attempt (or -1 to wait indefinitely).
      Throws:
      IOException - if the client cannot connect to the server (if the server is not running, for example).
      IllegalArgumentException - if hostname is null or if the port is out of range.