Package com.highdeal.cnd.message

Class StatefulServiceClient

java.lang.Object
com.highdeal.cnd.message.AsyncRatingServiceClient
com.highdeal.cnd.message.AsyncStatefulServiceClient
com.highdeal.cnd.message.StatefulServiceClient
All Implemented Interfaces:
com.highdeal.barbus.ISSLContextProvider
Direct Known Subclasses:
ChargeableItemCollectorClient
public class StatefulServiceClient extends AsyncStatefulServiceClient
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.

Your client application converts the information data about the customer service usage (service consumption) to a chargeable item and sends this data event to the connected SAP CC system, the online charging system (OCS) for being rated (dynamic pricing) and charged to an account or allowance.

This class provides the necessary methods to implement online charging services in your system landscape with or without credit control before the customer service delivery.

Recommendation

You can implement the AsyncStatefulServiceClient class to speed up the processing.

Example

The SAP CC Message Client user interface is a good example of implementation. This user interface implements this com.highdeal.cnd.message.StatefulServiceClient class to allow the SAP CC user to send some charging operations to the SAP CC system for test, demo, or training purposes. For more information, see the primary help.

Consider the following information in this topic:

Synchronous Services and Operations

With this Java class, you can implement online event-based charging services or online session-based charging services via the Message TCP high-speed technical interface.

Business Services: Online Stateful Charging Operations Technical Names (Consider the methods in this Java class)
Event-based charging without credit control Immediate charging operation (for direct debiting) charge(..)
Event-based charging with credit control Best-effort charging operation checkLimit(..)
Event-based advice of charge Blank charging operation blankCharge(..)
Inverse rating operation checkLimit(..) in estimation mode
Multiservice session-based charging (multiple charging sessions of reservations/confirmations) Quota reservations and consumption confirmations (partial or complete) related to the usage of several customer services or several options of a global service:
  • A multiservice session includes several charging sessions
  • Optional reservation renewal mechanism associated to a specialized listener
You manage a multiservice session relating to several customer services with: Within this multiservice session, you manage the charging sessions (of quota reservations and consumption confirmations related to the usage of one customer service) with:

You handle the new reservation notifications on partially granted reservations with a specialized listener. This listener must register to the connected SAP CC system.

Business monitoring Spending status monitoring (advanced implementation and customizing) You manage the spending status monitoring by
Billing process synchronization Activation of periodic and one-off fees activate(..)
Special:

Notes

Deprecated Services and Operations

The following business operations or services are now deprecated and replaced. SAP SE recommends that you do not implement these operations anymore. They will be revoked in newer versions of SAP Convergent Charging.

Business Services Deprecated Operations Technical Names (Consider the methods in this Java class) Replaced by
Non authenticated server connection All class builders (except the empty one) that connect the client to the server without user credentials. Replaced by the StatefulServiceClient() + a call to AsyncRatingServiceClient.setUserCredentials(String, String) then a call to one of the following methods to connect the client:
Event-based advice of charge Price estimating operation getEstimatedPrice(..) Replaced by the Blank charging operation
Event-based charging with credit control Prerating operation Replaced by the multiservice session-based charging service
Session-based charging (single charging session)

Replaced by: Multiservice session-based charging

Quota reservation and consumption confirmation related to the usage of one customer service:
  • Start a charging session by reserving credit
  • Update the session by confirming or canceling the previous reservation (effective charging) and operating a new reservation
  • Stop the session
Replaced by the multiservice session-based charging service

Features

This charging client benefits from the functions provided by the Message TCP technical interface. Refer to its features about:

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

Operation Results

The connected SAP CC system replies to operation requests with the following data:

Charging Contract Operational Status

Most of services and operations take into account the operational status of a charging contract (excepting the preRate and the postRate deprecated operations). This means that an operation exception can be thrown if the operational status of a charging contract is locked or closed.

Communication Timeout

When a timeout is associated to a given message client, it must be performed during this limited time. If this limited time is exceeded, the operation is rolled back but the client timeout does not guarantee that related operations successfully ended (see the SAP CC Application Help for more information).

High Performances

By default, this charging client provides high throughput performances. For very high throughput performances, consider the AsyncStatefulServiceClient or the fine-tuning activity.

High Availability (HA)

By default, this charging client provides high availability services with an SAP CC system with distributed instances in HA setup.

You can implement several charging clients in your Java-based client application and you can implement several client applications to manage failover mechanism in your client applications.

Notification

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

  • Asynchronous service for batch management: The notifications are regularly sent by the SAP CC system. Refer to the Java package information.
  • Synchronous service for real-time management: The notifications are embedded by the SAP CC system in the result messages of the charging requests. The renew reservation notifications are managed via a specialized listener (see advanced implementation). You can implement in your client application the immediate processing of these notifications.

Security

To implement a ciphered connection between the client and SAP CC, use AsyncRatingServiceClient.setSslContext(javax.net.ssl.SSLContext).
Then, the client application will be authenticated and authorized to connect to the SAP CC server by calling the AsyncRatingServiceClient.connect(String hostname, int port, boolean secure, String bindAddress, int timeout, FoundLostRatingListener ratingListener, ServiceClientTuning config) method, with secure parameter set to true.

To implement user authentication between the client and SAP CC, the client must set up 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:

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 stateful service client by (always) calling the empty builder (other builders are deprecated)
    StatefulServiceClient client = new StatefulServiceClient();

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

    //Call one of the connect() methods that are provided in Service Client classes according to the
    //  expected 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

Implementation in Your Client Application

Initializing and Connecting

Your charging client (based on this StatefulServiceClient class) must be initialized via establishing a connection to one or more dispatcher instances available in the distant SAP CC system. Once at least one dispatcher of the SAP CC system is connected from the 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.

Implementing Session-Based Charging Services

You implement the following operations in your Java-based client application to manage a multiservice session:

Note

Refer to the implementation note section if you want to provide the optional reservation renewal function in your system landscape.

System Configuration

Consult the SAP CC Configuration and Implementation Guide to know the necessary configuration settings of the SAP CC system.

Master Data Configuration

Particular constraints apply to the configuration of the pricing logic. Pay attention when designing and configuring price plans dedicated to session-based charging services. Consult the SAP CC Application Help and the primary help of the SAP CC Core Tool user interface for more information.

Implementing Event-Based Charging Services

Depending on your business requirements, you implement one of the following operations in your Java-based client application:

Implementing Policy Control Services

You implement this function to provide policy control mechanisms in your system landscape.

Prerequisites

The SAP CC system is configured to support the reservation renewal function.

Customizing Sequence

Dedicated Listener

System Configuration

Consult the SAP CC Configuration and Implementation Guide to know the necessary configuration settings of the SAP CC system. Before implementing SAP Convergent Charging in your system landscape, you must configure the systems and the data.

Terminating

Your client application must release the connections when it ends. Implement the <a href="StatefulServiceClient.html#close()"close(..) method.

Advanced Implementation

The following advanced implementation activities are possible. Refer to the implementation note section for more information.

Notes on SAP CC Implementation

Fine-Tuning

By default, this charging client provides high throughput performances.

You can fine tune the behavior of your client application by implementing the StatefulServiceClientTuning class.

Implementing the Spending Status Monitoring Function

This function is available in the online charging services. In this Customizing activity you develop a client application and a monitoring client that manages spending status monitoring and report handling.

Prerequisites

The SAP CC system is configured to support the spending status monitoring function.

Customizing Sequence

  • Depending on your business requirements, design your listener of spending status reports accordingly to the spending status changes sent by the SAP CC system
  • Implement the integration code of a spending status report listener based on the ISpendingStatusReportListener interface. Develop your own onSpendingStatusReport(...) method
  • Depending on your business requirements, design your client application accordingly to your own spending status monitoring sequences
  • In your client application, implement a monitoring client based on this StatefulServiceClient class:

System Configuration

Consult the SAP CC Configuration and Implementation Guide to know the necessary configuration settings of the SAP CC system. Before implementing SAP Convergent Charging in your system landscape, you must configure the systems and the data.

Implementing the ISpendingStatusReportListener interface

A client application must implement the ISpendingStatusReportListener interface to be able to handle monitoring reports.

Implementing the Reservation Renewal Function

This function is available in the session-based charging services.

Prerequisites

The SAP CC system is configured to support the reservation renewal function.

Customizing Sequence

  • Depending on your business requirements, design the functions of the listeners of renew reservation notifications
  • Implement the integration code of a reservation renewal listener based on the IReservationRenewalListener interface. You develop your own onRenewReservation(..) method.
  • Extend the initialization of the charging client: Implement the registration of a listener with the registerReservationRenewalListener(..) method .
  • Otherwise, you can implement another client based on the StatefulServiceClient class in the client application or in another client application. This new notification client is responsible for handling all the renew reservation notifications for all the charging client instances in the client application.
  • Change the implementation of the multiservice session-based charging services
    • In the Multiservice session start:
      • Enable the reservation renewal function when starting a multiservice session by using the setReservationRenewalListenerId(..) inherited method. Specify that the multiservice sessions are eligible for renew reservation notifications by the reservation renewal listener identified by the specified identifier.
      • When relevant for your business requirements, set up external data that the reservation renewal listener(s) may need when processing the renew reservation notifications. Use the setExternalData(..) inherited method. This data is never changed by the SAP CC Core Server system.
    • In the Multiservice session update: When relevant for your business requirements, change external data that is copied to the renew reservation notifications by the connected SAP CC system.
  • Change the termination of the charging client: Implement the unregistration of a listener

System Configuration

Consult the SAP CC Configuration and Implementation Guide to know the necessary configuration settings of the SAP CC system that relates to the reservation renewal function available in the session-based charging services.

Implementing the IReservationRenewalListener interface

A client application must implement the IReservationRenewalListener interface to be able to handle Renew Reservation notifications.

The implementation of this interface allows the SAP CC system to inform the client application that additional credit has been made available during a multiservice charging session. When such a notification occurs, the client application may not have to stop the session and may continue to update the session by making new reservations on charging sessions. The client application can handle this use case by implementing an IReservationRenewalListener and attaching it to the charging client.

The IReservationRenewalListener interface defines a unique method to handle the notification: onRenewReservation(). This method provides the necessary parameters to handle the notification:

  • The session identifier, which is unique to the multiservice charging session
  • The reservation identifier, which is unique to the service charging session for the multiservice charging session
  • The external data that can optionally be passed to the SAP CC system during a start or update operation
  • An index indicating the number of attempts to transmit this notification
  • An IReservationRenewalAcknowledger object that must be used to acknowledge the receipt of this notification

The acknowledger is an optional feature allowing the client application to tell the SAP CC system the notification has been received and handled. This feature is useful when the RENEW_RESERVATION_RESEND_ATTEMPTS parameter of the SAP CC system is set with a positive and non-zero value. Once the SAP CC system is acknowledged by the client application, the resend procedure is canceled for this notification.

Code Snippet

The following code snippet provides an example of how to implement an IReservationRenewalListener interface to receive and handle a Renew Reservation notification: 

    private class MyReservationRenewalListener implements IReservationRenewalListener {

        public void onRenewReservation(String sessionId, String reservationId, byte[] externalData, short resendAttempt, IReservationRenewalAcknowledger acknowledger) {

            // Simple implementation: print notification to console
            System.out.println("Renew Reservation notification received for session/reservation " + sessionId + " " + reservationId);

            // (Optional) Acknowledge the handling message
            acknowledger.ack(new IReservationRenewalAcknowledgerListener() {

                public void onException(ServerFailureException e) {
                    // Handle server failure exception
                    System.err.println("ServerFailureException in acknowledgment: " + e.getMessage());
                }

                public void onException(IllegalArgumentException e) {
                    // Handle illegal argument exception
                    System.err.println("IllegalArgumentException in acknowledgment: " + e.getMessage());
                }

                public void onException(CommunicationFailureException e) {
                    // Handle communication failure exception
                    System.err.println("CommunicationFailureException in acknowledgment: " + e.getMessage());
                }

                public void onResult() {
                    // Handle acknowledgment result
                    System.out.println("Server has received acknowledgment");
                }
            });
        }
    }

Implementing the registerReservationRenewalListener(byte, IReservationRenewalListener) method

To be able to receive and handle Renew Reservation notifications, the client application must use the registerReservationRenewalListener method of the charging client. The client application must provide a ReservationRenewalListener identifier (rrlId) and the ReservationRenewalListener that can handle the Renew Reservation notification. The rrlId value can be 1 to 127 included.

Code Snippet

The following code snippet provides an example of how to call the registerReservationRenewalListener() method of the charging client: 

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

    // Initialize the listener
    MyReservationRenewalListener myListener = new MyReservationRenewalListener();

    // Initialize the stateful service client
    StatefulServiceClient client = new StatefulServiceClient(DISPATCHER_HOST, DISPATCHER_EXT_PORT);

    // Register a reservation renewal listener
    client.register(RRLID, myListener);

Implementing the unregisterReservationRenewalListener(byte) method

To stop receiving Renew Reservation notifications, the client application must use the unregisterReservationRenewalListener method of the charging client. The client application must provide a ReservationRenewalListener identifier (rrlId). The rrlId value can be 1 to 127 included.

Code Snippet

The following code snippet provides an example of how to call the unregisterReservationRenewalListener() method of the charging client: 

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

    // Initialize the listener
    MyReservationRenewalListener myListener = new MyReservationRenewalListener();

    // Initialize the stateful service client
    StatefulServiceClient client = new StatefulServiceClient(DISPATCHER_HOST, DISPATCHER_EXT_PORT);

    // Unregister a reservation renewal listener
    client.register(RRLID);

Changing the Implementation of the Session-Based Charging APIs

In the implementation of the charging process of the service client, additional actions must be taken in the integration code when managing multiservice charging sessions.

On multiservice charging session start:

  • Specify that the session is monitored for renew reservation notifications by the reservation renewal listener identified by the given identifier. The method setReservationRenewalListenerId() of the operation should be used.
  • Optionally, add external data that the reservation renewal listener may need when processing the notification. The method setExternalData() of the operation should be used. This data is not read nor changed by SAP CC Server.

Code Snippet

    // Create a multiservice charging session start operation
    ISessionStartChargingOperation startOp = client.createSessionStartOperation(sessionID, userServiceID, serviceID, consumptionDate);

    // Add a charging session operation: reserve
    startOp.prepareReserve(reservationId, reservationItem, defaultResolution, ttl, propertyToInverse);

    // Indicate that this multiservice charging session is monitored for renew reservation notifications by the reservation renewal listener identified by the rrlId
    startOp.setReservationRenewalListenerId(rrlId);

    // (Optional) Add external data, that is sent back unchanged in the renew reservation notifications
    startOp.setExternalData(externalData);

    // Execute the start operation
    startOp.execute(sessionResultListener);

On multiservice charging session update:

  • Optionally, add external data that the reservation renewal listener may need when processing the notification. The method setExternalData() of the operation should be used. This data is not read nor changed by SAP CC Server.

Code Snippet

    // Create a multiservice charging session update operation
    ISessionUpdateChargingOperation updateOp = client.createSessionUpdateOperation(sessionID, userServiceID, serviceID, consumptionDate);

    // Add a charging session operation: confirm and reserve
    updateOp.prepareConfirmAndReserve(reservationId, confirmationItem, reservationItem);

    // (Optional) Add external data, that is sent back unchanged in the renew reservation notifications
    updateOp.setExternalData(externalData);

    // Execute the update operation
    updateOp.execute(sessionResultListener);

On multiservice charging session stop:

  • No additional action is necessary

Additional Information

Consult all the online and offline charging services that you can implement in your Java-based client application.

Consult the SAP CC Application Help for more information about the online charging services, the charging process and its execution modes.