Features use the Charging Manager component to create one or more charging instances during a session. Each charging instance represents a charging conversation with an Online Charging System (OCS).

Tip See Sentinel Charging Manager for an overview of the Charging Manager.

Accessing a Charging Manager

A feature gets a reference to a ChargingManager from the feature endpoint. For example:

final ChargingManager chargingManager = getCaller().getChargingManager();
// use the charging manager ...
Tip It is safe for a feature to store a reference to the ChargingManager in a Java attribute.

Using the Charging Manager

The Charging Manager interface defines operations for creating two types of ChargingInstance:

  1. ReservationChargingInstance createReservationInstance(String name) — creates a charging instance suitable for scenarios where unit reservation is appropriate, such as SCUR and ECUR.

  2. ImmediateChargingInstance createImmediateChargingInstance(String name) — creates a charging instance suitable for scenarios where immediate charging is appropriate, such as IEC.

Each ChargingInstance has a unique name that is provided at the time the instance is created. The ChargingManager interface also defines operations for accessing a charging instance by name and for getting a collection of all charging instances known by the ChargingManager.

Warning The Charging Manager throws a DuplicateNameException if you try to create a new charging instance with the same name as an existing charging instance.

For example:

package com.opencloud.sentinel.charging;

import java.util.Collection;

public interface ChargingManager {

    /** ChargingManager component type value, used in {@link FailedInstruction}. */
    String COMPONENT_TYPE_NAME = "ChargingManager";

    /** ChargingManager component name key, used in {@link FailedInstruction}. */
    String COMPONENT_NAME_KEY = "ChargingInstance";

    /** Request Type key, used in {@link FailedInstruction}. */
    String REQUEST_TYPE_KEY = "requestType";

    /**
     * Create a new ReservationChargingInstance in the ChargingManager. This instance can be
     * used for Session Charging with Unit Reservation, and Event Charging with Unit Reservation.
     * @param name the name must be unique for this Sentinel session.  Names are case sensitive.
     * @return created event charging instance.
     * @throws DuplicateNameException If charging instance already exists with the supplied name.
     */
   ReservationChargingInstance createReservationInstance(String name)
            throws DuplicateNameException;

    /**
     * Create a new Immediate Charging Instance in the ChargingManager.
     * @param name the name must be unique for this Sentinel session.  Names are case sensitive.
     * @return created immediate charging instance.
     * @throws DuplicateNameException If charging instance already exists with the supplied name.
     */
   ImmediateChargingInstance createImmediateChargingInstance(String name)
            throws DuplicateNameException;

   /**
    * Determine the charging instance which the ChargingManager holds for a name for this session
    * or null if there is no such instance.
    * @param name Unique name associated with the {@link ChargingInstance}.
    * @return ChargingInstance associated with given name or null if no such instance.
    */
   ChargingInstance getChargingInstance(String name);

   /**
    * Returns Collection of managed Charging Instances for this Sentinel Session.
    * @return Collection of {@link ChargingInstance}s.
    */
   Collection<ChargingInstance> getChargingInstances();
}
Note The first release implementation of the Charging Manager supports one charging instance per session. This limitation will be removed in a subsequent release of Sentinel, so all possible approaches to charging a session will be supported.

Charging instances

There are two types of charging instance:

  1. ReservationChargingInstance — used for scenarios where unit reservation is appropriate, such as SCUR and ECUR

  2. ImmediateChargingInstance — used for scenarios where immediate charging is appropriate, such as IEC.

Behaviour common to both types is defined by the ChargingInstance interface.

Charging instance interface

The charging instance interface defines behaviour that is common to ReservationChargingInstance and ImmediateChargingInstance.

Operations Purpose 
 getName()

Each charging instance has a name that is unique within the scope of the ChargingManager.

 
 getChargingType()

Each charging instance has a type (defined by: enum ChargingType).

 
 getChargingState()

A charging instance is in a state that corresponds to a step in the charging process (defined by: enum State).

 
 getSessionCounters()

A charging instance has an associated SessionCounters instance.

Note See New Session Counters to learn more about session counters and how they are used. 
 getPendingChargingInstruction()
clearInstruction()

Determine if there are any pending charging instructions for the charging instance (defined by: enum Instruction).

 
 getPendingReportingReason()

Determine if this charging instance has any pending reporting reason.

 
 suspend()
resume()
isSuspended()

Charging may be suspended and is later resumed.

 
 isCreditCheckInProgress()

Determine if a credit check is in progress in the charging session managed by the charging instance.

For example:

package com.opencloud.sentinel.charging;

import com.opencloud.sentinel.charging.sessioncounters.SessionCounters;
import org.jainslee.resources.diameter.ro.types.vcb0.ReportingReason;

public interface ChargingInstance {

    enum Instruction { None, CreditReservation, CreditFinalisation, DirectDebit, Refund }
    enum ChargingType { Reservation, Immediate }

    /**
     * Represents the current state of a ChargingInstance, an instance is in the
     * Initial state prior to processing CCA-I, Mid state after processing CCA-I
     * and Final state after credit finalisation is instructed.
     */
    enum State { Initial, Mid, Final }

    /**
     * Returns the name assigned to the charging instance, must be unique for the Charging
     * manager instance.
     * @return Unique name for this charging instance.
     */
    String getName();

    /**
     * The type of charging instance
     * @return ChargingType for this charging instance.
     */
    ChargingType getChargingType();

    /**
     * The current state of charging instance
     * @return State for this charging instance.
     */
    State getChargingState();

    /**
     * SessionCounters for the charging instance.
     * @return SessionCounters for this charging instance.
     */
    SessionCounters getSessionCounters();

    /**
     * Determine if this charging instance has any pending charging instruction.
     * @returns pending instruction.
     */
    Instruction getPendingChargingInstruction();

    /**
     * Determine if this charging instance has any pending reporting reason.
     * @returns reporting reason.
     */
    ReportingReason getPendingReportingReason();

    /**
     * Clears any pending charging instruction
     */
    void clearInstruction();

    /**
     * The SuspensionStartTime field for all counters in this instance will be set to the
     * current time.
     */
    void suspend();

    /**
     * On calling resume all session counters associated with this charging instance will
     * have the cumulativeSuspendedDuration field updated if autoUpdateCounters is true.
     *
     * @param autoUpdateCounters false if intending to manually update
     *        cumulativeSuspendedDuration, true for automatic updating of
     *        cumulativeSuspendedDuration in all associated session counters
     */
    void resume(boolean autoUpdateCounters);

    /**
     * Returns true iff this ChargingInstance is currently suspended.
     * @return true iff this ChargingInstance is currently suspended.
     */
    boolean isSuspended();

    /**
     * Indicates whether or not there is a credit check currently in progress.  This
     * generally means that a CCA is pending.
     * @return true iff there is a credit check currently in progress.
     */
    boolean isCreditCheckInProgress();
}

ReservationChargingInstance interface

The ReservationChargingInstance interface extends ChargingInstance and adds operations for charging with unit reservation (SCUR and ECUR).

Operations Purpose 
 doCreditReservation

Initiate a credit reservation, send an update, or perform a re-authorisation.

 
 doCreditFinalisation

Finalise the current charging session if a session is active.

For example:

package com.opencloud.sentinel.charging;

import org.jainslee.resources.diameter.ro.types.vcb0.ReportingReason;

public interface ReservationChargingInstance extends ChargingInstance {

    public enum CreditResultExecutionPhase { Initial, Mid }

    /**
     * Instructs the charging instance to initiate a credit reservation, send an update or
     * perform a reauthorisation
     * @param reason Reason for credit reservation.
     * @param phase The phase in which the Post CC execution point should be raised
     * @throws InstructionAlreadyPendingException if there is already an instruction pending
     * @throws ChargingInstanceAlreadyFinalisedException if the charging instance is already
     *         finalised.
     * @throws CreditCheckAlreadyInProgressException if there is already a credit check in
     *         progress
     */
    void doCreditReservation(ReportingReason reason, CreditResultExecutionPhase phase)
                            throws InstructionAlreadyPendingException,
                                   ChargingInstanceAlreadyFinalisedException,
                                   CreditCheckAlreadyInProgressException;

    /**
     * Instructs the charging instance to initiate a credit reservation, send an update or
     * perform a reauthorisation
     * @param phase The phase in which the Post CC execution point should be raised
     * @throws InstructionAlreadyPendingException if there is already an instruction pending
     * @throws ChargingInstanceAlreadyFinalisedException if the charging instance is already
     *         finalised.
     * @throws CreditCheckAlreadyInProgressException if there is already a credit check in
     *         progress
     */
    void doCreditReservation(CreditResultExecutionPhase phase)
                            throws InstructionAlreadyPendingException,
                                   ChargingInstanceAlreadyFinalisedException,
                                   CreditCheckAlreadyInProgressException;

    /**
     * Instructs the core to finalise the current charging session if a session is active,
     * and call the feature if response-CCA arrives.
     * @param reason Reason for credit finalisation.
     * @throws InstructionAlreadyPendingException if there is already an instruction pending
     * @throws ChargingInstanceAlreadyFinalisedException if the charging instance is already
     *         finalised.
     * @throws CreditCheckAlreadyInProgressException if there is already a credit check in
     *         progress.
     */
    void doCreditFinalisation(ReportingReason reason)
                            throws InstructionAlreadyPendingException,
                                   ChargingInstanceAlreadyFinalisedException,
                                   CreditCheckAlreadyInProgressException;
}
Note For examples of system features that use a ReservationChargingInstance see Sentinel B2BUA ECUR Featuresand Sentinel B2BUA SCUR Features.

ImmediateChargingInstance interface

The ImmediateChargingInstance interface extends ChargingInstance and adds operations for immediate charging (IEC).

Operations Purpose 
 doDirectDebit()

Perform a direct debit.

 
 doRefund()

Perform a refund.

For example:

package com.opencloud.sentinel.charging;

import com.opencloud.sentinel.charging.ReservationChargingInstance.CreditResultExecutionPhase;

public interface ImmediateChargingInstance extends ChargingInstance {

    /**
     * Instructs the core to perform a direct debit and deliver the response CCA to the
     * feature on arrival.
     * @throws InstructionAlreadyPendingException
     * @throws CreditCheckAlreadyInProgressException
     */
    void doDirectDebit(CreditResultExecutionPhase phase)
                        throws InstructionAlreadyPendingException,
                               CreditCheckAlreadyInProgressException;

    /**
     * Instructs the core to perform a refund and call the feature if response-CCA arrives
     * @throws InstructionAlreadyPendingException
     * @throws CreditCheckAlreadyInProgressException
     */
    void doRefund(CreditResultExecutionPhase phase)
                        throws InstructionAlreadyPendingException,
                               CreditCheckAlreadyInProgressException;
}
Note For examples of system features that use an ImmediateChargingInstance see Sentinel B2BUA IEC Features.
Previous page Next page