1 Connecting J2EE-Compliant Applications to BRM

This chapter describes how a J2EE-compliant application can connect to the Oracle Communications Billing and Revenue Management (BRM) system by using JCA Resource Adapter and how BRM operations are exposed through the adapter.

Before using the adapter, you should be familiar with the following:

  • BRM concepts and architecture. See "Introducing BRM" in BRM Concepts.

  • J2EE and J2EE Connector Architecture (JCA) 1.5 Specification.

  • Web Service Invocation Framework (WSIF) and Web Services Description Language (WSDL) with JCA bindings.

About Connecting J2EE-Compliant Applications to the BRM System

You connect J2EE-compliant external applications to your BRM system by using JCA Resource Adapter. The adapter is deployed on a J2EE-compliant application server, such as Oracle WebLogic Server. External applications send requests for information to the adapter, which then calls BRM opcodes and returns data to the external application. This enables any J2EE-compliant application to integrate with the BRM software.

For example, a customer relationship management (CRM) application, such as Oracle's Siebel CRM, that is connected to an application server can send billing and rating requests to the BRM software for processing. For information about using the adapter as part of Oracle Application Integration Architecture (Oracle AIA), see "Using BRM with Oracle Application Integration Architecture" in BRM Concepts.

Overview of the JCA Resource Adapter Architecture

When a J2EE-compliant application sends a request to the application server, the Business Process Execution Language (BPEL) process on the application server routes the request to the adapter on the application framework (AF). Figure 1-1 illustrates the JCA Resource Adapter architecture.

Figure 1-1 JCA Resource Adapter Architecture

Description of Figure 1-1 follows
Description of ''Figure 1-1 JCA Resource Adapter Architecture''

When the adapter receives the request, it performs the following:

  1. Retrieves the opcode to call from the interaction specification.

  2. Optionally validates the input XML against the schema for the target opcode.

  3. Converts the input XML into an input flist.

  4. Calls the BRM opcode through the BRM context, using the opcode name, opcode flags, and other attributes passed in the interaction specification.

The opcode processes the request and returns the result in an output flist to the adapter. The adapter then performs the following:

  1. Converts the opcode's output flist into output XML and stores it in the payload of the output XML record.

  2. Optionally validates the output XML against the schema for the opcode.

  3. Returns the output XML to the calling application.

  4. In case of an error, returns a resource exception.

The adapter connects to BRM by using internal connection pooling, which can be configured as part of the adapter's deployment when creating connection factories.

About JCA Resource Adapter

The adapter is a system-level software driver that is used by a J2EE-compliant application to connect to the BRM system. The adapter complies with J2EE Connector Architecture 1.5 and follows the guidelines for a standalone packaged adapter. It supports synchronous outbound communication, which means that the request message originates from the J2EE-compliant application and is returned by the BRM system.

The adapter exposes the BRM API through the following:

  • JCA common client interface (CCI) as an Interaction.

  • WSIF provider and WSDL with JCA bindings as a WSIF API.

The adapter performs the following main functions:

About Sending Data to JCA Resource Adapter

The adapter implements CCI as part of the client API implementation. Any J2EE-compliant application that uses CCI can send data to the adapter, but the XML data it sends must conform to the BRM opcode XML schema.

To send data to the adapter, J2EE-compliant applications send the following data in the interaction specification:

  • The BRM opcode to call. For a list of opcodes that can be called, see the BRM WSDL files. By default, the WSDL files are installed in the BRM_Home/apps/brm_integrations/wsdls directory, where BRM_Home is the directory in which BRM components are installed. For information about WSDL files, see "About BRM Web Services and WSDL Files".

    BRM_Home/apps/brm_integrations/wsdls contains sub-directories to support BPEL flows on Oracle Application Integration Architecture (AIA) for Communications. For Oracle AIA 11.x, use the WSDL files in BRM_Home/apps/brm_integrations/wsdls/11g.

  • (Optional) Opcode schema file name. This specifies the location of the input and output schema files. By default, the schema files are installed in the BRM_Home/apps/brm_integrations/schemas directory.


    The schema file name is mandatory if validation is required.
  • (Optional) Opcode flags. This defaults to zero.

  • (Optional) Whether it is a base opcode. This specifies whether the opcode is a base opcode. See "Base Opcodes" in BRM Developer's Reference for more information. By default, an opcode is not a base opcode.

  • (Optional) Validation requirements. This specifies whether the adapter validates the input XML and output XML against the opcode schema. By default, validation is turned off.

J2EE-compliant applications send the input data for the opcode in the XML record payload. This includes all data that is required by the opcode's input flist.

For more information about the interaction specification parameters, see the BRM WSDL files. For more information about the input data, see the appropriate opcode flist specification.

The adapter returns a resource exception in the following situations:

  • If any of the mandatory fields are not passed in the interaction specification

  • If the input XML is not in an XML record or is not an instance of the XML record

  • If there is any error calling the opcode

  • If there is any error in the opcode's execution

  • If there is any error in the input or output validation

About BRM Web Services and WSDL Files

The WSDL files included with the adapter define the opcodes that can be called and the attributes required to call a specific opcode. The opcodes are grouped by functional area into a Web service. For example, one Web service defines the billing opcodes and another Web service defines the payment opcodes. The adapter includes one WSDL file for each Web service.

Table 1-1 describes the WSDL files installed, by default, in the BRM_Home/apps/brm_integrations/wsdls/10g directory.

Table 1-1 WSDL Default Files (10g)

WSDL File Name Description


Defines the accounts receivable Web service, which includes the following opcodes:













See "Accounts Receivable FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the balances Web service, which includes the following opcodes:





See "Balance FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the base Web service, which includes the following opcodes:




See "Base Opcodes" in BRM Developer's Reference for more information.


Defines the billing Web service, which includes the following opcodes:






See "Billing FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the collections Web service, which includes the following opcodes:


See "Collections Manager FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the customer Web service, which includes the following opcodes:










See "Customer FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the invoicing Web service, which includes the following opcodes:


Important: You must configure your client application to convert the invoice data received from the PCM_OP_INV_VIEW_INVOICE opcode into the appropriate format. See "About Invoicing Output XML Data".

See "Invoicing FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the pricing Web server, which includes the following opcodes:






Defines the payment Web service, which includes the following opcode:


See "Payment FM Standard Opcodes" in BRM Developer's Reference for more information.


Defines the subscription Web service, which includes the following opcodes:













See "Subscription Management FM Standard Opcodes" in BRM Developer's Reference for more information.

You can create a new WSDL file or add an opcode description to an existing WSDL file. For more information, see "Generating the WSDL Files for Your System".

About Validating Input and Output XML Data

The adapter optionally validates the input and output XML by comparing the XML fields and values against the opcode XML schema.

During the validation process, the adapter verifies that all date values passed in the input and output XML meet the ISO 8601 standard. The adapter supports the following ISO-8601 date formats:

Short Formats (without Seconds)

  • yyyy-mm-ddT

  • yyyy-mm-ddThh

  • yyyy-mm-ddThhZ

  • yyyy-mm-ddT+hh

  • yyyy-mm-ddT-hh

  • yyyy-mm-ddThh+hh

  • yyyy-mm-ddThh-hh

  • yyyy-mm-ddThhZ+hh

  • yyyy-mm-ddThhZ-hh

  • yyyy-mm-ddThh:mm

  • yyyy-mm-ddThh:mmZ

  • yyyy-mm-ddThhmm

  • yyyy-mm-ddThhmmZ

  • yyyy-mm-ddT+hhmm

  • yyyy-mm-ddT-hhmm

  • yyyy-mm-ddThh:mm+hh

  • yyyy-mm-ddThh:mm-hh

  • yyyy-mm-ddThh:mmZ+hh

  • yyyy-mm-ddThh:mmZ-hh

  • yyyy-mm-ddThhmm+hh

  • yyyy-mm-ddThhmm-hh

  • yyyy-mm-ddThhmmZ+hh

  • yyyy-mm-ddThhmmZ-hh

  • yyyy-mm-ddThh+hh:mm

  • yyyy-mm-ddThh-hh:mm

  • yyyy-mm-ddThhZ+hh:mm

  • yyyy-mm-ddThhZ-hh:mm

  • yyyy-mm-ddThh+hhmm

  • yyyy-mm-ddThh-hhmm

  • yyyy-mm-ddThhZ+hhmm

  • yyyy-mm-ddThhZ-hhmm

  • yyyy-mm-ddThh:mm+hh:mm

  • yyyy-mm-ddThh:mm-hh:mm

  • yyyy-mm-ddThh:mmZ+hh:mm

  • yyyy-mm-ddThh:mmZ-hh:mm

  • yyyy-mm-ddThh:mm+hhmm

  • yyyy-mm-ddThh:mm-hhmm

  • yyyy-mm-ddThh:mmZ+hhmm

  • yyyy-mm-ddThh:mmZ-hhmm

  • yyyy-mm-ddThhmm+hhmm

  • yyyy-mm-ddThhmm-hhmm

  • yyyy-mm-ddThhmmZ+hhmm

  • yyyy-mm-ddThhmmZ-hhmm

  • yyyy-mm-ddThhmm+hh:mm

  • yyyy-mm-ddThhmm-hh:mm

  • yyyy-mm-ddThhmmZ+hh:mm

  • yyyy-mm-ddThhmmZ-hh:mm

Long Formats (with Seconds)

  • yyyy-mm-ddThh:mm:ss

  • yyyy-mm-ddThh:mm:ssZ

  • yyyy-mm-ddThhmmss

  • yyyy-mm-ddThhmmssZ

  • yyyy-mm-ddThh:mm:ss+hh

  • yyyy-mm-ddThh:mm:ss-hh

  • yyyy-mm-ddThh:mm:ssZ+hh

  • yyyy-mm-ddThh:mm:ssZ-hh

  • yyyy-mm-ddThhmmss+hh

  • yyyy-mm-ddThhmmss-hh

  • yyyy-mm-ddThhmmssZ+hh

  • yyyy-mm-ddThhmmssZ-hh

  • yyyy-mm-ddThh:mm:ss+hh:mm

  • yyyy-mm-ddThh:mm:ss-hh:mm

  • yyyy-mm-ddThh:mm:ssZ+hh:mm

  • yyyy-mm-ddThh:mm:ssZ-hh:mm

  • yyyy-mm-ddThh:mm:ss+hhmm

  • yyyy-mm-ddThh:mm:ss-hhmm

  • yyyy-mm-ddThh:mm:ssZ+hhmm

  • yyyy-mm-ddThh:mm:ssZ-hhmm

  • yyyy-mm-ddThhmmss+hh:mm

  • yyyy-mm-ddThhmmss-hh:mm

  • yyyy-mm-ddThhmmssZ+hh:mm

  • yyyy-mm-ddThhmmssZ-hh:mm

  • yyyy-mm-ddThhmmss+hhmm

  • yyyy-mm-ddThhmmss-hhmm

  • yyyy-mm-ddThhmmssZ+hhmm

  • yyyy-mm-ddThhmmssZ-hhmm

The adapter includes XML schema for the BRM opcodes specified in the WSDL files. If support for other opcodes, other storable classes, or subclasses is needed, you must convert them into XSD schema before you can use them with the adapter.

About Validating the XML Schema for BRM Opcodes

The adapter validates the XML data passed in by the J2EE-compliant application by using the opcode XSD schema. For example, if the input XML includes data for the PCM_OP_CUST_COMMIT_CUSTOMER opcode, the adapter validates the input XML data against the PCM_OP_CUST_COMMIT_CUSTOMER input schema. Likewise, when returning the request, the adapter validates the output XML data against the opcode's output schema.

You must generate the schema for any opcode that the adapter needs to validate by using the pin_opspec_to_schema utility. For more information, see "Generating the Schema for Your Opcodes".

About Validating the XML Schema for Storable Classes and Subclasses

Opcode schemas define the schema for each opcode only and contain an extension section that references storable classes. To validate flist fields that reference storable class fields, the adapter includes the schema for storable classes in the schema for the opcodes.

The opcode schemas packaged with the adapter have include sections for the following storable class schema files:

  • /account

  • /billinfo

  • /discount

  • /event

  • /event/billing

  • /payinfo

  • /product

  • /profile

  • /purchased_discount

  • /purchased_product

  • /service

You must generate schema files for these storable classes and their subclasses. If you added any opcode schemas to the adapter, you must also generate schema files for any storable classes they need to access.

You generate the XSD schema for your storable classes and subclasses by using the pin_dd_to_schema utility. The utility generates the schema for all storable classes and their subclasses. For example, if you specify to generate schema for the /service/telco/gsm class, the utility generates the schema for /service/telco/gsm, /service/telco/gsm/telephony, /service/telco/gsm/data, and all other subclasses of the /service/telco/gsm class in your system.

To create the schema for storable classes, see "Generating the Schema for Your Storable Classes and Subclasses".

About Converting XML Data and Calling the BRM API

The adapter converts the input XML into an opcode input flist according to the rules in the XSL style sheet. The adapter then passes the flist to the appropriate opcode through the Java Portal Communications Module (PCM). If an error occurs during the opcode call or in the opcode functionality, the adapter returns an error to the calling application.

About Converting Output Flist Data into XML Format

The adapter converts output flists into XML format by using the BRM short tag name format. That is, the adapter creates XML tags by removing the ”PIN_FLD_” prefix from the flist field and array name. For example, the PIN_FLD_LOGIN flist field is mapped to the LOGIN XML tag, and the PIN_FLD_SERVICES flist array is mapped to the SERVICES XML tag.

The XML tags for the PIN_FLD_INHERITED_INFO and PIN_FLD_EXTENDED_INFO substructs, however, are constructed using the following syntax:


The value of Class is defined in the brm_extensions.xml file, which specifies the flist field from which to build the tag. The file is preconfigured for the opcode and storable class schemas shipped with the adapter. If your system contains custom opcodes that reference storable class fields, you must modify this file. For information, see "Specifying the XML Tags for Extended Fields".

About Invoicing Output XML Data

When you use the PCM_OP_INV_VIEW_INVOICE opcode to retrieve and display invoices, the adapter returns an unformatted invoice to the calling application. The adapter returns invoicing data in the BUFFER XML field in hexBinary format and the type of invoice format in the TYPE_STR XML field, as described in the opcode schema. To view a formatted invoice, you must configure your client application to convert the invoicing data into the appropriate format.

About JCA Resource Adapter Connection Management

Connection management enables J2EE-compliant applications to connect to the BRM system through the adapter. The adapter manages all connections and establishes physical connections through the Java PCM.

When a J2EE-compliant application sends an XML record, the adapter performs the following tasks:

  • Instantiates a CCI Connection object

  • Establishes a connection to BRM through the Java PCM

  • Stores a reference of the BRM context in the CCI Connection object

  • Returns the CCI Connection object to the application server

About JCA Resource Adapter Transaction Management

In compliance with the JCA 1.5 Specification, JCA Resource Adapter provides several levels of transaction support. You can deploy the adapter in any of the following transaction modes:

  • XA Transaction: (Default) In this mode, the adapter supports both two-phase commit extended architecture (XA) transactions and one-phase commit transactions managed by a global transaction manager through the XAResource interface. See "About XA Transaction Support".

  • Local Transaction: In this mode, the adapter supports only one-phase commit local transactions managed by the application server, such as Oracle WebLogic Server.

  • No Transaction: In this mode, the transaction is managed by the application, such as Oracle AIA, that is using JCA Resource Adapter to connect to BRM.

For information about changing the transaction mode, see "Changing the JCA Resource Adapter Transaction Mode on Oracle WebLogic Server".

About XA Transaction Support

An XA transaction (also called a distributed or global transaction) is a group of operations implemented as a single transaction involving multiple data stores (resources) on multiple network hosts. Each data store is represented by a resource manager (such as JCA Resource Adapter), and the transaction is presided over by a global transaction manager.

To ensure that all data stores involved in an XA transaction remain synchronized, each data store must participate in a two-phase commit process:

  • Phase 1: Prepare. After verifying whether its data store is accessible and the changes can be successfully committed, each participating resource manager votes either to commit or to roll back the transaction.

  • Phase 2: Commit. If all participating resource managers vote to commit, the transaction manager instructs them to finalize the operation. If one or more vote to roll back, all participating resources are instructed to roll back the prepared changes.

All J2EE-compliant external applications that need XA transaction support, such as Oracle AIA, must connect to BRM through JCA Resource Adapter.

The adapter supports calls to all the methods in the J2EE standard XA API (javax.transaction.xa.XAResource).

For more information about XA transactions, see XA and Oracle Controlled Distributed Transactions.

About the XA Transaction Timeout

By default, successfully prepared XA transactions expire in BRM if a commit request is not received within a specified time after the transaction opens. The XA transaction timeout is specified in the following places, which are listed in the order of priority:

  • Application server configuration settings

  • Oracle DM configuration file dm_xa_trans_timeout_in_secs entry

Making the XA transaction timeout period long enough for the transaction manager to recover from failure and complete interrupted XA transactions without a database administrator's intervention is a good practice. See "Changing the XA Transaction Timeout Period".

The following Oracle database views contain information about expired XA transactions:

  • DBA_2PC_PENDING. Contains all prepared XA transactions that have expired, including those that have been manually committed or rolled back but not yet purged or forgotten via an XA forget() request. See "About the DBA_2PC_PENDING Table" in BRM System Administrator's Guide.

  • DBA_PENDING_TRANSACTIONS. Contains all prepared XA transactions waiting to be committed, whether or not they are expired. Expired transactions that have been manually committed or rolled back remain in this view until they are purged or forgotten.

Expired XA transactions can be completed by one of the following operations:

About Recovering from XA Transaction Failures

When the transaction manager is restarted after a failure, it sends a recover request to JCA Resource Adapter. The adapter returns a list of XA transaction branches that are in a prepared or manually completed state.

Based on information in its transaction logs, the transaction manager then issues a commit or rollback request for each transaction in the list. If a request fails with one of the following error codes (which indicate that the transaction was manually completed), the transaction manager issues a forget request to prevent the adapter from reprocessing the transaction during the next recovery process:




For more information about the XA error codes, see "BRM Error Codes" in BRM System Administrator's Guide.


To enable BRM to support the XA recovery process, you must grant read privileges to the DBA_2PC_PENDING and DBA_PENDING_TRANSACTIONS views for each BRM database user. See step 7 in "Installing JCA Resource Adapter".

About IMDB Cache Manager and Distributed Transactions

JCA Resource Adapter does not support distributed transactions that involve IMDB Cache Manager. For information about distributed transactions involving IMDB Cache Manager, see "About Committing Transactions in Both Oracle IMDB Cache and the BRM Database" in BRM System Administrator's Guide.

About Creating Multiple Accounts in One Transaction with JCA Resource Adapter

You can create multiple BRM accounts in one transaction with JCA Resource Adapter. This is useful, for example, when a single order in Oracle Communications Order and Service Management (OSM) produces multiple new customers. It enables Oracle AIA to maintain the cross-references between the OSM order and its associated BRM accounts.

To create multiple accounts in one transaction, make all calls to the PCM_OP_CUST_COMMIT_CUSTOMER opcode any time within that transaction. The order of calling the PCM_OP_CUST_COMMIT_CUSTOMER opcode is irrelevant.

About JCA Resource Adapter Security

The adapter logs a J2EE-compliant application into the BRM software using basic security:

  • Client authentication. The adapter authenticates a valid J2EE-compliant application with a user name and password. You can implement more robust authentication by using the adapter policies.

  • Client authorization. By default, the adapter does not perform authorization, but you can implement it by using Oracle Identity Manager. You can also use Oracle Identity Manager to implement roles and authorization based on roles.

  • Secure communication. A secure communication channel between the adapter and BRM is dependent on the implementation.


    The adapter does not support reauthentication or reauthorization.

If the client passes erroneous security information, the adapter returns a security exception to indicate the error.

You set security by using entries in the adapter deployment descriptor file. For more information, see "Connecting JCA Resource Adapter to BRM from Oracle WebLogic Server".

About JCA Resource Adapter Logging

JCA Resource Adapter supports Java Unified Logging (JUL), which enables the adapter to use the application server's logging library.

For more information, see "Configuring JCA Resource Adapter Logging on Oracle WebLogic Server".

About Deploying and Connecting JCA Resource Adapter

After installing the adapter package, you must deploy it on your application server. The connection parameters to connect the adapter to BRM are defined in the deployment descriptor packaged along with the adapter archive (RAR) file. The deployment descriptor includes the following files:

  • Adapter deployment descriptor file (ra.xml): Includes parameters for connecting the adapter to BRM and the application server. The format of the file is defined in the J2EE Connector Architecture 1.5 Specification.

  • Oracle WebLogic Server deployment descriptor file (weblogic-ra.xml): Defines operation parameters that are unique to Oracle WebLogic Server.

For more information, see "Deploying and Configuring JCA Resource Adapter on Oracle WebLogic Server".

About the BRMAdapterServletClient Application

Use the BRMAdapterServletClient application to test your custom opcodes and develop customized applications that communicate with JCA Resource Adapter.

For more information, see "Testing JCA Resource Adapter Configuration and BRM Connectivity".