org.mobicents.csapi.jr.slee.cs
Interface IpChargingSessionConnection

All Superinterfaces:

IpServiceConnection

public interface IpChargingSessionConnection
extends IpServiceConnection

The Charging Session interface provides operations to facilitate transactions between a merchant and a user. The application programmer can use this interface to debit or credit amounts and/or units towards a user, to create and extend the lifetime of a reservation and to get information about what is left of the reservation. This interface shall be implemented by a Charging SCF. As a minimum requirement, the release() method shall be implemented. If the reserveAmountReq() method is implemented, at least one of the debitAmountReq() or the creditAmountReq() methods shall also be implemented. If the reserveUnitReq() method is implemented, at least one of the debitUnitReq() or the creditUnitReq() methods shall also be implemented. If neither the reserveAmountReq() nor the reserveUnitReq() method is implemented, then at least one of the directDebitAmountReq() or the directDebitUnitReq(), or the directCreditAmountReq(), or the directCreditUnitReq() methods shall be implemented.

Method Summary

void	creditAmountReq(TpApplicationDescription applicationDescription, TpChargingPrice amount, boolean closeReservation, int requestNumber) This method credits an amount towards the reservation associated with the session.
void	creditUnitReq(TpApplicationDescription applicationDescription, TpVolume[] volumes, boolean closeReservation, int requestNumber) This method credits a volume of application usage towards the reservation.
void	debitAmountReq(TpApplicationDescription applicationDescription, TpChargingPrice amount, boolean closeReservation, int requestNumber) This method debits an amount from the reservation.
void	debitUnitReq(TpApplicationDescription applicationDescription, TpVolume[] volumes, boolean closeReservation, int requestNumber) This method debits a volume of application usage from the reservation.
void	directCreditAmountReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpChargingPrice amount, int requestNumber) This method directly credits an amount towards the user.
void	directCreditUnitReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpVolume[] volumes, int requestNumber) This method directly credits a volume of application usage towards the user.
void	directDebitAmountReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpChargingPrice amount, int requestNumber) This method directly debits an amount towards the user.
void	directDebitUnitReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpVolume[] volumes, int requestNumber) This method directly credits a volume of application usage towards the user.
void	extendLifeTimeReq() With this method an application can request the lifetime of the reservation to be extended.
TpChargingPrice	getAmountLeft() With this method an application can request the remaining amount of the reservation.
int	getLifeTimeLeft() With this method an application can request the remaining lifetime of the reservation.
TpVolume[]	getUnitLeft() With this method an application can request the remaining amount of the reservation.
void	rateReq(TpChargingParameter[] chargingParameters) This method is used when the application wants to have an item rated by the charging service.
void	release(int requestNumber) This method releases the session, no operations can be done towards this session anymore (not even retries).
void	reserveAmountReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpChargingPrice preferredAmount, TpChargingPrice minimumAmount, int requestNumber) This method is used when an application wants to reserve an amount of money for services to be delivered to a user.
void	reserveUnitReq(TpApplicationDescription applicationDescription, TpChargingParameter[] chargingParameters, TpVolume[] volumes, int requestNumber) This method is used when an application wants to reserve volumes of application usage to be delivered to a user in the session.

Methods inherited from interface org.mobicents.csapi.jr.slee.IpServiceConnection

closeConnection

Method Detail

creditAmountReq

void creditAmountReq(TpApplicationDescription applicationDescription,
                     TpChargingPrice amount,
                     boolean closeReservation,
                     int requestNumber)
                     throws TpCommonExceptions,
                            P_INVALID_AMOUNT,
                            P_INVALID_CURRENCY,
                            P_INVALID_REQUEST_NUMBER,
                            javax.slee.resource.ResourceException

This method credits an amount towards the reservation associated with the session. The amount left in the reservation will be increased by this amount. Each request to debit / credit an amount towards a reservation is handled separately. For example, two requests for a payment of EUR 1,- will give a total payment of EUR 2,-. A credit of EUR 1,- and a debit of EUR 1 will give a total payment of EUR 0,-.

Parameters:

amount - The amount of specified currency to be credited towards the user.

closeReservation - If set to true, this parameter indicates that the remaining part of the reservation can be freed. This may also mean addition of currency to the subscriber's account if more credits than debits have been made. The session is not released, this has to be done explicitly by calling the release() method.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_AMOUNT

P_INVALID_CURRENCY

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

creditUnitReq

void creditUnitReq(TpApplicationDescription applicationDescription,
                   TpVolume[] volumes,
                   boolean closeReservation,
                   int requestNumber)
                   throws TpCommonExceptions,
                          P_INVALID_VOLUME,
                          P_INVALID_REQUEST_NUMBER,
                          javax.slee.resource.ResourceException

This method credits a volume of application usage towards the reservation. The volumes left in the reservation of this will be increased by this amount. Each request to debit / credit a volume towards a reservation is handled separately. For example, two requests for a payment for 10 kilobytes will give a total payment for 20 kilobytes

Parameters:

volumes - Specifies the credited volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.

closeReservation - If set to true, this parameter indicates that the reservation can be freed. The session is not released, this has to be done explicitly by calling the release() method.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_VOLUME

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

debitAmountReq

void debitAmountReq(TpApplicationDescription applicationDescription,
                    TpChargingPrice amount,
                    boolean closeReservation,
                    int requestNumber)
                    throws TpCommonExceptions,
                           P_INVALID_AMOUNT,
                           P_INVALID_CURRENCY,
                           P_INVALID_REQUEST_NUMBER,
                           javax.slee.resource.ResourceException

This method debits an amount from the reservation. The amount left in the reservation will be decreased by this amount. Each request to debit / credit an amount towards a reservation is handled separately. For example, two requests for a payment of EUR 1,- will give a total payment of EUR 2,-. A credit of EUR 1,- and a debit of EUR 1 will give a total payment of EUR 0,-. When a debit operation would exceed the limit of the reservation, the debit operation fails.

Parameters:

amount - The amount of specified currency to be debited from the user.

closeReservation - If set to true, this parameter indicates that the reservation can be freed. The session is not released, this has to be done explicitly by calling the release() method.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_AMOUNT

P_INVALID_CURRENCY

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

debitUnitReq

void debitUnitReq(TpApplicationDescription applicationDescription,
                  TpVolume[] volumes,
                  boolean closeReservation,
                  int requestNumber)
                  throws TpCommonExceptions,
                         P_INVALID_VOLUME,
                         P_INVALID_REQUEST_NUMBER,
                         javax.slee.resource.ResourceException

This method debits a volume of application usage from the reservation. The volumes left in the reservation will be decreased by this amount. Each request to debit / credit a volume towards a reservation is handled separately. For example, two requests for a payment for 10 kilobytes will give a total payment for 20 kilobytes. When a debit operation would exceed the limit of the reservation, the debit operation succeeds, and the debited volumes will be the rest of the volumes in the reservation.

Parameters:

volumes - Specifies the charged volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.

closeReservation - If set to true, this parameter indicates that the reservation can be freed. The session is not released, this has to be done explicitly by calling the release() method.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_VOLUME

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

directCreditAmountReq

void directCreditAmountReq(TpApplicationDescription applicationDescription,
                           TpChargingParameter[] chargingParameters,
                           TpChargingPrice amount,
                           int requestNumber)
                           throws TpCommonExceptions,
                                  P_INVALID_AMOUNT,
                                  P_INVALID_CURRENCY,
                                  P_INVALID_REQUEST_NUMBER,
                                  javax.slee.resource.ResourceException

This method directly credits an amount towards the user. A possible reservation associated with this session is not influenced.

Parameters:

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

amount - The amount of specified currency to be credited towards the user.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_AMOUNT

P_INVALID_CURRENCY

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

directCreditUnitReq

void directCreditUnitReq(TpApplicationDescription applicationDescription,
                         TpChargingParameter[] chargingParameters,
                         TpVolume[] volumes,
                         int requestNumber)
                         throws TpCommonExceptions,
                                P_INVALID_VOLUME,
                                P_INVALID_REQUEST_NUMBER,
                                javax.slee.resource.ResourceException

This method directly credits a volume of application usage towards the user. The volumes in a possible reservation associated with this session are not influenced.

Parameters:

sessionID - The ID of the reservation.

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

volumes - Specifies the credited volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_VOLUME

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

directDebitAmountReq

void directDebitAmountReq(TpApplicationDescription applicationDescription,
                          TpChargingParameter[] chargingParameters,
                          TpChargingPrice amount,
                          int requestNumber)
                          throws TpCommonExceptions,
                                 P_INVALID_AMOUNT,
                                 P_INVALID_CURRENCY,
                                 P_INVALID_REQUEST_NUMBER,
                                 javax.slee.resource.ResourceException

This method directly debits an amount towards the user. A possible reservation associated with this session is not influenced.

Parameters:

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

amount - The amount of specified currency to be debited from the user.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_AMOUNT

P_INVALID_CURRENCY

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

directDebitUnitReq

void directDebitUnitReq(TpApplicationDescription applicationDescription,
                        TpChargingParameter[] chargingParameters,
                        TpVolume[] volumes,
                        int requestNumber)
                        throws TpCommonExceptions,
                               P_INVALID_VOLUME,
                               P_INVALID_REQUEST_NUMBER,
                               javax.slee.resource.ResourceException

This method directly credits a volume of application usage towards the user. The volumes in a possible reservation associated with this session are not influence.

Parameters:

sessionID - The ID of the reservation.

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

volumes - Specifies the charged volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_VOLUME

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

extendLifeTimeReq

void extendLifeTimeReq()
                       throws TpCommonExceptions,
                              javax.slee.resource.ResourceException

With this method an application can request the lifetime of the reservation to be extended. If no reservation has been made on the charging session, this method raises an exception (P_TASK_REFUSED).

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

getAmountLeft

TpChargingPrice getAmountLeft()
                              throws TpCommonExceptions,
                                     javax.slee.resource.ResourceException

With this method an application can request the remaining amount of the reservation.

Returns:

amountLeft: Gives the amount left in the reservation.

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

getLifeTimeLeft

int getLifeTimeLeft()
                    throws TpCommonExceptions,
                           javax.slee.resource.ResourceException

With this method an application can request the remaining lifetime of the reservation. If no reservation has been made on the charging session, this method raises an exception (P_TASK_REFUSED).

Returns:

reservationTimeLeft: Indicates the number of seconds that the session remains valid.

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

getUnitLeft

TpVolume[] getUnitLeft()
                       throws TpCommonExceptions,
                              javax.slee.resource.ResourceException

With this method an application can request the remaining amount of the reservation.

Returns:

volumesLeft: Specifies the remaining volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

rateReq

void rateReq(TpChargingParameter[] chargingParameters)
             throws TpCommonExceptions,
                    javax.slee.resource.ResourceException

This method is used when the application wants to have an item rated by the charging service. The result can be used to present pricing information to the end-user before the end-user actually wants to start using the service.

Parameters:

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

release

void release(int requestNumber)
             throws TpCommonExceptions,
                    P_INVALID_REQUEST_NUMBER,
                    javax.slee.resource.ResourceException

This method releases the session, no operations can be done towards this session anymore (not even retries). Unused parts of a reservation are freed.

Parameters:

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session.

Throws:

TpCommonExceptions

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

reserveAmountReq

void reserveAmountReq(TpApplicationDescription applicationDescription,
                      TpChargingParameter[] chargingParameters,
                      TpChargingPrice preferredAmount,
                      TpChargingPrice minimumAmount,
                      int requestNumber)
                      throws TpCommonExceptions,
                             P_INVALID_AMOUNT,
                             P_INVALID_CURRENCY,
                             P_INVALID_REQUEST_NUMBER,
                             javax.slee.resource.ResourceException

This method is used when an application wants to reserve an amount of money for services to be delivered to a user. It is also possible to enlarge the existing amount reservation by invoking this method. If a reservation is extended, the lifetime of the reservation is re-initialized.

Parameters:

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff.

preferredAmount - The amount of specified currency that the application wants to be reserved.

minimumAmount - The minimum amount that can be used by the application if the preferred amount cannot be granted.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_AMOUNT

P_INVALID_CURRENCY

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException

reserveUnitReq

void reserveUnitReq(TpApplicationDescription applicationDescription,
                    TpChargingParameter[] chargingParameters,
                    TpVolume[] volumes,
                    int requestNumber)
                    throws TpCommonExceptions,
                           P_INVALID_VOLUME,
                           P_INVALID_REQUEST_NUMBER,
                           javax.slee.resource.ResourceException

This method is used when an application wants to reserve volumes of application usage to be delivered to a user in the session. When using units it is assumed that the price setting for the units is handled by the network side services. It is also possible to enlarge the existing unit reservation by invoking this method.

Parameters:

chargingParameters - These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff..

volumes - Specifies the reserved volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit. It is e.g. possible to make a reservation for 10 000 octets and 5 charging units.

requestNumber - Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.

Throws:

TpCommonExceptions

P_INVALID_VOLUME

P_INVALID_REQUEST_NUMBER

javax.slee.resource.ResourceException