17 Billing

17.2.1 Billable Actions and Billing System Interaction

This section describes billable actions and billing system interaction.

// Suppose your BillingContext Object is foo 
BillingController controller =  BillingController.getInstance(); 
if (controller.isBillingEnabled() ) 
 { 
       try { 
             BillingResult result = controller.preService(foo); 
            if ( result != null ){ 
               ServiceDetailRecord sdr = result.getServiceDetailRecord(); 
               if (result.getResultCode() != BillingResult.FAILED) { //Succeed 
                 // Add your logic here 
               } 
              else { // Failed 
                    // Add your logic here to handle preService failure 
                    //BillingException e = new BillingException(failure message); 
                    // e.setResult(result);
                    // throw e;
 
              } 
          } 
      } catch (BillingException be) { 
               //Handle Billing Execption here 
         } 

// Suppose your BillingContext Object is foo 
BillingController controller =  BillingController.getInstance(); 
if (controller.isBillingEnabled() ) 
 { 
       try { 
             BillingResult result = controller.postService(foo); 
            if ( result != null ){ 
               ServiceDetailRecord sdr = result.getServiceDetailRecord(); 
               if (result.getResultCode() != BillingResult.FAILED) { //Succeed 
                 // Add your logic here 
               } 
              else { // Failed 
                    // Add your logic here to handle postService failure 
              } 
          } 
      } catch (BillingException be) { 
               //Handle Billing Execption here
         } 

17.4.1 Default Billing Collector Implementation

The BillingCollector implementation object is responsible for processing the BillingContext for a given billable action. It generates an appropriate Service Detail Record for the billing driver to process. OracleAS Wireless includes a default BillingCollector implementation named BillingCollectorImpl which handles the following BillingContext objects:

• For multi-channel service access: oracle.panama.rt.ServiceContext

  • Extended Attribute Name:

    • SERVICE_URL—the URL of the service invoked

    • SERVICE_TYPE—the type of the service, that is, Folder or Link (FOLD, LINK)

    • DEVICE_NAME—the device name

    • INVOKER—the Invoker for this runtime service. The list of values include HTTP, ASYNC, ALERT, PROVISIONING, AGENT. This attribute can be used by the driver to trace the root-invoker of this service. The Invoker attribute and the list of values are defined in the BillingDataCollector Interface.

    • ASK_IN_MSGID—this is set if the service is the INVOKER attribute value ASYNC. The value denotes the Incoming message ID for the Async application. It can use used to relate the message request with the Async action.

• For J2ME application download: oracle.panama.model.UserDownloadStatusAPPLICATION_NAME

  • Extended Attribute Name:

    • CONTENT_NAME—the Application name

    • CONTENT_VERSION—the Content version

    • USER_DEVICE_NAME (if available)—the user device name

    • MIME_TYPE—the mime type downloaded

    • CURRENT_NUMBER_OF_DOWNLOADS—the number of previous downloads before the current download

    • CONTENT_SIZE—the size of the content

• For mobile alert subscription: oracle.panama.mobilealert.ServiceAlertSubscription

  • Extended Attribute Name:

    • OPERATION_TYPE—indicates if it is an Alert Message SDR or Alert Subscription SDR. The value for mobile alert is ALERT_SUBSCRIPTION

    • SERVICE_URL—URL for the invoked service. Alert Engine invokes a service to generate content, and this attribute is the URL for the service.

    • ALERT_DELIVERY_ADDR—the end-user address to which alerts will be delivered. A comma-separated list of possible addresses.

• For messaging:

  • Sending: oracle.panama.messaging.transport.impl.SendingBillingContext

  • Extended Attribute Name:

    • TYPE—indicates if the action is a sending or receiving action. It is set to S for sending.

    • FROM—the from address (can be null).

    • TO_ADDRESSES—the destination address.

    • DELIVERY_TYPE—the delivery channel type.

    • SERVICE_NAME (Optional)—the client name (such as Push Server, Async Agent).

    • DRIVER_NAME—the driver name (for the sending case only).

    • REPLYTO_ADDRESS—the reply to address.

    • CLIENT_NAME—the client that initializes the sending request.

    • MESSAGE_ID—the ID assigned to the message by the messaging server.

    • LINKED_MESSAGE_ID—the ID that links many independent transactions together. For example, an Async transaction and message sending transaction. Other transactions may assign a different name to this attribute.

  • Receiving: oracle.panama.messaging.transport.impl.ReceivingBillingContext

  • Extended Attribute Name:

    • TO_ADDRESS—the destination address of this message.

    • DELIVERY_TYPE—the delivery channel type.

    • CLIENT_NAME—the reply to address.

    • MESSAGE_ID—the ID assigned to the message by the messaging server.

17.4.2 Service Detail Record ID Versus Billing Reference ID

The Service Detail Record ID is defined by the Billing Collector. The default format is [Component Name: Random Key]. The Billing Reference ID is obtained from the billing system. In the pre-bill case, it is usually defined as the authorization ID.

17.4.3 Extend Default Billing Collector

OracleAS Wireless billing integration framework enables users to extend the default billing collector implementation for various reasons:

• To capture more data than the default implementation for a default BillingContext, see Example 17-3.

public class MyBillingCollector extends oracle.wireless.billing.BillingDataCollectorImpl 
{ 
   ... 
    public ServiceDetailRecord createServiceDetailRecord(BillingContext context) 
   { 
       ServiceDetailRecord sdr = null; 
        if (context instanceof oracle.panama.rt.ServiceContext ){ 
            sdr = super.createServiceDetailRecord(context); 
           if ( sdr != null){ 
             // Add your additional data capture logic here 
            // For example: 
           // oracle.panama.rt.ServiceContext serviceContext = (oracle.panama.rt.ServiceContext)context; 
           // sdr.setExtendedData("SERVICE_PATHURL", context.getService().getURLPathParameter()); 
         } 
       } 
       else{ 
          sdr = super.createServiceDetailRecord(context); 
      } 
      return sdr; 
   } 
  ... 
}

• To capture data from a custom BillingContext, see Example 17-4.

public class MyBillingCollector extends oracle.wireless.billing.BillingDataCollectorImpl 
{ 
   ... 
    public ServiceDetailRecord createServiceDetailRecord(BillingContext context) 
   { 
       ServiceDetailRecord sdr = null; 
        if (context instanceof MyBillingContext ){ 
             // MyBillingContext mycontext = (MyBillingContext)context; 
            // get the user name from your context 
            // Java.sql.Timestamp accessTime = null; 
            // BillingManager manager = BillingManager.getInstance(); 
            //sdr = manager.createServiceDetailRecord(<User Name>, <Your service Name>, accessTime, <your billing component name>); 
           // sdr.setExtendedData("MY_DATA", <Get data from your context object>); 
           ... 
         } 
       } 
       else{ 
          sdr = super.createServiceDetailRecord(context); 
      } 
      return sdr; 
   } 
  ... 
} 

To ignore a billable action base on the context data. Simply return a null object from the createServiceDetailRecord call based on your business logic.

Specify your extended Billing Collector using Oracle Enterprise Manager:

EM > Wireless Server: Site Administration > Billing Framework > Billing Collector Class name

17.4.4 Maintaining Transaction Context on Multipart Requests

A typical wireless request spans multiple entities (a multi-part request). For example, an Async request may originate at the Messaging Server, forwarded to the Async Listener, which invokes a Runtime service and then returns the result back to the user through the Messaging Server. The Billing Rules may demand a billing at each stage of the transaction, but the pricing may vary depending on the context of the request. To support such a scenario, it is necessary to maintain the history of the request's path (available resources to the Billing Driver [or Data Collector]), where the Billing Rules are enforced.

When the request changes, the transaction must be reset by the driver in the pre-service. The default billing collector implementation stores transaction ID information as a thread local variable, and caches it in the thread unless reset. For example, in the Async Servlet case, since subsequent requests are also processed in the context of the same thread, the Async servlet retains the previous transaction ID, unless it is reset by the collector or driver. In a typical scenario, an psych request arrives through the messaging layer. In order for the billing layer to link this messaging request with the Async request and the subsequent messaging response, the message ID is carried forward. The MESSAGE_ID extended attribute of the incoming message should match the ASK_IN_MSGID of the Async request and this should match the LINKED_MESSAGE_ID attribute of the outgoing message. This is how the incoming message ID is carried forward when the request is serviced.

           BillingTransaction Trans = BillingTransactionManager.getInstance().createTransaction();
          Trans.getId(); // if its XYZ say       
           sdr.setTransaction(Trans);

            BillingTransaction Trans = BillingTransactionManager.getInstance().lookupTransaction (XYZ);
          Trans.getId(); // if its XYZ say       
          Trans.addSdr(sdr); // OR sdr.setTransaction(Trans);

  /**
   * Returns the current billing transaction
   * @return BillingTransaction the current billing transaction
   */
public BillingTransaction getCurrentTransaction();

/** Sets the transaction for the current transaction
 * @param transaction the current transaction
 */
public void setCurrentTransaction(BillingTransaction transaction);

17.6.1 Handling Prebilling

Here is an implementation example of handling prebilling:

• Define the billable actions using either default or custom actions.

• Use the driver's preService call to do billing authorization and/or resource reservation, return an authorization ID generated by the billing system.

• Use the driver's postService call to complete the billing transaction by passing the authorization obtained from the preService call.

17.6.2 Handling Postbilling

Here is an implementation example of handling postbilling:

• Define the billable actions using either default or custom actions.

• Use the driver's preService call to do billing authorization and/or rating/fraud detection.

• Use the driver's postService call to submit billing-related data to the billing system.