5 Configuring Java Service Request Processors and Web Services

This chapter describes the Java service request processor (JSRP) and a Web Service interface to the JSRP.

About Java Service Request Processor Servers

A JSRP is an Oracle Communications ASAP server that controls service request reception and translation from an upstream system and service activation notifications from ASAP back to the upstream system.

With an JSRP you can:

Generate and submit work orders
Subscribe and manage work order events
Query work order information

The JSRP accepts and translates native service requests (work orders) into Common Service Description Layer (CSDL) commands. Using information from the work order, the SRP determines the parameters that are associated with the CSDL command and sends them to the Service Activation Request Manager (SARM) for provisioning.

You can implement the following types of JSRPs, depending on the upstream technology being employed.

JSRP and Web Service: Provides a standardized OSS through Java interface and Web Service interface into ASAP's provisioning functionality within a WebLogic server instance.

For more information about the JSRP and Web Service, see "About JSRP, Web Service, and OCA SRP Components".
Custom Java SRP: You can create a custom JSRP not based on a WebLogic server instance using the information provided in ASAP Java Online Reference. For more information about configuring a custom JSRP, see "Configuring a Custom Java SRP client".
OCA SRP: Used internally by the ASAP Order Control Application (OCA) client. OCA SRP co-exists with Java SRP in WebLogic and shares some of the Java-based APIs used in JSRP.

For more information on the OCA SRP, see "Configuring a OCA SRP".

About JSRP, Web Service, and OCA SRP Components

The JSRP is an upstream component into ASAP that provides a standardized OSS through Java (OSSJ) interface into the ASAP provisioning functionality and also a Web Services API implementation.

Figure 5-1 displays a system-level view of the JSRP. The JSRP receives requests from an upstream system, potentially an order manager: for example, Oracle Communications Order and Service Management (OSM) or a customer care system. Requests are translated into ASAP commands, which are then submitted to the SARM for processing.

Figure 5-1 JSRP, System Level View

The JSRP provides two types of interfaces: XML over JMS and Java value types (JVT) over RMI/IIOP. The JSRP is fully compliant with the OSSJ Service Activation API version 1.0.

In addition to the JSRP, Web Service provides an interface for SOAP/JMS messages. The Web Service implementation translates these SOAP/JMS messages into JVT work orders and sends them to the JSRP's JVT interface.

For more information about these interfaces, see "About the JSRP Server and Web Service Interfaces".

The JSRP and Web Service implementation are situated between the SARM and clients designed to send messages to either Web Service, JVT, or JMS interfaces. These clients are located on a remote application, such as OSM.

Oracle recommends that you create a Store and Forward (SAF) agent for requests and responses to and from the JMS or Web Service interfaces and the JMS or Web Service clients and a JMS bridge for work order state changes from ASAP to the JMS or Web Service clients. For more information about SAF and the JMS bridge, see "About Connecting JSRP JMS and Web Service Interfaces to a Remote Application".

The JVT interface does not require SAF or the JMS bridge.

The following list summarizes the components required for the two JSRP interfaces and the Web Service interface to a remote application (for example, OSM):

JSRP JMS Interface to and from SAF and JMS Bridge to and from JSRP JMS Client (OSM)
ASAP Web Service interface to and from SAF and JMS Bridge to and from JSRP Web Service Client (OSM)
JSRP JVT Interface (RMI) to and from JSRP JVT Client (OSM)

For more information about creating a JVT or JMS Client, see the discussion about developing Java SRP client applications in ASAP Java Online Reference available from the Oracle software delivery Web site along with the ASAP installation files. ASAP Java Online Reference also provides a Java library for the JVT interface and lists the XML schemas used for constructing XML-based work order messages.

For more information about the Web Service API and the Web Services Description Language (WSDL) file, see ASAP Developer's Guide.

For information about sample JVT and JMS clients and source files that you can use to test the Java SRP, go to ASAP_Home/samples/jsrp/README.txt.

The JMS, JVT, and Web Services JMS modules, connection pools, and JDBC stores are automatically configured when you install ASAP. For information about these components, see "About the JSRP Server and Web Service Interfaces".

The configuration of the Java SRP deployment descriptors are automatically completed when you install ASAP. If you must fine-tune the deployment descriptor attributes of the Java SRP, see "Modifying JSRP Parameters (Deployment Descriptors) in WebLogic".

The implementation of the Java SRP and Web Services API does not affect any provisioning logic in the existing ASAP product. Support for OSSJ and Web Services is implemented as translations to and from existing types and structures in ASAP, to OSSJ and Web Services conferment types and structures.

As with the other types of SRPs, the Java SRP and Web Services API allows the client to generate and submit work orders, manage work order events, and retrieve work order information.

Note:

The implementation of the Java SRP and Web Services API does not affect any provisioning logic in the existing product and is consistent with other upstream interfaces (C++ SRP, OCA SRP).

About the JSRP Server and Web Service Interfaces

The configuration of the WebLogic Server involves defining server resources such as connection pools, JDBC stores, and JMS modules such as connection factories, queues, and topics that are required for the Java SRP and the Web Services implementation. When you install ASAP, the Java SRP and Web Service configuration are automatically created. You can verify the Java SRP and Web Service configuration using the WebLogic management console.

Table 5-1 lists and describes the JMS modules used by the JSRP interfaces and Web Service.

Table 5-1 Java SRP, OCA SRP, and Web Services JMS Modules

JMS Module Name	Description
CMWSAdapterQueue	The publisher to the CMSW queue is Design Studio. It publishes ASAP Cartridges. The subscriber to this queue is the CMSW Adapter located in WebLogic.
ErrorQueue	The publisher for the ErrorQueue is WebLogic. If any error happens within any WebLogic queue, this message is published to the ErrorQueue. This is an internal WebLogic queue and does not effect ASAP components. For more information about this queue, see the WebLogic Server documentation.
JVTEventTopic	The publisher for the JVTEventTopic is the JSRP. Work order events get published to this topic. Subscribers are JSRP and Web Service clients that wish to receive notification of JSPR Events published to the JVTEventTopic in the form of Java object responses.
MessageQueue	The JSRP client (for example OSM) publishes JMS requests to this queue in the form or JSRP work orders. The subscriber to this queue is the JSRP server.
OCAEventTopic	The publisher for the OCAEventTopic is the OCA SRP. Work order events get published to this topic. Subscribers are OCA clients that wish to receive notification of OCA events published to the OCAEventTopic in the form of Java object responses.
OCAMessageQueue	The OCA client publishes JMS requests to this queue in the form or OCA work orders. The subscriber to this queue is the OCAJ server.
TopicConnectionFactory	The JSRP server, and OCA server uses this TopicConnectionFactory to create a topic publisher that sends ASAP events to XVTEventTopic, JVTEventTopic, and OCAEventTopic.
WebServiceQueue	The Web Services client (for example OSM) publishes SOAP requests to this queue in the form or Web Service work orders. The subscriber to this queue is the Web Services server. It decomposes the SOAP Work order, creates a JVT work order, and submits the work order via the JSRP RMI interface. This interface is shared with JVT.
XVTEventTopic	The publisher for the XVTEventTopic is the JSRP. Work order events get published to this topic. Subscribers are JSRP clients that wish to receive notification of JSPR Events published to the XVTEventTopic in the form of xml responses.

About Connecting JSRP JMS and Web Service Interfaces to a Remote Application

Oracle recommends that you create a SAF agent and JMS bridge between the ASAP WebLogic server and the remote application WebLogic server. Oracle recommends this SAF agent and JMS bridge for the JMS or Web Service interfaces to ensure reliable communication.

Figure 5-2 illustrates an example SAF and JMS bridge configuration between the Web Service interface on ASAP and a Web Service client on a remote application, in this case, OSM.

Figure 5-2 SAF and JMS Bridge Between OSM and ASAP

In this example, an OSM SAF agent sends requests to the ASAP request queue, and ASAP returns responses through the ASAP SAF agent to the OSM reply-to queue. In addition, ASAP sends work order state changes from the JSRP XVTEventTopic through a JMS bridge with a SAF agent to the OSM event queue.

For detailed instructions for creating SAF and JMS bridges between ASAP and OSM, see Configuring WebLogic Resources for OSM Integration With ASAP And UIM On Different Domains (Doc ID 1431235.1) knowledge article in Oracle Support, https://support.oracle.com. This article is applicable to any remote application that uses a WebLogic JMS server to send and receive Web Service or JMS messages.

Modifying JSRP Parameters (Deployment Descriptors) in WebLogic

This section provides information about how to modify JSRP parameters or deployment descriptors in WebLogic Server. You can update the JSRP parameters described in Table 5-2 by using WebLogic Workshop (Eclipse component) or by editing the ejb-jar.xml file manually.

Table 5-2 JSRP Configuration Parameters (Deployment Descriptors)

Parameter Name	Type	Description
SERVICE_TYPE	java.lang.String	Do not change this parameter. This parameter differentiates between JSRP and OCA instances, and can be either JSRP or OCA.
UnidFormat	java.lang.String	This parameter defines the work order (WO) format template. If the JSRP does not provide the WO_ID, the WO_ID is generated based on the format template.
APPLICATION_DN	java.lang.String	Do not change this parameter.
OCA_ATTEMPTS	java.lang.Integer	This parameter configures the number of times that the OCA Server tries to submit a WO to SARM.
VALIDATION_ENABLED	java.lang.Boolean	This parameter, when enabled, validates the JSRP WO requests against the XML Schema. Enabling this attribute can provide additional security. For more information, see "Configuring Validation of Received Data".
BACKWARD_COMPATIBLE_SCHEMA	java.lang.Boolean	It's flag to indicate if it's backward compatible with previous format.
INCLUDE_SERVICE_ACTION_DETAIL	java.lang.Boolean	Includes service action details in events.
USE_ORIGINAL_INSTANCE_NUMBER	java.lang.Boolean	This indicate in even if set to true, then the JSRP uses the original instance number from the primaryKey and type contained in a message received from the Service Request Translator (SRT). if (useOriginalServiceInstanceNumbers()) { typeElement.appendChild( pKeyText ); idElement.appendChild( typeText ); } else { typeElement.appendChild( typeText ); idElement.appendChild( pKeyText ); }
NO_LISTENING_THREAD	java.lang.Boolean	Disables the SARM listening port for the JSRP. Set this parameter to false.
NO_WAIT_START_ORDER	java.lang.Boolean	Disables the JSRP functionality that waits for a start order messages from the SARM. Set this parameter to false.

To edit the JSRP parameter file manually:

Go to WebLogic_domain/servers/WebLogic_server/upload/asapENV_ID/app (where the WebLogic_domain is the installation directory for your WebLogic Server domain, WebLogic_server is the name of your WebLogic Server domain, and ENV_ID is the ASAP environment ID.

Do the following:

jar xvf asapENV_ID.ear srp.jar 
jar xvf srp.jar META-INF/ejb-jar.xml

Edit ejb-jar.xml to modify JSRP parameters. For example:

    <env-entry>        <env-entry-name>APPLICATION_DN</env-entry-name>        <env-entry-type>java.lang.String</env-entry-type>        <env-entry-value>System/dc2/ApplicationType/ServiceActivation/Application/1-0;7-2;ASAP/Comp/</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>SRP</env-entry-name>        <env-entry-type>java.lang.String</env-entry-type>        <env-entry-value>JSRPdc2</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>SRP_BACKWARD_COMPATIBLE</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <env-entry-value>true</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>DEFAULT_JMS_REPLY_TO</env-entry-name>        <env-entry-type>java.lang.String</env-entry-type>        <env-entry-value>System/dc2/ApplicationType/ServiceActivation/Application/1-0;7-2;ASAP/Comp/XVTEventTopic</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>VALIDATION_ENABLED</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <env-entry-value>false</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>BACKWARD_COMPATIBLE_SCHEMA</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <env-entry-value>false</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>INCLUDE_SERVICE_ACTION_DETAIL</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <env-entry-value>false</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>USE_ORIGINAL_INSTANCE_NUMBER</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <env-entry-value>false</env-entry-value>      </env-entry>      <env-entry>        <env-entry-name>NO_LISTENING_THREAD</env-entry-name>        <env-entry-type>java.lang.Boolean</env-entry-type>        <!-- changed to false to activate ASAP behavour -->        <env-entry-value>false</env-entry-value>      </env-entry>     ...

Do the following:

jar uvf srp.jar META-INF/ejb-jar.xml 
jar uvf asapENV_ID.ear srp.jar

Redeploy the asapENV_ID.ear file.

Configuring Validation of Received Data

You can configure the JSRP to validate any ASAP RPC parameters of "char" type if VALIDATION_ENABLED in the JSRP deployment descriptor is set to "true". If the maximum lengths are exceeded, the JSRP throws an exception. For example, in the XML/JMS interface, if specifying <mslv-sa:organizationUnit>POTS12345678</mslv-sa:organizationUnit> in createOrderByValueRequest (which exceeds the maximum length), the following exception is thrown:

<sa:createOrderByValueException
xmlns:co="http://java.sun.com/products/oss/xml/Common"
xmlns:mslv-sa="http://www.metasolv.com/oss/ServiceActivation/2003"
xmlns:sa="http://java.sun.com/products/oss/xml/ServiceActivation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<sa:illegalAttributeValueException>
<co:message>String attribute value[POTS12345678] exceeding its maximum length[8]</co:message>
</sa:illegalAttributeValueException>
</sa:createOrderByValueException>

Exceptions also will be thrown in the JVT interface.

Setting Log Levels

You can configure the Java SRP to filter log messages that are being written into the WebLogic log file by changing the level of message severity.

There are three levels of severity for the Java SRP:

info
warning
error

By default, the asapSeverityLevel is error.

See ASAP System Administrator's Guide for details on configuring the logging levels.

Uninstalling the Java SRP

For more information on uninstalling the Java SRP, see the procedure for uninstalling WebLogic in ASAP Installation Guide.

Configuring a Custom Java SRP client

You can use the Control server to manage (start, stop, auto-restart) a custom JSRP client that is not based in a WebLogic server like any other ASAP component. Perform the following steps to configure a Java SRP Client.

Write a custom Java SRP client by extending the ASCAppl class (see the sample code below).
Implement applMain() method, which is the main function of the Java SRP client (see "Sample Code for a Custom JSRP Client").
Implement the initialize() method instead of providing a specialized constructor, if necessary (see "Sample Code for a Custom JSRP Client").

Using SACT, populate the Control database and ASAP Environment (tbl_appl_proc and tbl_component) for the new Java SRP client.

<activationConfig xmlns="http://www.metasolv.com/ServiceActivation/2003/ActivationConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.metasolv.com/ServiceActivation/2003/ActivationConfig 
M:\hlam_view\ASAP_base\ASAP\jmx\xsd\ActivationConfig.xsd">

<nonControlManagedServer name="JSRPenvid" xsi:type="JSRPServerType">        <description>Java SRP</description>        <system>envid</system>        <territory>envid</territory>        <diagnosticFilename>JSRPenvid.diag</diagnosticFilename>        <diagnosticLevel>LOW_LEVEL</diagnosticLevel>        <SARMListenPort>40070</SARMListenPort>        <SRPListenHostname>                <IPaddress>10.156.53.74</IPaddress>        </SRPListenHostname>        <SRPListenPort>40077</SRPListenPort></nonControlManagedServer>
 
</activationConfig>

Write the script to run the Java SRP client (see "Sample Script to Run the Custom JSRP Client").

Sample Code for a Custom JSRP Client

package com.metasolv.activation;

import java.util.*;
import java.io.*;
import java.sql.SQLException;
import java.text.*;
import com.mslv.activation.server.*;

public class SampleJSrpClient extends ASCAppl
{

 public void initialize()
 {

        super.initialize();
        // Do additional initialization
……..

..
.

 public void applMain()
 {

    for(;;) {
        try {
            // Do actual process for JSRP client
………………
        } catch(Exception ex ) {  
        }
    }

Sample Script to Run the Custom JSRP Client

#!/bin/ksh

#
# =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
#
# (c) 2008 Oracle. 
# The CLASSPATH variable is used by the primordial class loader in the java virtual

Configuring a OCA SRP

The OCA SRP is similar to Java SRP and resides in WebLogic. The OCA SRP shares some of the Java-based APIs used in JSRP. The OCA system includes a GUI based client for configuring the OCA SRP and integrates the work order related main functionality in this single program.

Setting OCA SRP Configuration Parameters

In addition to the parameters contained in the previous table, the following parameters in ASAP_Home/config/OCA.cfg were used by the deprecated CORBA SRP emulator. Now, they are required by the new OCA SRP.

Table 5-3 describes the configuration parameters that must be set in the ASAP_Home/config/OCA.cfg configuration file. For more information about configuring the OCA client, see ASAP Order Control Application User's Guide.

Table 5-3 Session Configuration Parameters

Configuration Variable	Required	Default Value	Description
HOST	Yes	localhost	Name of host machine where WebLogic is installed. The session associated OCA SRP server is running as an application of this WebLogic.
PORT	Yes	2345	Port number on which WebLogic is listening. The session associated OCA SRP server is running as an application of this WebLogic.
ENV_ID	Yes	S123	Environment ID of ASAP instance. The session associated OCA SRP server is a component of this ASAP system.
SYSTEM_NAME	Yes	OCA_S123	Name of the OCA Server to which the OCA client connects. Used to support multiple ASAP systems from a single client.

Table 5-4 Global Configuration Parameters

Configuration Variable	Required	Default Value	Description
SYSTEM_NAME	Yes	OCA_S255	Name of the ASAP system to which the OCA client connects. Used to support multiple ASAP systems from a single client.
LANGCODE	No	USA	Language code for the language in which translatable information is returned to and displayed by the client. If applied, all translatable fields are shown in the OCA client native language, as specified by the LANGUAGE variable. A language other than the default language (USA) must be configured in ASAP.
IDLETIMEOUT	No	0	Maximum idle time, in minutes, after which the OCA SRP server terminates the OCA client connection. Set to zero (0) to disable this feature.
DATE_FORMAT	-	-	dd/MM/yyyy or MM/dd/yyyy
TIME_FORMAT	-	-	AM_PM (12-hour clock with an AM or PM designation) or NON_AM_PM (a 24-hour clock).
OCA_EVENTS_SUPPORTED	Yes	True	The flag should be false when connecting to servers on the HP10.20 platform. Events are not supported for this platform.
MAXW_OPEN_DETAILS	No	3	The number of detail windows a user can have open at one time.