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.
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.
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/ |
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. |
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. |
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.
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:
Open the ECE_home/oceceserver/config/eceTopology.conf file.
Un-comment the line where the sdkCustomerLoader node is defined.
Change directory to ECE_home/oceceserver/bin
Load the ECE runtime environment:
$ ./ecc 'load sdk_production_loader.ecc'
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.
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
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.
When you are done with the sample program, shut down the ECE runtime environment:
$ ecc stop server
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.
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.
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