com.highdeal.bart.message

Class CDRServiceClient

java.lang.Object

com.highdeal.bart.message.CDRServiceClient

All Implemented Interfaces:

com.highdeal.barbus.ISSLContextProvider

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

This Java class provides the necessary operations to implement Offline Acquisition Services to develop an offline mediation application or connector to be able to send Consumption Detail Records (CDRs) to the SAP CC BART Server system for being charged by SAP Convergent Charging; This class enables synchronous communications via the Message TCP high-speed technical interface.

Implementation in Your Client Application

To develop a mediation connector you must implement in your client application:

• CDR preparation
• Connection management
• Aquisition management

Implementing the Preparation of CDRs

You must implement:

• The load of collected information data records related to the service consumption by the end customers of the service provider
• The conversion of information data related to this customer service usage to Consumption Detail Records (CDRs) that specify the data format handled by SAP CC BART Server. This format is based on Call Detail Record format from the telecommunication industry to facilitate this data conversion.

Implementing the Connection

The distant SAP CC BART Server system is identified by its hostname on which it is running and its listening port:

• The IP address or the name of the host machine of the SAP CC system. Must not be null.
• The communication port on which the distant SAP CC system is listening. It is a positive integer up to 65535.

To manage your network traffic, this client can be bound to one or all the network interface(s) of the machine hosting your application. If you want to force this client to be bound to one specific network interface, you must specify the argument bindAddress with a valid IP address or a valid host name. Otherwise this client will be bound to all the network interfaces.
Whatever the bind address, the port of this client will be choosen automatically between all the available ports of the network interface(s).

Note

Consult the SAP CC Configuration Guide for more information about the communication settings and access points available in your landscape.

Client Timeout

You specify the maximal duration (in seconds), the response of a message has to be expected whatever the sent message. If no client timeout is needed, set timeout to NO_TIMEOUT.

Error Handling

This MessageClient will maintain the connection with the server opened. If the connection is closed because of network problem, this client will try to open again the connection with the server every 2 seconds.

Implementing the CDR Acquisition

Prerequisistes

• Connection is established
• CDRs to be sent are available

Customizing Sequence

• startAcquisitionSession(..)
• acquireCDR(..)
• stopAcquisitionSession(..)
• close()

Constructor Summary

Constructors

Constructor and Description
CDRServiceClient() Creates a non-initialized MessageClient; One of the methods connect() must then be used to connect it to the distant SAP CC BART Server system.
CDRServiceClient(java.lang.String hostName, int port) Creates a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API).
CDRServiceClient(java.lang.String hostName, int port, int timeout) Creates a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API);.
CDRServiceClient(java.lang.String hostName, int port, java.lang.String bindAddress, int timeout) Initializes a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API).

Method Summary

Modifier and Type	Method and Description
AcquireCDRResult	acquireCDR(java.util.Vector<CDRModel> cdrs, AcquisitionSessionModel session) Asks the distant SAP CC BART Server system to acquire the specified CDRs in batch mode via the TCP Message interface; Before to process the acquisition, you must define and start an acquisition session.
void	close() Closes the connection with the CDR Service server.
void	connect(java.lang.String hostName, int port) Connects this MessageClient using the round robin with the distant SAP CC BART Server system.
void	connect(java.lang.String hostName, int port, int timeout) Connects this MessageClient using the round robin with the distant SAP CC BART Server system with communication timeout set in client application side.
void	connect(java.lang.String hostName, int port, java.lang.String bindAddress, int timeout) Connects this MessageClient using the round robin with the server.
void	connect(java.lang.String hostname, int port, java.lang.String bindAddress, int timeout, com.highdeal.cnd.message.ServiceClientTuning config) Connects this CDRServiceClient to the distant SAP CC BART Server system.
javax.net.ssl.SSLContext	getSslContext() Returns the SSL context used with secure connections
int	getTimeout() Returns the timeout in milliseconds for each request (or -1 to wait indefinitely)
boolean	isConnected() Gets the connected status.
boolean	isSecureMode() Returns true if this client use the secure mode
void	setSecureMode(boolean secureMode) Configures the secure mode for this client application
void	setSslContext(javax.net.ssl.SSLContext sslContext) Sets the SSL context used with secure connections or null to use plain connections which is the default mode.
AcquisitionSessionModel	startAcquisitionSession(AcquisitionSessionModel session) Starts an acquisition session of CDRs in the distant SAP CC system.
AcquisitionSessionModel	stopAcquisitionSession(AcquisitionSessionModel session, boolean withErrors) Stops an started acquisition session

Methods inherited from class java.lang.Object

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

Constructor Detail

CDRServiceClient

public CDRServiceClient()

Creates a non-initialized MessageClient; One of the methods connect() must then be used to connect it to the distant SAP CC BART Server system.

CDRServiceClient

public CDRServiceClient(java.lang.String hostName,
                        int port)
                 throws java.io.IOException

Creates a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API).

Parameters:

hostName - The host name of the distant SAP CC BART Server system

port - The communication port on which the server waits for operation requests from client applications

Throws:

java.io.IOException - if the client cannot connect to the server (if server is not running, for instance).

CDRServiceClient

public CDRServiceClient(java.lang.String hostName,
                        int port,
                        int timeout)
                 throws java.io.IOException

Creates a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API);.

Parameters:

hostName - The host name of the distant SAP CC BART Server system

port - The communication port on which the server waits for operation requests from client applications

timeout - The timeout in milliseconds for each request (or -1 to wait indefinitely). If you use zero and acknowledgments are requested then a CommunicationFailureException will be thrown without sending request.

Throws:

java.io.IOException - if the client cannot connect to the server (if server is not running, for instance).

CDRServiceClient

public CDRServiceClient(java.lang.String hostName,
                        int port,
                        java.lang.String bindAddress,
                        int timeout)
                 throws java.io.IOException

Initializes a MessageClient and connects it with the distant SAP CC BART Server system (server side of this API).

Parameters:

hostName - The host name of the distant SAP CC BART Server system

port - The communication port on which the server waits for operation requests from client applicationst

bindAddress - The address to bind to (can be null)

timeout - The timeout in milliseconds for each request (or -1 to wait indefinitely) If you use zero and acknowledgments are requested then a CommunicationFailureException will be thrown without sending request.

Throws:

java.io.IOException - if the client cannot connect to the servers.

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 or null to use plain connections which is the default mode.

Parameters:

sslContext - The SSL context used with secure connections

isSecureMode

public boolean isSecureMode()

Returns true if this client use the secure mode

Returns:

true If this client use the secure mode

setSecureMode

public void setSecureMode(boolean secureMode)
                   throws java.security.NoSuchAlgorithmException

Configures the secure mode for this client application

Parameters:

secureMode - The secure mode to use for this client; If true, this method sets the SSL context to its default value.

Throws:

java.security.NoSuchAlgorithmException - When the secure mode SSL context cannot be created

See Also:

setSslContext(SSLContext)

getTimeout

public int getTimeout()

Returns the timeout in milliseconds for each request (or -1 to wait indefinitely)

Returns:

The timeout in milliseconds, or -1 if no timeout has previously been set for this MessageClient.

acquireCDR

public AcquireCDRResult acquireCDR(java.util.Vector<CDRModel> cdrs,
                                   AcquisitionSessionModel session)
                            throws InvalidCDRException,
                                   InvalidAcquisitionException,
                                   com.highdeal.hci.ServerFailureException,
                                   com.highdeal.cnd.message.CommunicationFailureException

Asks the distant SAP CC BART Server system to acquire the specified CDRs in batch mode via the TCP Message interface; Before to process the acquisition, you must define and start an acquisition session.

Parameters:

cdrs - A vector of CDRs to be acquired by BART Server

session - The acquisition session which these CDRs will be linked to

Returns:

A vector containing the CDRs with status ACQUIRED/DUPLICATE

Throws:

InvalidCDRException - If cdrs is not valid

InvalidAcquisitionException - If the acquisition session is not valid

com.highdeal.hci.ServerFailureException - If the SAP CC BART Server system is not available

com.highdeal.cnd.message.CommunicationFailureException - If a communication failure occurs with the distant SAP CC system

startAcquisitionSession

public AcquisitionSessionModel startAcquisitionSession(AcquisitionSessionModel session)
                                                throws InvalidAcquisitionException,
                                                       com.highdeal.hci.ServerFailureException,
                                                       com.highdeal.cnd.message.CommunicationFailureException

Starts an acquisition session of CDRs in the distant SAP CC system.

Parameters:

session - The settings of the acquisition session to start

Returns:

The session and its unique ID as it has been created on distant SAP CC BART Server system

Throws:

InvalidAcquisitionException - If the acquisition session is not valid

com.highdeal.hci.ServerFailureException - If the SAP CC BART Server system is not available

com.highdeal.cnd.message.CommunicationFailureException - If a communication failure occurs with the distant SAP CC system

stopAcquisitionSession

public AcquisitionSessionModel stopAcquisitionSession(AcquisitionSessionModel session,
                                                      boolean withErrors)
                                               throws InvalidAcquisitionException,
                                                      com.highdeal.hci.ServerFailureException,
                                                      com.highdeal.cnd.message.CommunicationFailureException

Stops an started acquisition session

Parameters:

session - The acquisition session to stop

withErrors - A flag which notifies the SAP CC BART Server that some errors occurred during the acquisition

Returns:

The session as it is created on server side

Throws:

InvalidAcquisitionException - If the acquisition session is not valid

com.highdeal.hci.ServerFailureException - If the SAP CC BART Server system is not available

com.highdeal.cnd.message.CommunicationFailureException - If a communication failure occurs with the distant SAP CC system

connect

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

Connects this MessageClient using the round robin with the distant SAP CC BART Server system with communication timeout set in client application side.

Parameters:

hostName - The host name of the SAP CC BART Server system

port - The communication port on which the server waits for operation requests

timeout - The client timeout for the operation requests sent by your Java application

Throws:

java.io.IOException - if the client cannot connect to the server (if server is not running, for instance).

connect

public void connect(java.lang.String hostName,
                    int port)
             throws java.io.IOException

Connects this MessageClient using the round robin with the distant SAP CC BART Server system.

Parameters:

hostName - The host name of the SAP CC BART Server system

port - The communication port on which the server waits for operation requests

Throws:

java.io.IOException - if the client cannot connect to the server (if server is not running, for instance).

connect

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

Connects this MessageClient using the round robin with the server.

Parameters:

hostName - The host name of the BART Server system

port - The port on which the server waits for operation requests

bindAddress - The address to bind description

timeout - The communication timeout for the operation requests sent by your Java application

Throws:

java.io.IOException - if the client cannot connect to the server (if server is not running, for instance).

connect

public void connect(java.lang.String hostname,
                    int port,
                    java.lang.String bindAddress,
                    int timeout,
                    com.highdeal.cnd.message.ServiceClientTuning config)
             throws java.lang.IllegalStateException,
                    java.lang.IllegalArgumentException,
                    java.io.IOException

Connects this CDRServiceClient to the distant SAP CC BART Server system.

The cdr service server is identified by its hostname on which it is running and its listening port. Please see BART documentation in order to find the value of this properties.

This client can be bound to one or all the network interface(s) of the running host. If you want to force this client to be bound to one specific network interface, just specified the argument bindAddress with a valid IP address or a valid hostname. Otherwise this client will be bound to all the network interfaces.
Whatever the bind address, the port of this client will be choosen automatically between all the available ports of the network interface(s).

After having invoked this method, this client will maintain the connection with the server opened. If the connection is closed because of network problem, this client will try to open again the connection with the server every 2 seconds. This period can be updated using the ServiceClientTuning.

Parameters:

hostname - The IP address or the name of the host on which the cdr service server is running (the SAP CC BART Server system). Must not be null.

port - The port on which the cdr service server is listening. It is a positive integer up to 65535.

bindAddress - The local address (IP address or host name) to which this client has to be bound. If not specified (i.e. is null), this client will be bound to all the available addresses. The bound port will be the choosen between all the available ports.

timeout - The maximal duration in second, the response of a message has to be expected whatever the sent message. If no timeout is needed, set timeout to NO_TIMEOUT.

config - A set of configuration settings dedicated to fine tune the High Availability (HA) of this service.

Must be null by default.

The SAP support team can provide you with specific values only in order to resolve HA issue by an SAP support team. If null, the default settings of ServiceClientTuning are used.

Throws:

java.lang.IllegalStateException - if this client is already connected with a remote cdr service server.

java.lang.IllegalArgumentException - if hostname is null or if port is outside the range of a valid port values.

java.io.IOException - if this client cannot be connected to the server because of an I/O error.

isConnected

public boolean isConnected()

Gets the connected status.

Returns:

true if the client is connected and false otherwise.

close

public void close()

Closes the connection with the CDR Service server. This method allows to release all resources attached (sockets and buffers).