12 About the ECE Sample Programs

This chapter describes how to use the sample programs included in the Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE) SDK to call the ECE APIs.

About the Sample Programs

ECE SDK includes a set of sample programs that demonstrate how to use the ECE API for sending requests to ECE.

You use these sample programs in the following ways:

  • Use the sample programs as code samples for calling the ECE APIs.

  • Use the sample programs as code samples for writing custom applications.

  • Run sample programs to send requests to ECE and receive responses.

    The sample programs print information about the messages exchanged.

  • Use the sample program scripts to get an idea of the configuration and dependencies that are required for integrating the ECE client into your build system (Maven, Ant, and so on).

Look at the sample program source to see how the program works. For example, if you want to write a program that sends a unit-based debit request to ECE, examine the SampleDebitRefund sample program source to:

  • View the methods to use in your code.

  • How to use the libraries and calls.

The samples are supported on the Linux and Oracle Solaris platforms. Compile the sample programs using the shell script provided for each sample program. See "Compiling and Running the Sample Programs" for more information.

Finding the Sample Programs

The SDK sample programs are found in the ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk directory.

Table 12-1 shows the ECE SDK software directory structure: ECE_home is the directory in which ECE Server software is installed.

Table 12-1 Elastic Charging Engine Sample Program Directories

Directory Description

ECE_home/ocecesdk/bin

Directories that contain shell scripts for compiling and running various types of sample programs.

ECE_home/ocecesdk/bin/extensions

Shell scripts for extension-implementation sample programs.

ECE_home/ocecesdk/bin/notification

Shell scripts for notification sample programs.

ECE_home/ocecesdk/bin/plugin

Shell scripts for BrmCdrPluginDirect plug-in sample programs.

ECE_home/ocecesdk/bin/policy

Shell scripts for policy sample programs.

ECE_home/ocecesdk/bin/query

Shell scripts for query sample programs.

ECE_home/ocecesdk/bin/update

Shell scripts for update sample programs.

ECE_home/ocecesdk/bin/usage

Shell scripts for usage sample programs.

ECE_home/ocecesdk/config

Configuration files common to all sample programs.

ECE_home/ocecesdk/config/extensions

Configuration files for extension-implementation sample programs.

ECE_home/ocecesdk/source

Note: The full path showing the Java project directory structure to the sample programs is:

ECE_home/ocecesdk/source/oracle/communication/
brm/charging/sdk

All Java sample programs.

ECE_home/ocecesdk/source/.../sdk/extensions

Source files for extension-implementation sample programs (for pre-request-processing and post-request-processing).

Includes the data loader used for extensions.

ECE_home/ocecesdk/source/.../sdk/notification

Source files for notification sample programs.

ECE_home/ocecosdk/source/.../sdk/plugin

Source files for BrmCdrPluginDirect plug-in sample programs.

ECE_home/ocecesdk/source/.../sdk/policy

Source files for policy sample programs.

ECE_home/ocecesdk/source/.../sdk/query

Source files for query sample programs.

ECE_home/ocecesdk/source/.../sdk/update

Source files for update sample programs.

ECE_home/ocecesdk/source/.../sdk/usage

Source files for usage sample programs.

Descriptions of the Sample Programs

Each sample program includes these supporting files:

  • Source files to view or modify for your own applications

  • Shell scripts to compile and run the sample programs

The sample programs use the generic .ecc script sdk_production_loader.ecc.

All of the sample programs can work with the ready-to-use sample data included with the ECE Server software installation (the sample data you load using ECE data-loading utilities).

Note:

The ECE sample programs do not work well with data you load using the simulator loader utility.

The following tables list the sample programs, the .ecc script that applies to each, the shell script that complies and runs the sample program, and the description of the sample program.

For descriptions of the methods the sample programs use, see the documentation for oracle.communication.brm.charging.sdk in BRM Elastic Charging Engine Java API Reference.

Table 12-2 lists the usage sample programs.

Table 12-2 ECE Sample Programs for Usage Requests

Sample Program ECC Script Shell Script Description

SampleAccountingOnOff

sdk_production_loader.ecc

sample_accounting_on_off.sh

Simulates an accounting on/off request being sent from the mediation client.

SampleDataSession

sdk_production_loader.ecc

sample_data_session.sh

Simulates a simple data session, including an INITIATE, an UPDATE, and a TERMINATE request.

SampleDebitRefundSession

-

sample_debit_refund_session.sh

Shows how to send debit and refund requests with multiple values in unit-based and amount-based mode.

See "Usage Example for SampleDebitRefundSession".

SampleGenericSession

-

sample_generic_session.sh

Simulates any kind of voice or data session.

SampleGprsSession

-

sample_gprs_session.sh

Simulates a GPRS session.

SampleIncrementalUsageRequestLauncher

sdk_production_loader.ecc

sample_incremental_usage_request.sh

Simulates a voice session with incremental mode.

SampleMultipleServicestLauncher

sdk_production_loader.ecc

sample_multiple_service.sh

Shows how to send usage requests for the Multiple Services Credit Control (MSCC) case (multiple sub-requests are sent in a single usage request).

SamplePriceEnquiry

sdk_production_loader.ecc

sample_price_enquiry.sh

Sends a price enquiry request.

SampleReAuthRequest

sdk_production_loader.ecc

sample_RAR.sh

Sample program that shows the generation of reauthorization request (RAR) messages.

Also shows how to consume notification messages. This portion of the code is for illustration only and is disabled.

SampleStartUpdateAccountingRequestLauncher

-

sample_start_update_accounting_request.sh

Simulates a sample usage session including a START_ACCOUNTING, UPDATE_ACCOUNTING, and TERMINATE request. For example, a usage session for a DSL data download in a postpaid scenario.

SampleUsageRequestLauncher

sdk_production_loader.ecc

sample_usage_request.sh

Allows you to send custom voice usage requests.

Customer ID, number of requests to send, request type (INITITATE/UPDATE...) and duration must be given as arguments (for example, sample_usage_request.sh run 6500000000 2 TERMINATE 120).

SampleVoiceSession

sdk_production_loader.ecc

sample_voice_session.sh

Simulates a simple voice session, including an INITIATE, an UPDATE, and a TERMINATE request.

Table 12-3 lists the update sample programs.

Table 12-3 ECE Sample Programs for Update Requests

Sample Program ECC Script Shell Script Description

SampleExternalTopUpRequestLauncher

-

sample_external_topup_notification_request.sh

Shows how third- party systems can perform direct top ups in ECE.

Table 12-4 lists the policy sample programs.

Table 12-4 ECE Sample Programs for Policy Requests

Sample Program ECC Script Shell Script Description

SamplePolicySessionRequestLauncher

-

sample_policy_session_request.sh

Simulates a policy session.

Shows how to send a policy request to ECE that requests both Sp and Sy information.

SampleSpendingLimitReportRequestLauncher

-

sample_spending_limit_report_request.sh

Simulates a policy Sy query request.

Shows how to send a request to retrieve policy counter status information.

SampleSubscribeNotificationRequestLauncher

-

sample_subscribe_notification_request.sh

Simulates a policy Sp query request.

Shows how to send a request to retrieve the value for a specified set of subscriber preferences and subscribe for receiving notifications when the values of the preferences change. For example, shows how to retrieve the channel a subscriber prefers for receiving policy-related notifications (SMS or email) or the language in which the subscriber prefers the notification to be written (French, English).

SampleSubscriberPreferenceUpdateRequestLauncher

-

sample_subscriber_preference_update_request.sh

Simulates a policy-related update request.

Shows how to update the subscriber preferences in ECE.

SampleUserDataRequestLauncher

-

sample_user_data_request.sh

Simulates a policy Sp query request without subscription.

Shows how to send a request to retrieve the values for subscriber preferences that are configured for the product of a customer.

Table 12-5 lists the query sample programs.

Table 12-5 ECE Sample Programs for Query Requests

Sample Program ECC Script Shell Script Description

SampleAuthenticationQuery

sdk_production_loader.ecc

sample_auth_query_request.sh

Sends an authentication query request.

SampleBalanceQueryRequestLauncher

sdk_production_loader.ecc

sample_balance_query_request.sh

Sends a balance query request.

Table 12-6 lists the extension sample programs.

Table 12-6 ECE Sample Programs for Extension Implementations

Sample Program ECC Script Shell Script Description

-

-

sample_extensions_loader

Data loader for extension implementations

-

-

build_deploy_extension

Sample extension implementation

-

-

tax_configuration.spec

Sample extension implementation

-

-

tax_configuration_data.csv

Sample extension implementation

Table 12-7 lists the notifications sample programs.

Table 12-7 ECE Sample Programs for Notifications

Sample Program ECC Script Shell Script Description

SampleDurableJmsClient

-

sample_durable_jms_client.sh

Simulates a durable JMS client

SampleJmsClient

-

sample_jms_client.sh

Simulates a JMS client

SampleJmsServer

-

sample_jms_server.sh

Simulates a JMS server

Table 12-8 lists the custom plug-in sample programs.

Table 12-8 ECE Sample Programs for Custom Plug-in

Sample Program ECC Script Shell Script Description

SampleRatedEventFormatterCustomPlugin

-

build_deploy_plugin.sh

Builds and deploys the sample plug-in SampleRatedEventFormatterCustomPlugin.

Compiling and Running the Sample Programs

You can compile and run a sample program with the shell script provided for that specific sample program as shown in Table 12-2.

To compile and run a sample program:

  1. Open the ECE_home/oceceserver/config/eceTopology.conf file.

  2. Un-comment the line where the sdkCustomerLoader node is defined.

  3. Change directory to ECE_home/oceceserver/bin

  4. Load the ECE runtime environment:

    $ ./ecc 'load sdk_production_loader.ecc'

  5. Change directory to ECE_home/ocecesdk/sample_program_directory, where the sample_program_directory is the subdirectory that contains the shell script for compiling and running the sample program you want to run:

    Directory Description
    ECE_home/ocecesdk/bin/extensions Shell scripts for extension-implementation sample programs.
    ECE_home/ocecesdk/bin/notification Shell scripts for notification sample programs.
    ECE_home/ocecesdk/bin/policy Shell scripts for policy sample programs.
    ECE_home/ocecesdk/bin/plug-in Shell scripts for BrmCdrPluginDirect plug-in sample program
    ECE_home/ocecesdk/bin/query Shell scripts for query sample programs.
    ECE_home/ocecesdk/bin/update Shell scripts for update sample programs.
    ECE_vome/ocecesdk/bin/usage Shell scripts for usage sample programs.

    For example, to compile and run the sample_voice_session.sh sample program (the sample program for sending a voice session usage request to ECE), you must be in the ECE_home/ocecesdk/bin/usage directory.

  6. Compile the sample program:

    $ sh ./scriptname.sh build

    You must compile the sample program once.

    For example, to compile the sample_voice_session.sh sample program, enter:

    $ sh ./sample_voice_session.sh build

  7. Run the sample program.

    $ sh. /scriptname.sh run

    Some programs require that you enter parameters. The run command output gives you information about what parameters are required.

    If you run the run command with no parameters, the command uses default parameter values from the SDK scripts.

  8. When you are done with the sample program, shut down the ECE runtime environment:

    $ ecc stop server

About Sample Program Parameters

To determine which parameter values you need to use for running a sample program, you can use the help option of the sample script. All of the sample scripts have a help option which prints the usage of the sample program.

About Sample Program Methods

For descriptions of the methods the sample programs use, see the documentation for oracle.communication.brm.charging.sdk in BRM Elastic Charging Engine Java API Reference.

Usage Example for SampleDebitRefundSession

Below is a usage example for running the SampleDebitRefundSession sample program.

To see the usage of any sample program, type no arguments at the command line.

Usage:

sample_debit_refund_session.sh build|run|defaultrun userId requestType correlationId [BALANCE_ELEMENT_ID,AMOUNT BALANCE_ELEMENT_ID,AMOUNT ...] [TOTAL,IN,OUT TOTAL,IN,OUT ...]

where:

  • build compiles the related SDK source files

  • run runs the SDK program (debit refund) according to the parameters you provide.

    You must supply all parameters in the command line.

    Alternatively, you can provide no parameters. If you provide no parameters, the SDK script will invoke the ECE sample program with default parameter values.

  • defaultrun builds and runs the SDK program.

    No parameters are required. The program uses the default parameter specified inside the shell script.

  • Order of parameters are fixed and if one optional parameter is provided then all values of other optional parameters must be supplied.

  • requestType is either DEBIT_AMOUNT, REFUND_AMOUNT, DEBIT_UNIT, or REFUND_UNIT.

  • In case of DEBIT_AMOUNT or REFUND_AMOUNT, BALANCE_ELEMENT_ID is the well-known ISO code for balance elements, such as 840 for US Dollars, or 95 for Free Minutes.

  • In case of DEBIT_UNIT or REFUND_UNIT, TOTAL,IN and OUT has to be specified with numbers in MB (MegaBytes).

Example:

#debit $10 for USD and 25 seconds Free Minutes

sample_debit_refund_session.sh run 650999777 DEBIT_AMOUNT CORR_ID 840,10 95,25

#refund $50 for USD and 5 seconds Free Minutes

sample_debit_refund_session.sh run 650999777 REFUND_AMOUNT CORR_ID 840,50 95,5