Package com.highdeal.cnd.message

This Java package provides the main Java classes and interfaces to implement the Message TCP high-speed technical interface of SAP CC; With this package, you can develop a client application able to send chargeable items to the SAP CC system to charge (online or offline) or quote for the usage of a customer service by end customers.

See: Description

Interface Summary

Interface	Description
AcquisitionListener	This Java interface defines the onResult(..) method called by the asynchronous batch service client when performing asynchronous chargeable item acquisition by using the method AsyncBatchServiceClient.acquire(List, AcquisitionListener).
ActivateEventListener	This interface has to be implemented by the classes in charge for processing the result of the activate operation.
BatchChargeEventListener	This Java interface has to be implemented by the classes in charge for processing the result of a batch charge operation; the result may include an exception.
ChargeEventListener	This Java interface defines the necessary methods that you design and develop to handle the result (succes, failure) of a charging operation requested by the charging client in your client application.
ChargeExceptionListener	This Java interface specifies several onException(..) methods for handling exceptions in the charging client of your client application; Consider the known subinterfaces.
ChargingResultListener	This interface must be implemented by the classes in charge of processing the result of an asynchronous charging operation.
CheckLimitEventListener	This interface has to be implemented by the classes in charge for processing the result of a check limit operation.
CleanupEventListener	This interface has to be implemented by the classes in charge for processing the result of a cleanup operation.
ClientOpEventListener	The client operation event listener interface to receive client operation events.
ForbiddenChargeExceptionListener	This Java interface has to be implemented by the classes which must handle exceptions; It specifies the onException(..) method invoked to hanlde possible errors related to ForbiddenCharge exceptions.
FoundLostRatingListener	This Java interface is dedicated for managing a listener that is notified when a rater instance of the SAP CC system is found or lost.
IAuthenticationListener	This interface defines methods called while a connection is authenticated.
IExternalDataSettable	This Java interface defines the method for setting up or changing the external data that are included in the renew reservation notifications.
IMonitorSpendingStatusResultListener	This Java interface has to be implemented by the caller of the AsyncStatefulServiceClient.monitorSpendingStatus(String, byte, String, String[], int, IMonitorSpendingStatusResultListener) method for processing results and exceptions.
IMonitorSpendingStatusResultListener.ISpendingStatusMonitoringResult	This Java interface provides data of the result of spending status monitoring.
InvalidItemListener	This Java interface defines a method onException(..) dedicated to the handling of the invalid item exception in your client application; First consider the known subinterfaces that specify the listeners to implement in your code.
IReservationRenewalAcknowledger	This Java interface enables to inform the connected SAP CC system that the renew reservation notification is handled during session-based charging operations (see the online charging services).
IReservationRenewalAcknowledger.IReservationRenewalAcknowledgerListener	This Java interface enables a reservation renewal listener to be informed when the business acknowledgement has been received by the connected SAP CC system.
IReservationRenewalListener	This Java interface enables a charging client to be notified of reservation renewal during multiservice session-based charging operations (see the online charging services).
IReservationRenewalListenerIdSettable	This Java interface defines the necessary method for setting up the identifier of the reservation renewal listener (RRL) that is responsible for handling renew reservation notifications during session-based charging operations.
ISessionAsyncOperation	This Java interface defines the method relevant for executing an operation of a session-based charging scenario.
ISessionConfirmAndReserve	This Java interface defines the prepareConfirmAndReserve(..) method that is relevant for managing an update event of a session-based charging scenario.
ISessionConfirmation	This Java interface defines the key methods necessary for managing a reservation confirmation or reservation cancellation during session-based charging; implement the prepareConfirm(..) method and the prepareCancel(..) method to finalize a reservation in a charging session.
ISessionDefaultAttributeHolder	This Java interface defines generic methods and attributes for session-based charging operations; Consider the subinterfaces.
ISessionOperation	This Java interface defines the method relevant for executing and requesting an operation in a session-based charging scenario; the execution in your charging client sends the service operation to the connected SAP CC system.
ISessionReservation	This Java interface defines the key prepareReserve(..) method necessary for managing a reservation during session-based charging.
ISessionReservationRenewalNotifiable	This interface defines methods relevant for managing a reservation during session-based charging scenario.
ISessionResultListener	This Java interface has to be implemented by the caller in charge of processing the results and exceptions a of a session-based charging scenario.
ISessionStartChargingAsyncOperation	This Java interface defines necessary methods for implementing the beginning of a multiservice session during session-based charging operations: you prepare the expected reservations for an end customer and you trigger the start operation by executing the object returned by the createSessionStartAsyncOperation(..) method in your charging client.
ISessionStartChargingOperation	This Java interface defines necessary methods for implementing the beginning of a multiservice session during session-based charging operations: you prepare the expected reservations for an end customer and you trigger the start operation by executing the object returned by the createSessionStartOperation(..) method in your charging client.
ISessionStopChargingAsyncOperation	This Java interface defines the necessary methods for managing the termination of a multiservice session during session-based charging operations, for each charging session, you confirm or cancel a reservation.
ISessionStopChargingOperation	This Java interface defines the necessary methods for managing the termination of a multiservice session during session-based charging operations, for each charging session, you confirm or cancel a reservation.
ISessionUpdateChargingAsyncOperation	This Java interface defines the necessary methods for implementing an createSessionUpdaAsyncOperation(..) update of a multiservice session during session-based charging operations; for each charging session, you confirm a reservation, cancel, or extend a reservation.
ISessionUpdateChargingOperation	This Java interface defines the necessary methods for implementing an update of a multiservice session during session-based charging operations; for each charging session, you confirm a reservation, cancel, or extend a reservation.
ISpendingStatusReportAcknowledger	This Java interface defines the necessary methods to inform the SAP CC Core Server system that the spending status report is handled in your client application.
ISpendingStatusReportAcknowledger.ISpendingStatusReportAcknowledgerListener	This Java interface defines a method to be informed that your acknowledgement has been received by connected SAP CC system.
ISpendingStatusReportListener	This Java interface enables a monitoring client to be notified of spending status reports during customer service usage.
PrePostRateEventListener	Deprecated Deprecated since version 2.0 of SAP CC and replaced by the operations of the session-based charging services
SessionEventListener	This interface has to be implemented by the classes in charge for processing the result of session operations.
TranslateEventListener	This interface has to be implemented by the classes in charge for processing the result of a translate operation.

Class Summary

Class	Description
AsyncBatchServiceClient	This main Java class provides the necessary operations to implement Offline Charging Services (OFCS) in your SAP system landscape by using the Message TCP technical interface with asynchronous communications for the highest throughput performances.
AsyncRatingServiceClient	This abstract Java class provides common methods to open, close a connection, and send rating messages.
AsyncStatefulServiceClient	This main Java class provides the operations necessary to implement real-time charging services (event-based or session-based) in your SAP system landscape by using the Message TCP technical interface with asynchronous communications for the highest throughput performances.
AsyncStatefulServiceClientCtrl	This class represents a client operation event listener able to supervise the activity of the instances of the SAP CC Core Server system by limiting the number of operations in the server instances.
BatchServiceClient	This main Java class provides the necessary operations to implement Offline Charging Services (OFCS) in your SAP system landscape to send chargeable items to the connected SAP CC Core Server system to charge the past usage (consumption) of a marketable service by end customers; This class enables synchronous communications via the Message TCP high-speed technical interface.
BatchServiceClient.ReratingClientRequestHandler	Rerating service client request handler: always refuse rerating information, except if a rerating information handler has been set.
BootMode
ChargeableItemCollectorClient	Deprecated Since version 1.0 of SAP CC, this Java class is replaced by the StatefulServiceClient Java class.
ClientOpEventInformation	This Java class is used to collect the information elements generated by the ClientOPEventListener and the client API.
ConnectionStatus	The class contains the connection status information after a connect method is called (e.g.
EmptyClientOpEventListener	This Java class represents an empty event listener for receiving client operation events.
FoundLostRatingListenerWrapper
ResponseHandlerWrapper
ServiceClientTuning	This class is a set of tuning properties for the service client.
SessionChargingOperation	FOR INTERNAL USE ONLY - This Java class represents a multiservice session operation request that is sent to the connected SAP CC system to manage session-based charging services.
SessionOperationItemResult	This class defines the result of a session-based charging operation.
SessionOperationItemResultFactory
SpendingStatus	This Java class represents the spending status with its latest label value.
StatefulServiceClient	This main Java class provides the operations necessary to implement real-time charging services (event-based or session-based) in your system landscape by using the Message TCP technical interface with very high throughput performances.
StatefulServiceClientTuning
StatelessServiceClient	This Java class allows your client application to send some stateless rating and prerating events to the connected SAP CC Core Server system by using the Message TCP high-speed technical interface.
UniversalChargeEventListener

Enum Summary

Enum	Description
ClientOpEventTopic	This enumeration lists the operations where it is possible to have an event listener in your client application.
IAuthenticationListener.Reason	This enumeration lists the possible reasons for the message authentication exception.
IMonitorSpendingStatusResultListener.MonitoringAction	This enumeration lists the possible actions: no action, created, changed, or canceled.
ISessionDefaultAttributeHolder.TransactionSelectionCriteria	This enumeration defines the selection criteria for transaction selection: NONE_TRANSACTION, MASTER_TRANSACTION, ALL_TRANSACTION, or ALL_TRANSACTION_AND_RECURRING.
ISessionReservation.SessionReservationResolution	This enumeration lists the resolutions of a session reservation: confirmed of canceled.
SessionChargingOperation.SessionChargingOperationType	FOR INTERNAL USE ONLY - This enumeration lists the types of operations: START, UPDATE, and STOP.

Exception Summary

Exception	Description
CancelRatingSessionsException	Exception thrown when something wrong happens during the cancel rating session operation.
CommunicationFailureException	Exception internally thrown when the communication between your client application and the SAP CC Core Server system fails via the Message TCP technical interface: This exception is only generated on client-side in your customized charging client.
MessageAuthenticationException	Exception thrown when an error occurs during the authentication of a user login on the message API.
RerateSubscriptionException	Exception thrown when an error occurs during the execution of a subscription rerating operation in the connected SAP CC system; this exception includes a nested exception that explains the cause.

Package com.highdeal.cnd.message Description

This Java package provides the main Java classes and interfaces to implement the Message TCP high-speed technical interface of SAP CC; With this package, you can develop a client application able to send chargeable items to the SAP CC system to charge (online or offline) or quote for the usage of a customer service by end customers.

Technical Interface	Message TCP
Communication Protocol	TCP/IP
Communication Mode	Asynchronous, Synchronous
Public Endpoints	Dispatcher instances of the SAP CC system (Each dispatcher instance has a communication port relating to the TCP communications)
API Technology	[x] Java [ ] SOAP [ ] Proprietary XML
SAP CC Java Library	core-client.jar
Security	Yes (see the SAP CC Security Guide)
Load Balancing	Yes
Failover	Yes

Consider the following information in this topic:

• Message TCP technical interface
• Global charging services
• Implementation in your client application
• Notes on SAP CC implementation

Technical Interface: Message TCP

SAP Convergent Charging delivers an ultra-speed technical interface that you can implement in your SAP system landscape and develop in your Java-based client application to trigger business and technical operations to the SAP CC system connected via this technical interface.

Communication Infrastructure

The Message TCP technical interface defines a communication infrastructure to exchange messages between your client application and the connected SAP CC system.

Business Services

The Message TCP technical interface provides the following business services for prepaid and postpaid environments.

Business Service	Online Charging and Notification	Offline Charging
Description	Online charging	Offline charging
Services	Real-Time Charging: Stateful Charging With Credit Control and Credit Reservation: Session-Based, Event-Based Stateful Charging Without Credit Control and Credit Reservation: Immediate Charging for Direct Debiting Stateless Rating Services Business Notification Services (Account and Balance Management) Billing Process Synchronization Spending Status Monitoring	Non Real-Time Charging: Offline Acquisition for Deferred charging service Offline Charging Services (batch mode or single capture) Recharging for Rerating service (for subscriptions or provider contracts)
Environment	Prepaid and postpaid	Postpaid
Real-Time	Yes	No

Recommendation

Refer to the SAP CC Application Help for more information about the global charging services.

APIs for the Message TCP Interface

To implement some business services available in the Message TCP technical interface of SAP CC, you can use the following Java packages:

• com.highdeal.cnd.message
• com.highdeal.notification

Features

The Message TCP technical interface provides important features that you can implement in your system landscape.

Note

Consult the SAP CC Application Help for more information about high availability, high data volume and performances. It details the functions and mechanisms available in SAP Convergent Charging.

High Availability (HA) Management

• Heartbeat function
• Multiple failover functions

High Volume Management

Multiple load balancing functions

High Performance Management

• Multiple load balancing functions
• Asynchronous services

Notification Handling

You can implement the handling of the business notifications sent by the SAP CC Core Server system:

• Asynchronous service for batch management: The notifications are regularly sent by the SAP CC system. You can develop a Java-based client application that is responsible for handling and processing these notifications. Refer to the com.highdeal.notification Java package.
• Synchronous service for real-time management: Certain notifications are embedded by the SAP CC system in the result messages of the charging operation requests. The renew reservation notifications are only available in session-based charging services and require a specialized listener. You can implement in your client application the immediate processing of all these business notifications.

Security

The Message TCP technical interface provides secured communications via the TCP/IP channel. Consult the SAP CC Security Guide. The Message TCP technical interface can request client application to be authenticated. Consult the SAP CC Security Guide. Consult the security section in the javadoc of different charging clients classes.

Communications

• TCP/IP
• Asynchronous, Synchronous
• Public Endpoints: Dispatcher instances of the SAP CC system

Global Charging Services

Online Charging

The Online Charging Services enable to process in real time the incoming chargeable items sent by your mediation system in a connected mode (also called 'online' mode). These chargeable items relate to the usage (consumption) of a customer service. The mediation system sends the chargeable items before or during the service usage.

Business Services	Async. Comm.	Sync. Comm.
Stateful Session-Based Charging Service Multiservice session-based charging (multiple charging sessions of reservations/confirmations, reservation cancellation, reservation renewal on partially granted reservations)	Yes	Yes
Stateful Event-Based Charging Service Charging with credit control and quota reservation (no reservation cancellation) Immediate charging without credit control (for direct debiting) Advice of charge (inverse rating, blank charging)	Yes	Yes
Stateless Rating Service	No	Yes
Business Notification Service Account and Balance Management (amount threshold alert (prepaid account or a credit limit balance), reservation renewal, prepaid account expiration)	Yes	Yes
Business Processes Synchronization Service Billing Process Synchronization	Yes	Yes
Business Monitoring Service Spending Status Monitoring	Yes	Yes

Offline Charging

The Offline Charging Services enable to process a set of chargeable items sent by your mediation system in a disconnected mode (also called 'offline' mode). These chargeable items relate to the past usage (consumption) of a customer service. When relevant, your mediation system connects to and sends the chargeable items after the service usage.

Business Services	Async. Comm.	Sync. Comm.
Offline Acquisition Service (for Deferred Charging Service)	Yes	Yes
Offline Charging Service (batch mode or single) Batch Charging Advice of Charge	Yes	Yes
Recharging Service (for Rerating Service)	Yes	Yes

Implementation in Your Client Application

This Java package provides you with the classes necessary to implement online charging or offline charging services and relating service operations.

This section provides you with a developer guide:

• Operation management
• Charging client classes
• Initialization
• Connection
• Communications (time-out, termination)
• Exception and error handling
• Notification management

Operation Management

All the charging operations are available as Java methods that you call in a customized charging client class of your implementation code.

If you implement the asynchronous communications (see the AsyncStatefulServiceClient and AsyncBatchServiceClient classes) to speed up the processing, consider the exception and error handling.

Charging Client Classes

Several charging client classes are available according to your business requirements:

Charging Service	Charging Client Class	Business Services
Online Charging (with or without credit control)	AsyncStatefulServiceClient StatefulServiceClient StatelessServiceClient	Real-Time Charging Services (Session-Based or Event-Based Charging, Stateless Rating) Advice of Charge Services
Offline Charging	AsyncBatchServiceClient BatchServiceClient	Offline acquisition for Deferred charging service Offline charging service (batch mode or single) Quote service (blank charging) Recharging for Rerating service (for subscriptions or provider contracts)

Recommendation

For very high performances you should implement the AsyncStatefulServiceClient (online charging) and the AsyncBatchServiceClient (offline charging).

Monitoring Client Classes

Several monitoring client classes are available according to your business requirements:

Charging Service	Charging Client Class	Business Services
Online Charging (with or without credit control)	AsyncStatefulServiceClient StatefulServiceClient	Business Monitoring (Spending Status Monitoring)

Recommendation

For very high performances you should implement the AsyncStatefulServiceClient (online charging).

Initialization

Your Java-based client application initializes a charging client when it starts and stops when the client application stops.

Connection

Your charging client must be initialized by establishing a connection to one of more dispatcher instances available in the distant SAP CC Core Server system. This can be the master dispatcher or another dispatcher instance.

Once at least one dispatcher instance of the SAP CC system is connected from your client application, then this charging client retrieves automatically the list of all the dispatcher instances available on the SAP CC system side.

Note

The charging client establishes automatically in the background a connection with each dispatcher instance to ensure load balancing and failover functions.

Available Methods

All the connect(.) methods provide this mecanism:

• void connect(java.lang.String systemName, java.net.InetSocketAddress... bootDispatcherAddresses)
• void connect(java.lang.String systemName, com.highdeal.barbus.InstanceAddress... bootDispatcherAddresses)
• void connect(java.lang.String hostname, int hostport)
• void connect(java.lang.String hostname, int port, boolean secure, java.lang.String bindAddress, int timeout, FoundLostRatingListener ratingListener, ServiceClientTuning config)
• void connect(java.lang.String hostname, int hostport, FoundLostRatingListener ratingListener)
• void connect(java.lang.String systemName, int lookupDuration, java.net.InetSocketAddress discoveryAddress, java.lang.String bindAddress, int timeout, FoundLostRatingListener ratingListener, ServiceClientTuning config, java.net.InetSocketAddress... bootDispatcherAddresses)
• void connect(java.lang.String systemName, int lookupDuration, java.net.InetSocketAddress discoveryAddress, java.lang.String bindAddress, int timeout, FoundLostRatingListener ratingListener, ServiceClientTuning config, com.highdeal.barbus.InstanceAddress... bootDispatcherAddresses)
• void connect(java.lang.String hostname, int hostport, int timeout)
• void connect(java.lang.String hostname, int hostport, java.lang.String bindAddress, int timeout, FoundLostRatingListener ratingListener)
• void connect(java.lang.String hostname, int port, java.lang.String bindAddress, int timeout, FoundLostRatingListener ratingListener, ServiceClientTuning config)

Communications

Once an initial connection is established to the distant SAP CC system, your client application will be automatically connected.

Client Timeout

Defining a timeout is optional. Depending on the nature of the charging workflow, the recommended timeout may vary greatly.

Recommendation

For event-based charging, no timeout is recommended.

Termination

Your client application must release the connections when it ends.

Exception and Error Handling

Depending on your business requirements, you design and develop the relevant exception and error handling functions in your client application.

Client-Side Failures	Server System Failures
CommunicationFailureException	ServerFailureException BatchChargeException (Offline Charging Services) InvalidItemException ForbiddenChargeException TransactionClearingException SessionOperationException (Session-based Charging Service in Online Charging Services) StatelessRateException (Stateless Rating Service in Online Charging Services)

Note

If you implement the asynchronous communications (see the AsyncStatefulServiceClient and AsyncBatchServiceClient classes) to speed up the processing, consider the specialized listeners that are dedicated to the handling of the operation results in your client application. This processing includes the exception and error handling.

Notification Management

Prerequisites

You must set up the charging operation requests to include the rated transactions in the resulting purchase orders. The rated transactions include the notifications generated during the charging process. Refer to the ts flag available in the different methods of the charging clients.

Performances

Very high throughput:

• Pool of charging clients
• Asynchronous communications
• Tuning

Notes on SAP CC Implementation

Pooling

Your client application can manage a pool of charging clients for parallel processing, high volume traffic.

Specialized Listeners (Asynchronous Communication)

If you implement the asynchronous communications to speed up the processing, consider the specialized listeners that are dedicated to the handling of the operation results in your client application.

The relevant listener depends on the type of the business operations you want to manage.

Note

This processing includes the exception and error handling when an operation request failed.

Service Operations

Event-Based Charging Operations

Event-Based Charge (Online or Offline Service)

Batch Charge (Offline Service)

Best-Effort Charge (Online Service)

Get Estimated Price (Online Service)

Blank Charge (Online Service)

This operation estimates the price by asking the SAP CC system to rate and charge in blank mode the specified chargeable item that simulates a customer service usage. The chargeable item can correspond to a real service consumption (not charged) or to the simulation of service consumption. You implement this operation if you want to provide advice of charge services in your SAP system landscape.

Note

This operation is equivalent to the event-based charge operation but the blank mode means that no data is committed to the database.

Caution

If the transaction processor does not take care about the database transaction (transaction processor that stores the transactions into a file by example), the transaction processor action will not be rolled back.

Inverse Rate (Check Limit)

What is the maximum quantity of service I can consume based on an amount?

Session-Based Charging Operations

SAP Convergent Charging can provide charging services for service usage information that is based on consumption sessions. Session-based charging operations are only available in real-time enviroment to implement online charging service in your system landscape.

Session-Based Charge (Online Service)

Additional Information

Consult the SAP CC Application Help for more information about the convergent charging services, the implementation scenario variants, and the charging and activation processes.