3 Deploying and Configuring JCA Resource Adapter

This chapter describes how to deploy and configure JCA Resource Adapter.

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

  • Oracle Communications Billing and Revenue Management (BRM) concepts and architecture. See "Introducing BRM" in BRM Concepts.

  • BRM opcodes and flists. See "Understanding Flists and Storable Classes" in BRM Developer's Guide.

  • J2EE Connector Architecture (JCA) 1.5 Specification.

  • XML, XML Schema Definition (XSD), and XML StyleSheet Language (XSL).

  • Web Services Description Language (WSDL).

Overview of the JCA Resource Adapter Configuration Procedure

The procedure for setting up JCA Resource Adapter includes the following tasks:

  1. Installing the adapter on your BRM system. See "Installing JCA Resource Adapter".

  2. Compiling your custom Java Portal Connection Module (PCM) classes and adding them to the adapter. See "Creating and Packaging Custom Classes and Fields".

  3. Generating the schema files for the adapter. See "Generating the Schema Files for Your System".

  4. Specifying how to construct XML tags. See "Specifying the XML Tags for Extended Fields".

  5. Generating the WSDL files for the adapter. See "Generating the WSDL Files for Your System".

  6. Configuring the representation of infinite date values. See "Configuring How to Represent Infinite Date Values".

  7. Deploying and connecting the adapter on your application server:

  8. (Optional) Change the XA transaction timeout period. See "Changing the XA Transaction Timeout Period".

  9. Testing JCA Resource Adapter's configuration and connectivity to BRM. See "Testing JCA Resource Adapter Configuration and BRM Connectivity".

Creating and Packaging Custom Classes and Fields

JCA Resource Adapter uses Java PCM APIs to connect to BRM. If the adapter will call opcodes that reference custom storable class fields, you must compile your custom classes and add them to the adapter to make the custom storable class fields available to the adapter.

To make your custom and modified storable classes available to JCA Resource Adapter:

  1. Use Storable Class Editor to create or modify your storable classes and fields. For more information, see Storable Class Editor Help.

    For information about editing storable classes, see "Creating, Editing, and Deleting Fields and Storable Classes" in BRM Developer's Guide.

  2. From the File menu, select Generate Custom Fields Source to create source files for your custom fields. See Storable Class Editor Help for detailed instructions.

    Storable Class Editor creates a C header file called cust_flds.h, a Java properties file called InfranetPropertiesAdditions.properties, and a Java source file for each custom field.

  3. Create the Infranet.properites file in the adapter's top-level directory.

  4. For each Java application that will use these fields, copy the contents of the InfranetPropertiesAdditions.properties file into the Infranet.properties file.

  5. In the directory where Storable Class Editor created the Java source files, compile the source files:

    javac -d . *.java 
      
    
  6. Package the class files created in step 5 into a JAR file:

    jar cvf filename.jar *.class 
      
    
  7. Package the JAR file created in step 6 and the Infranet.properties file created in step 3 into the OracleBRMJCA15Adapter.rar file.

    Note:

    Ensure that the OracleBRMJCA15Adapter.rar file includes only one instance of the updated Infranet.properties file. And, if the OracleBRMJCA14Adapter.jar file within the OracleBRMJCA15Adapter.rar file contains the Infranet.properties file, ensure that the contents of the InfranetPropertiesAdditions.properties file are copied into that file.
  8. Do one of the following:

    • Place the OracleBRMJCA15Adapter.rar file in the adapter's working directory (Oracle_Home/j2ee/Instance/connectors/AdapterDeploymentName/AdapterDeploymentName).

    • Place the JAR file created in step 6 in the WebLogic_home/mydomain/user_projects/Domain_Name/lib directory.

      where:

      • WebLogic_Home is the directory in which you installed the WebLogic Server.

      • Domain_Name is the domain directory in which the adapter will be deployed.

  9. Restart your application server.

Generating the Schema Files for Your System

JCA Resource Adapter uses schema files to validate data it sends to or receives from BRM.

To generate the schema files for your system:

  1. If you modified any opcodes, generate schemas for the opcodes in your BRM system. See "Generating the Schema for Your Opcodes".

  2. Generate schemas for the storable classes and subclasses in your BRM system. See "Generating the Schema for Your Storable Classes and Subclasses".

  3. In your opcode schema files, specify the location of your storable class schema files. See "Specifying the Location of the Storable Class Schema Files in the Opcode Schema Files".

  4. Copy the opcode and storable class schema files to a location that is accessible to the adapter. Verify that this location is the same as the one specified in the include section of the opcode schema files and in the opcode schema InteractionSpec attribute in the WSDL files. See "Specifying the Location of the Storable Class Schema Files in the Opcode Schema Files" and "Generating the WSDL Files for Your System".

Generating the Schema for Your Opcodes

The adapter package includes all the opcode schemas and flist specifications you need for a default integration.

If you customized any of the opcodes that are supported by the adapter or if you added support for new opcodes, you must generate XSD schema files for the opcodes.

The steps you must take depend on the type of changes you made, as shown in Table 3-1:

Table 3-1 Procedure for Modifying Opcodes

Opcode Modification Procedure

Customized an opcode that JCA Resource Adapter already supports

Do the following:

  1. Modify the opcode's XML specification file. By default, the opcode specification XML files are installed in the BRM_home/apps/brm_integrations/opspecs directory, where BRM_home is the directory in which BRM is installed. See "Creating Custom Opcode Specification XML Files".

  2. Run the pin_opspec_to_schema utility. See "Converting flist Specs into XSD Schema Files with pin_opspec_to_schema".

Added a custom data type to an opcode that JCA Resource Adapter already supports

Do the following:

  1. Modify the opcode's XML specification file. By default, the opcode specification XML files are installed in the BRM_home/apps/brm_integrations/opspecs directory. See "Creating Custom Opcode Specification XML Files".

  2. Modify the pin_opspec_to_schema style sheet to handle custom data types or custom data structures. See "Specifying the XSL Rules to Create the Opcode Schema".

  3. Run the pin_opspec_to_schema utility. See "Converting flist Specs into XSD Schema Files with pin_opspec_to_schema".

Added a custom opcode to JCA Resource Adapter

Do the following:

  1. Configure BRM to recognize the custom opcode and manually create the opcode's XML specification file. See "Writing a Custom Facilities Module" in BRM Developer's Guide.

  2. If your opcode supports custom data types or data structures, modify the pin_opspec_to_schema style sheet. See "Specifying the XSL Rules to Create the Opcode Schema".

  3. Run the pin_opspec_to_schema utility. See "Converting flist Specs into XSD Schema Files with pin_opspec_to_schema".

Note: Add your custom opcode to a WSDL file. See "Generating the WSDL Files for Your System".


Creating Custom Opcode Specification XML Files

You must create XML specification files for any opcodes that you customize or add to the adapter. Create the XML specification files by following the instructions in the BRM_home/apps/brm_integrations/stylesheets/opspec.xsd file.

Specifying the XSL Rules to Create the Opcode Schema

The pin_opspec_to_schema utility uses the BRM_home/brm_integrations/stylesheets/pin_opspec_to_schema.xsl style sheet to generate the schema for BRM opcodes. If your opcode references custom data types or custom data structures, you must modify the pin_opspec_to_schema.xsl style sheet to handle your customizations.

For a list of the supported BRM data types, see "Understanding the BRM Data Types" in BRM Developer's Guide.

Converting flist Specs into XSD Schema Files with pin_opspec_to_schema

To convert flist specifications into XSD schema files:

  1. Go to the BRM_home/apps/brm_integrations directory and run the following command:

    pin_opspec_to_schema -i input_file [-o output_file]
      
    

    where:

    • input_file is the name and location of the opcode's XML flist specification. By default, the utility looks for the file in the current directory.

    • output_file is the XSD schema output. By default, the utility creates a file named opcodename.xsd in the directory from which you run the utility.

Generating the Schema for Your Storable Classes and Subclasses

JCA Resource Adapter uses storable class schema files to validate storable class extensions passed in the input XML. See "Connecting J2EE-Compliant Applications to BRM".

To generate storable class schema files for your system:

  1. Determine which storable class files you must convert into XSD schema. See "Determining the Storable Classes to Convert into Schema".

  2. Convert your storable classes and subclasses by running the pin_dd_to_schema utility. See "Generating Storable Class Schema Files".

Determining the Storable Classes to Convert into Schema

The adapter package includes all the storable class schema files required for a default integration. By default, they are installed in the BRM_home/apps/brm_integrations/schemas directory.

You must generate additional schema files if your system contains the following:

  • Extensions to the /account, /billinfo, /discount, /event, /event/billing, /payinfo, /product, /profile, /purchased_discount, /purchased_product, or /service storable classes. If you extended any of these storable classes, you must create a new schema file for the base class. For example, if you added a subclass to the /profile storable class, you must regenerate the profile.xsd schema file.

  • Storable classes required by opcodes you added to JCA Resource Adapter. If you added an opcode schema to the adapter, you can determine whether it requires a storable class by checking for an include schemaLocation entry at the beginning of the schema file. If the entry exists, it lists the required storable class schema files. For example, the PCM_OP_CUST_COMMIT_CUSTOMER.xsd schema file includes the following entries, which indicate that the opcode needs schema files for the /service and /profile classes:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <xsd:schema targetNamespace="http://www.xmlns.oracle.com/BRM/schemas/BusinessOpcodes"
    elementFormDefault="qualified"
        xmlns="http://www.xmlns.oracle.com/BRM/schemas/BusinessOpcodes"
        xmlns:op="http://www.portal.com/schemas/BusinessOpcodes"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      
      <xsd:include schemaLocation="service.xsd"/>
      <xsd:include schemaLocation="profile.xsd"/>
      
      <xsd:element name="PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist">
        <xsd:complexType>
    

Generating Storable Class Schema Files

JCA Resource Adapter uses the schema to validate the object fields that are passed in the input XML.

Note:

The utility requires a configuration file to access the BRM database. For more information, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

To generate the schema for the storable classes and subclasses in your system:

  1. Verify that the storable class changes have been added to the BRM data dictionary.

  2. Using a text editor, create a configuration file that lists all storable classes you would like to convert. For example, create a sample.txt file that includes the following entries:

    /service/telco/gsm
    /service/telco/gprs
    /service/sms
    /service/telephony
    /profile
      
    
  3. Save and close the file.

  4. (Oracle Linux only) Set the LC_ALL environment variable to C:

    setenv LC_ALL C
      
    
  5. Go to the BRM_home/apps/brm_integrations directory and run the following command:

    pin_dd_to_schema  -e config_file | -r storable_class
      
    

    where:

    • config_file generates the schema for all storable classes listed in the configuration file and their subclasses.

    • storable_class generates the schema for the specified storable class and all of its subclasses.

    The utility generates the schema files in the directory from which you run the utility.

  6. Copy the schema files to a location that is accessible to the adapter during the XML validation process; for example, BRM_home/apps/brm_integrations/schemas.

Specifying the Location of the Storable Class Schema Files in the Opcode Schema Files

Opcode schema files contain an include section that lists each storable class schema file that they need. You must manually update the opcode schema files to point to the storable class schema file's correct location.

Not all opcodes need storable classes, so only a subset of the opcode schema files have the include section. The following list shows the opcode schemas that are packaged with the adapter and have an include section:

  • PCM_OP_CUST_COMMIT_CUSTOMER

  • PCM_OP_CUST_CREATE_PROFILE

  • PCM_OP_CUST_MODIFY_CUSTOMER

  • PCM_OP_CUST_MODIFY_PROFILE

  • PCM_OP_CUST_UPDATE_CUSTOMER

  • PCM_OP_CUST_UPDATE_SERVICES

  • PCM_OP_PYMT_COLLECT

  • PCM_OP_READ_FLDS

  • PCM_OP_READ_OBJ

  • PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT

  • PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT

  • PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION

  • PCM_OP_SUBSCRIPTION_CHANGE_DEAL

  • PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS

  • PCM_OP_SUBSCRIPTION_PURCHASE_DEAL

  • PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO

  • PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS

  • PCM_OP_SUBSCRIPTION_SET_PRODINFO

  • PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS

  • PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION

Perform the following for each opcode schema that contains an include section for the storable class schema files:

  1. Open the opcode XSD schema file in a text editor. By default, the opcode schema files are located in the BRM_home/apps/brm_integrations/schemas directory.

  2. Edit the include schemaLocation entry to point to each schema file's correct location. For example, you edit the lines shown in bold below for the PCM_OP_CUST_COMMIT_CUSTOMER.xsd file:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <xsd:schema targetNamespace="http://www.xmlns.oracle.com/BRM/schemas/BusinessOpcodes"
    elementFormDefault="qualified"
        xmlns="http://www.xmlns.oracle.com/BRM/schemas/BusinessOpcodes"
        xmlns:op="http://www.portal.com/schemas/BusinessOpcodes"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      
      <xsd:include schemaLocation="service.xsd"/>
      <xsd:include schemaLocation="profile.xsd"/>
      
      <xsd:element name="PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist">
        <xsd:complexType>
    

    Note:

    The adapter does not support accessing schemas through URLs.
  3. Save and close the file.

Specifying the XML Tags for Extended Fields

The brm_extensions.xml file defines how to construct XML tags for PIN_FLD_INHERITED_INFO and PIN_FLD_EXTENDED_INFO substructs when converting output flists into XML. The default file is preconfigured for the opcode and storable class schemas shipped with the adapter. You must modify this file if you added to the adapter any opcodes that reference storable class fields.

The adapter creates XML tags for PIN_FLD_INHERITED_INFO and PIN_FLD_EXTENDED_INFO substructs by using the following syntax:

ClassExtension
  

where Class is the subclass name, using an underscore (_) notation. For example, the XML tag for /service/telco/gsm is written as service_telco_gsmExtension. The file specifies the following for each opcode:

  1. Open the BRM_home/apps/brm_integrations/config/brm_extensions.xml file in an XML editor.

    Note:

    The file is packaged with the adapter and is copied to the Oracle_home/j2ee/Instance/connectors/AdapterDeploymentName/AdapterDeploymentName directory during the deployment process.
  2. In the opcode name entry, add the opcode that requires the subclass fields:

    <opcode name="Opcodename">
      
    
  3. In the container name entry, add the flist field used to construct the XML tag:

    <container name="Arrayname">Fieldname</container>
      
    

    where:

    • Arrayname specifies the array that contains the PIN_FLD_INHERITED_INFO or PIN_FLD_EXTENDED_INFO substruct.

    • Fieldname specifies the flist field in which to look up the subclass name.

    For example, the following entry for the PCM_OP_CUST_COMMIT_CUSTOMER opcode specifies that when the PIN_FLD_SERVICES output flist array contains PIN_FLD_INHERITED_INFO or PIN_FLD_EXTENDED_INFO, the adapter looks up the subclass name from the PIN_FLD_SERVICE_OBJ flist field.

    <?xml version="1.0" encoding="UTF-8"?>
    <brm_extensions>
    <opcode name="PCM_OP_CUST_COMMIT_CUSTOMER">
    <container name="PIN_FLD_SERVICES">PIN_FLD_SERVICE_OBJ</container>
    </opcode> 
    ... 
    </brm_extensions> 
      
    

    In this example, if the PIN_FLD_SERVICE_OBJ output flist field is 0.0.0.1 /service/ip 12345 0, Class is service_ip and the corresponding XML extension tag is service_ipExtension.

  4. Save and close the file.

  5. Restart the adapter.

Generating the WSDL Files for Your System

The adapter package includes all the WSDL files you need for a default implementation. If you customized the adapter to support additional opcodes, you must create or modify a WSDL file.

To generate a WSDL file:

Defining a Web Service

To define a Web service, specify the following in a configuration file:

  • The Web service name

  • The opcodes associated with the Web service

  • The location of each opcode's schema files

You create the configuration file manually by using an XML editor. The adapter provides a sample XML configuration file (BRM_home/apps/brm_integrations/config/pin_wsdl_generator.xml) that you can use as a guide.

The configuration file includes four main sections: namespaces, groups, binding-info, and service-info. You configure the groups section only; the namespaces, binding-info, and service-info sections are preconfigured.

Defining Default Values for a Web Service

You specify the default values for a Web service in the group-info name entry. The default values apply to all opcodes in the Web service, but they are overridden by any opcode-specific values defined in the opcode name entry. For information, see "Defining Settings for Individual Opcodes".

<group-info name="BASE" base="True" includePath="../schemas/"
wsdlFileInFix="Base"  validation="ValidationNotRequired"
validationAttr="ValidationNotRequired">

where:

  • group-info name specifies the name of the Web service.

  • base specifies whether the opcodes in this Web service are base opcodes. See "Base Opcodes" in BRM Developer's Reference. The default is False.

  • includePath specifies the relative path to the schema files. The utility adds this value to the WSDL file's include entries.

  • wsdlFileInFix specifies the value to add to the WSDL file name, using the following syntax: BRMValueServices.wsdl. For example, if wsdlFileInFix is set to Bill, the WSDL file name is BRMBillServices.wsdl. If this attribute is not present, the utility uses the group-info name value in the file name's syntax.

  • validation specifies whether the adapter validates the input and output XML for the opcodes in this group. The valid values are:

    • ValidationRequired, which specifies to validate the input and output XML. You can limit validation to just the input XML or just the output XML by using the validationAttr entry.

    • ValidationNotRequired, which specifies to skip the validation process.

    • InternalSchemaValidation, which specifies that the utility determines whether to validate the input and output XML by reading the validation requirement from the interaction specification.

    The default is ValidationRequired.

  • validationAttr specifies whether to validate only the input XML or only the output XML. This entry is valid only when the validation entry is set to ValidationRequired. The valid values are:

    • InputValidationNotRequired, which specifies to validate only the output XML.

    • OutputValidationNotRequired, which specifies to validate only the input XML.

Defining Settings for Individual Opcodes

You use the opcode name lines to list the opcodes that are in the Web service. Each opcode in the Web service must have its own opcode name entry.

Note:

The opcode-specific settings in this section override the default settings in the group-info name entry. If you set both default values and values specific to an individual opcode, the utility uses the opcode-specific settings first.
 <opcode name="PCM_OP_SEARCH"
base="True" 
custom="no"
opcodeNumber="89"
includePath="../schemas/"
wsdlFileInFix="Base" 
validation="ValidationRequired" 
validationAttr="InputValidationNotRequired">
   <opcodeFlag>1</opcodeFlag>
  

where:

  • opcode name specifies the name of an opcode in the Web service.

  • base specifies whether the opcode is a base opcode. See "Base Opcodes" in BRM Developer's Reference. The default is False.

  • custom specifies whether the opcode is a custom opcode. The valid values are yes and no. The default is no.

  • opcodeNumber specifies the opcode number. This field is mandatory if the custom field is set to yes.

  • includePath specifies the relative path to the schema files. The utility adds this value to the WSDL file's include entries.

  • wsdlFileInFix specifies the value to add to the WSDL file name, using the following syntax: BRMValueServices.wsdl. For example, if wsdlFileInFix is set to Bill, the WSDL file name is BRMBillServices.wsdl. If this attribute is not present, the utility uses the group-info name value in the file name's syntax.

  • validation specifies whether the adapter validates the input and output XML. The valid values are:

    • ValidationRequired, which specifies to validate the input and output XML. You can limit validation to just the input XML or just the output XML by using the validationAttr entry.

    • ValidationNotRequired, which specifies to skip the validation process.

    • InternalSchemaValidation, which specifies that the utility determines whether to validate the input and output XML by reading the validation requirement from the interaction specification.

    The default is ValidationRequired.

  • validationAttr specifies whether to validate only the input XML or only the output XML. This entry is valid only when the validation entry is set to ValidationRequired. The valid values are:

    • InputValidationNotRequired, which specifies to validate only the output XML.

    • OutputValidationNotRequired, which specifies to validate only the input XML.

  • opcodeFlag is the flag to pass to the opcode when it is called by the adapter. The default is 0.

Sample Web Services Group Configuration File

The following shows a sample XML configuration file:

<?xml version='1.0'?>
<wsdl-generate>
  <namespaces>
    <partnerlink-namespace     prefix="plt">http://schemas.xmlsoap.org/ws/2003/05/partner-link/</partnerlink-namespace>
    <jca-namespace prefix="jca">http://xmlns.oracle.com/pcbpel/wsdl/jca/</jca-namespace>
    <soap-namespace prefix="soap">http://schemas.xmlsoap.org/wsdl/soap/</soap-namespace>
    <default-namespace>http://schemas.xmlsoap.org/wsdl/</default-namespace>
    <brm-nameSpace prefix="brm">http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes</brm-nameSpace>
  </namespaces>
  <groups>
    <group-info name="BAL" includePath="../schemas/" wsdlFileInFix="Bal"
     validation="ValidationRequired" validationAttr="InputValidationNotRequired"> 
    <opcode name="PCM_OP_BAL_GET_BAL_GRP_AND_SVC" 
     validation="ValidationNotRequired">
      <opcodeFlag>1</opcodeFlag> 
    </group-info>
  </groups>
  <binding-info>
    <!-- binding information specific to J2CA and SOAP.
    The general binding information is filled by the tool. -->
  <JCA>
    <InteractionSpec>oracle.tip.adapter.brm.BRMInteractionSpec</InteractionSpec>
  </JCA>
  <SOAP>
    <Action>http://localhost/operationName</Action>
    <encodingStyle>http://schemas.xmlsoap.org/soap/encoding/</encodingStyle>
  </SOAP>
  </binding-info>
  <service-info>
    <!-- Service information specific to J2CA and SOAP -->
    <JCA>
      <!-- JNDI name of BRM JCA Resource Adapter -->
      <location>eis/BRM</location>
    </JCA>
    <SOAP>
      <address>http://localhost:8080/brm/BRMWS</address>
    </SOAP>
  </service-info>
</wsdl-generate>

Generating WSDL Files for Web Services

To generate WSDL files:

  1. Go to the BRM_home/apps/brm_integrations/config directory.

  2. Run the following command:

    pin_wsdl_generator [-c config_file] [-j | -s| -s XML]
      
    

    where:

    • config_file is the name and location of the XML configuration file that describes the grouping of opcodes. By default, the utility uses the BRM_home/apps/brm_integrations/config/pin_wsdl_generator.xml file.

    • -j generates WSDL files with JCA bindings. This is the default.

    • -s generates WSDL files with SOAP bindings for opcodes that take the payload as an XML string.

    • -s XML generates WSDL files with SOAP bindings for opcodes that take the payload as an XML element.

The utility generates the WSDL files in the directory from which the utility is run.

Configuring How to Represent Infinite Date Values

In some external applications, the infinite date value is represented as a NULL (empty XML element) value and in other external applications as the epoch time (01-01-1970 1200 AM UTC).

By default, when JCA Resource Adapter sends data to your external application, the infinite date value is the start of the epoch time.

Note:

Before configuring the new connection factory field, redeploy JCA Resource Adapter on the server running Oracle WebLogic Server.

To configure how to represent infinite date values:

  1. Start the application server or the J2EE instance.

  2. From the WebLogic Server Administration Console page, go to the resource adapter home page and create connection factories.

  3. Do one of the following:

    • To send the date field value, set ZeroEpochAsNull to true.

    • To send the date field value as the start of the epoch time, set ZeroEpochAsNull to false. This is the default.

    Note:

    Connection factory field values must be lowercase.

Deploying and Configuring JCA Resource Adapter on Oracle WebLogic Server

To deploy and configure the adapter on Oracle WebLogic Server, perform the following tasks:

Note:

Any time you change the adapter's configuration, you must restart Oracle WebLogic Server for the changes to take effect.

Deploying JCA Resource Adapter on Oracle WebLogic Server

The adapter is dependent on JAR files to deploy properly. Table 3-2 lists the JAR files that the adapter requires from different sources in your system.

Table 3-2 JAR Files Required from Other Sources

Source JAR Files

Oracle BPEL process

bpm-infra.jar

orabpel-thirdparty.jar

orabpel.jar

orabpel-common.jar

xmlparserv2.jar

Apache Xerces J

xercesImpl.jar

This file is available as follows:

  • For Linux, the xercesImpl.jar file is installed with Oracle WebLogic Server by default.

  • For Solaris and AIX, copy the BRM_home/jars/xercesImpl.jar file to the Domain_home/lib directory, where Domain_home is the WebLogic Server domain in which you will deploy JCA Resource Adapter, and then restart Oracle WebLogic Server.


If you are deploying the adapter in a standalone WebLogic Server instance, make sure these JAR files are included in your CLASSPATH.

To deploy the adapter on WebLogic Server:

  1. Start the WebLogic Server domain if it is not already started.

  2. Log in to WebLogic Server Administration Console. The default is the following:

    http://localhost:8001/console
      
    
  3. Click Lock and Edit.

  4. In the Domain Structure tree, click Deployments.

    The Summary of Deployments pane appears.

  5. Click Install.

    The Install Application Assistant pane appears.

  6. Browse to the deploy directory of the ResourceAdapterDeployment project, select the OracleBRMJCA15Adapter.rar file, and click Next.

  7. Select Install this deployment as an application and click Next.

  8. In the server list, select Server and click Next.

  9. Accept all other defaults on the remaining screens.

  10. Click Finish.

  11. Click Activate Changes, which deploys the adapter.

Check the state of the OracleBRMJCA15Adapter application in the WebLogic Server Administration Console. Start the application if the state is set to Prepared.

Connecting JCA Resource Adapter to BRM from Oracle WebLogic Server

You connect the adapter to the BRM software by creating connection pools and connection factories. As part of the adapter deployment, the application server creates a weblogic-ra.xml file from the packaged ra.xml file.

To configure the JCA Resource Adapter connection factory and connection pools:

  1. Start the WebLogic Server domain if it is not already started.

  2. Log in to WebLogic Server Administration Console. The default is the following:

    http://localhost:8001/console
      
    
  3. In the Domain Structure tree, click Deployments.

    The Summary of Deployments pane appears.

  4. In the Deployments table, click the JCA Resource Adapter name.

    By default, the name is OracleBRMJCA15Adapter.

    The Settings for Adapter_Name pane appears.

  5. Click the Configuration tab.

  6. Click the Outbound Connection Pool tab.

  7. In the Outbound Connection Pool Configuration table, expand OracleConnectionFactory.

  8. Click eis/BRM, which is the name of the JNDI for JCA Resource Adapter.

  9. In the Properties tab, for each connection factory, specify the following along with the needed connection factory field values in Table 3-3:

    • The JNDI location for the connection factory

    • The connection pool to use

    • How to connect to BRM by using these entries

      Note:

      Connection factory field values must be lowercase.
  10. Table 3-3 Connection Factory Field Values

    Entry Description

    ConnectionString

    Specify the protocol, host name, and port number for connecting to the BRM software. For example: ip server1 12006.

    Note: The protocol must be set to ip.

    FailoverConnectionString

    (In high-availability systems) Specifies an alternate Connection Manager (CM) host that an adapter uses to connect to BRM if the main host, specified in the ConnectionString entry, is unavailable. Use the following syntax:

    host_name1:port:password,host_name2:port:password,...

    where:

    • host_name is the name or IP address of the computer running CM or Connection Manager Master Process (CMMP).

    • port is the TCP port number of CM or CMMP on the host computer.

    • password is the password for logging into the BRM software.

    The syntax includes one or more alternate CMs separated by commas. For example: my_ host1:21:admin,my_host2:21:admin.

    InputValidation

    Specifies whether to validate the input XMLRecord:

    • true: The adapter validates the input XMLRecord against the opcode schema.

    • false: The adapter does not validate the input XMLRecord.

    The default is false.

    This overrides any other validation parameter specified in the WSDL file. For information about setting the validation parameters in the WSDL file, see "Defining a Web Service".

    OutputValidation

    Specifies whether to validate the output XMLRecord:

    • true: The adapter validates the output XMLRecord against the opcode schema.

    • false: The adapter does not validate the output XMLRecord.

    The default is false.

    This overrides any other validation parameter specified in the WSDL file. For information about setting the validation parameters in the WSDL file, see "Defining a Web Service".

    LoginType

    Specifies the authentication method:

    • 1: The adapter logs in to BRM by using the specified login name and password.

    • 0: The adapter logs in to BRM by using the specified service type and POID ID.

    The default is 1.

    UserName

    Specifies the login name the adapter uses for logging in to the BRM software.

    Note: This entry is required only if LoginType is set to 1.

    Password

    Specify the password the adapter uses for logging in to the BRM software.

    Note: This entry is required only if LoginType is set to 1.

    PoidID

    Specifies the POID. This entry should be set to 1.

    If JCA Resource Adapter is deployed under a brand, set PoidID to the account POID of the brand login.

    ServiceType

    Specifies the service the adapter uses to log in to the BRM software.

    The default is /service/pcm_client.

    BRMConnectionPoolMaxSize

    Specifies the maximum number of connections the connection pool can create.

    BRMConnectionPoolMinSize

    Specifies the minimum number of connections created by the connection pool when the pool is initialized.

    transactionMode

    Specifies the transaction mode used for message producers. See "About JCA Resource Adapter Transaction Management".

    MultiDB

    Specifies whether to enable connections to multiple database schemas:

    • true: Enables connections to multiple schemas.

    • false: Disables connections to multiple schemas.

    When the MultiDB connection factory entry is set to true, you do not need to supply the target schema's database number; the adapter automatically opens transactions on the correct schema and generates an error if a transaction attempts to manipulate data across schemas.

    BRMConnectionPoolTimeout

    Specifies the maximum amount of time in milliseconds that a connection request is queued.

    BRMConnectionPoolMaxIdleTime

    Specifies the maximum amount of time in milliseconds that a free connection in the connection pool can be idle. If a free connection is idle for a time greater than or equal to BRMConnectionPoolMaxIdleTime, the connection is removed from the pool.

    Note: Only the connections created after the limit set by BRMConnectionPoolMinsize is reached are verified for the idle time; if the condition is met, the connection is removed from the pool.

    InteractionTimeZone

    Specifies the time zone of the date fields in which JCA Resource Adapter sends the date fields to the Oracle AIA components.

    • TZ names: Time zone set on the BRM server, if it is different than the JCA server time. For example, EST, PST, or CST.

    • UTC: Coordinated Universal Time is the time standard used across the world.

    • LOCAL: Specified to use the time zone of the server on which JCA Resource Adapter is running.

    JCA Resource Adapter converts date fields to the time zone set by InteractionTimeZone on outbound messages.

    MaxRequestListSize

    Specifies the maximum number of connection requests the connection pool can queue before returning a NAP_CONNECT_FAILED error.

    Typically, the requests are queued when all the connections in the connection pool are occupied.

    AverageOpcodeCount

    Specifies the average number of opcode calls per thread.

    zeroEpochAsNull

    Specifies how JCA Resource Adapter sets infinite date values.

    • true: Sends the date field value to NULL to represent an infinite start or end date.

    • false: Sends the date field value as the start of the epoch time.

    The default is false.

    JavaPcmSSL

    Specifies whether to enable SSL for JCA Resource Adapter:

    • true: Enables SSL for JCA Resource Adapter.

    • false: Disables SSL for  JCA Resource Adapter.

    The default is false.

    SslWalletLocation

    Specifies the location in which JCA Resource Adapter Oracle wallet resides. By default, the cwallet.sso file in a directory named wallet is packaged with the OracleBRMJCA15Adapter.rar file. Extract the wallet directory and copy this directory to the local directory path that is accessible from the Oracle Weblogic Server. This directory path needs to be updated in the SslWalletLocation entry.

    SslCipherSuites

    Specifies the cipher suites for JCA Resource Adapter. By default, BRM supports the TLS_RSA_WITH_AES_128_CBC_SHA cipher suite for JAVA PCM client.


  11. Click Save.

  12. Log out of WebLogic Server Administration Console.

You have successfully configured the adapter to connect to BRM.

Changing the JCA Resource Adapter Transaction Mode on Oracle WebLogic Server

By default, JCA Resource Adapter is deployed in XA Transaction mode. After the adapter is deployed, you can change the transaction mode.

For information about the transaction modes, see "About JCA Resource Adapter Transaction Management".

To change the JCA Resource Adapter transaction mode on the WebLogic server:

  1. Start the WebLogic Server domain if it is not already started.

  2. Log in to WebLogic Server Administration Console. The default is the following:

    http://localhost:8001/console
      
    
  3. In the Domain Structure tree, click Deployments.

    The Summary of Deployments pane appears.

  4. In the Deployments table, click the JCA Resource Adapter name.

    By default, the name is OracleBRMJCA15Adapter.

    The Settings for Adapter_Name pane appears.

  5. Click the Configuration tab.

  6. Click the Outbound Connection Pool tab.

  7. In the Outbound Connection Pool Configuration table, expand OracleConnectionFactory.

  8. Click eis/BRM, which is the name of the JNDI for JCA Resource Adapter.

  9. In the Properties tab, click the TransactionMode property value.

  10. Enter one of the following values:

    • For No Transaction mode, enter 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 Local Transaction mode, enter LOCAL_TRANSACTION.

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

    • For XA Transaction mode, enter XA_TRANSACTION.

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

      Note:

      If the applications using JCA Resource Adapter do not need XA transactions, use the Local Transaction mode to avoid the administrative overhead of managing pending transactions.
  11. Click Save.

  12. Click the Transaction tab.

  13. From the Transaction Support list, select the value that matches the transaction mode selected in step 10:

    • No Transaction for No Transaction mode

    • Local Transaction for Local Transaction mode

    • XA Transaction for XA Transaction mode

  14. Click Save.

  15. Log out of WebLogic Server Administration Console.

Changing the JCA Adapter Resource Connection Pool Parameter Settings on Oracle WebLogic Server

By default, JCA Resource Adapter uses the connection pool parameters to manage the number of connections to the database. After the adapter is deployed, you can change the number of connection pools.

To change the JCA Resource Adapter connection pool parameter settings on WebLogic Server:

  1. Start the WebLogic Server domain if it is not already started.

  2. Log in to WebLogic Server Administration Console. The default is the following:

    http://localhost:8001/console
    
  3. In the Domain Structure tree, click Deployments.

    The Summary of Deployments pane appears.

  4. In the Deployments table, click the JCA Resource Adapter name.

    By default, the name is OracleBRMJCA15Adapter.

    The Settings pane appears.

  5. Click the Configuration tab.

  6. Click the Outbound Connection Pool tab.

  7. In the Outbound Connection Pool Configuration table, expand the OracleConnectionFactory.

  8. Click eis/BRM, which is the name of the JNDI for JCA Resource Adapter.

  9. Click the Connection Pool tab.

  10. Set the connection pool parameters as needed for your environment.

    1. Set Initial Capacity to the same values as the BRMConnectionPoolMinSize property in the JCA Resources Adapter connection factory settings.

    2. Set Max Capacity to the same value as the BRMConnectionPoolMaxSize property in the JCA Resource Adapter connection factory settings.

    3. Set Capacity Increment to 1.

    4. From the Shrinking Enabled list, select false.

    5. Set Shrink Frequency Seconds to 0.

    Note:

    Ensure that BPEL Process Manager is configured with enough threads to support the number of maximum connections to the pool. See the discussion of BPEL Process Manager in Oracle Fusion Middleware Performance Tuning Guide for more information.
  11. Click Save.

  12. Restart WebLogic Server, which applies the changes.

Configuring JCA Resource Adapter Logging on Oracle WebLogic Server

JCA Resource Adapter supports Java Unified Logging (JUL), which enables the adapter to use the Java Unified Logging library.

Creating a Startup Class

To create a Startup class:

  1. Copy the BRM_home/apps/brm_integrations/jca_adapter/weblogic_startup.jar file to Domain_home/lib, where Domain_home is the directory in which JCA Resource Adapter is deployed.

  2. The arguments must be set to FINE, FINER, or FINEST on the Startup Class Deployment screen (FINEST gives the most detail, and FINE gives the least detail).

    Note:

    Set the deployment order of the startup class lower than the deployment order of the JCA Resource Adapter. See the discussion about changing the deployment order in Oracle WebLogic Server Administration Console Help for more information.
  3. Log in to WebLogic Server Administration Console. The default is:

    http://localhost:8001/console
    
  4. Click Lock and Edit.

  5. In the Domain Structure tree, expand Environment and then click Startup and Shutdown classes.

    The Startup and Shutdown Classes pane appears.

  6. Click New.

    The Configure a New Startup or Shutdown Class: Class Type pane appears.

  7. Select Startup Class and click Next.

    The Configure a New Startup or Shutdown Class: Startup Class Properties pane appears.

  8. In the Name field, enter BRMStartupClass.

  9. In the Class Name field, enter oracle.tip.adapter.brm.BRMLoggerStartUP.

  10. Click Next.

    The Configure a New Startup or Shutdown Class: Select Targets pane appears.

  11. From the Servers list, select the server on which to deploy the class and click Finish.

    The Startup and Shutdown Classes pane appears.

  12. Click BRMStartupClass.

    The Settings for BRMStartupClass pane appears.

  13. Select Run Before Application Activations and click Save.

  14. Click Activate Changes.

  15. Restart WebLogic Server, which applies the changes.

By default, log files are created in the Domain_home/BRMAdapterLogs directory, where Domain_home is the directory in which the WebLogic Server domain is configured.

Changing the Java Logging Level on Oracle WebLogic Server

You change the logging level by using JConsole.

  1. Go to the WebLogic_home/jdk160_05/bin directory, where WebLogic_home is the directory in which WebLogic Server is installed.

  2. Run the following command:

    jconsole
      
    

    The New Connection dialog box appears.

  3. Select Remote Process, enter the WebLogic Server host name and port number, enter your user name and password, and then click Connect.

    Note:

    When WebLogic Server is running on the same system, you can use Local Process without authentication. The Local Process list shows the WebLogic Server process name and PID.

    The Java Monitoring and Management Console pane appears.

  4. Click the MBeans tab.

  5. In the MBean tree, expand java.util.logging, then expand Attributes, and then select LoggerNames.

  6. Copy the oracle.tip.adapter.brm.BRMConnectionFactory line.

  7. In the MBean tree, expand java.util.logging and then select Operations.

    The Operation invocation pane appears.

  8. In the void setLoggerLevel p0 and p1 fields, paste the logger name and log level that you copied in step 0

  9. Click setLoggerLevel, which updates the log level.

  10. Close the Java Monitoring and Management Console pane.

For more information, see "Using JConsole" in Java SE Monitoring and Management Guide.

Changing the XA Transaction Timeout Period

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. For information about changing this timeout period, see your application server documentation.

    Note:

    If your application is WebLogic Server, set the JTA timeout to 3600 seconds. WebLogic Server uses the JTA timeout as the XA transaction timeout.
  • Oracle DM configuration file dm_xa_trans_timeout_in_secs entry. This timeout is used only if the application server XA transaction timeout is not specified.

    To change the Oracle DM XA transaction timeout period:

    1. Open the BRM_home/sys/dm_oracle/pin.conf file in a text editor.

    2. If necessary, add the dm_xa_trans_timeout_in_secs entry to the file:

      - dm dm_xa_trans_timeout_in_secs seconds
       
      

      where seconds is the number of seconds after the transaction is opened that it expires. The minimum value is 10, and the maximum value is 5184000 (60 days). The default value is 3600 (1 hour).

    3. Save and close the file.

    4. Restart the Oracle DM instance.

Testing JCA Resource Adapter Configuration and BRM Connectivity

Use the BRMAdapterServletClient application to test the JCA Resource Adapter configuration and connectivity to BRM. The application enables you to provide input to an opcode and view its output.

To set up the BRMAdapterServletClient application, deploy and configure it on your Oracle WebLogic Server.

Note:

Verify that JCA Resource Adapter is deployed. Set the deployment order of the BRMAdapterServletClient application higher than the deployment order of JCA Resource Adapter. See the discussion about changing the deployment order in the Oracle WebLogic Server Administration Console Help for more information.

To deploy BRMAdapterServletClient application on your application server:

  1. Copy the BRMAdapterServletClient.war file from the BRM_home/apps/brm_integrations/jca_adapter directory to a location that is accessible to the adapter deployment tool.

  2. Specify to deploy the BRMAdapterServletClient application in the same instance as that of JCA Resource Adapter.

  3. Upload the BRMAdapterServletClient.war archive file.

  4. Run and test the adapter. You can access the application's default page at the following URL:

    http://HostName:PortNumber/BRMAdapterServletClient
      
    

    where HostName is the host name of the machine where the application is deployed and PortNumber is the port where the application is deployed.

Manually Committing or Rolling Back XA Transactions

If an XA transaction expires after being successfully prepared, a system administrator with the SYSDBA privilege can manually commit or roll back the transaction.

To commit or roll back XA transactions manually:

  1. Using SQL*Plus, log in to your database as the SYSDBA user:

    sqlplus sys@databaseAlias as sysdba
     
    

    where databaseAlias is the database alias of your BRM database.

  2. Run the following command, which retrieves the local transaction IDs for all pending XA transactions that were successfully prepared:

    select LOCAL_TRAN_ID,  GLOBAL_TRAN_ID from DBA_2PC_PENDING where  STATE = 'prepared';
     
    

    Timed-out XA transactions are stored in the DBA_2PC_PENDING view. See "About the DBA_2PC_PENDING Table" in BRM System Administrator's Guide.

  3. Do one of the following:

    • To commit the transaction, run the following command:

      commit force 'LocalTranID';
       
      
    • To roll back the transaction, run the following command:

      rollback force 'LocalTranID';
       
      

    where LocalTranID is the ID of the local transaction branch that you are committing or rolling back.

    Note:

    JCA Resource Adapter uses the global transaction ID to identify the global transaction to which the local transaction branch belongs.
  4. If your global transaction manager does not issue forget requests, purge the manually processed transaction from the DBA_2PC_PENDING view by using the EXECUTE DBMS_TRANSACTION.PURGE_LOST_DB_ENTRY() procedure.

    For more information, see the discussion about how to purge a distributed transaction from a database (Doc ID 159377.1) on the My Oracle Support Web site:

    https://support.oracle.com