This chapter contains information about customizing Oracle Communications Billing and Revenue Management (BRM) Web Services Manager.
Before reading this chapter, you should be familiar with implementing web services.
To expose custom opcodes as web services, enable Web Services Manager to support custom opcodes. For more information on custom opcodes, see "Using Custom Opcodes" in BRM Developer's Guide.
Note:
Before you customize an opcode for a web service in Web Services Manager, implement the custom opcode in BRM.To enable Web Services Manager to support custom opcodes:
Do one of the following:
Create the CustomOp.java file by entering the following command:
parse_custom_ops_fields -L pcmjava -I input -O output -P java_package
where:
input is the header file you create for your custom opcodes and fields.
output is the memory-mapped file or directory for the output of the script. output must be a directory having some correspondence with the Java package. For example, if java_package is in com.portal.classFiles, output must be f:/mysource/com/portal/classFiles.
java_package is the Java package in which to put the generated classes.
For more information, see the discussion about the parse_custom_ops_fields utility in BRM Developer's Guide.
Manually create the CustomOp.java file.
Verify that the CustomOp.java file contains the following:
The opcode-name-to-opcode-number mapping for all the custom opcodes in the file.
Important:
Verify that the mapping includes the full name of each opcode. If any opcode name is truncated, replace the truncated name with the full name.The opToString method, which converts opcode numbers to opcode names.
The stringToOp method, which converts opcode names to opcode numbers.
The following is a sample CustomOp.java file:
public class CustomOp {
public static final int CUSTOM_OP_ACT_INFO= 100000;
public static final int CUSTOM_OP_READ_ACT_PRODUCT = 100001;
public static String opToString( int op ) { try {
java.lang.reflect.Field[] flds =
CustomOp.class.getFields();
for( int i = 0; i < flds.length; i++ ) {
try {
int val = flds[i].getInt(null);
if( val == op ) {
return flds[i].getName();
}
} catch( IllegalAccessException e ) { continue;
} catch( IllegalArgumentException e ) { continue; }
}
} catch( SecurityException e ) {}
return null;
}
public static int stringToOp( String op ) {
try {
java.lang.reflect.Field[] flds =
CustomOp.class.getFields();
for( int i = 0; i < flds.length; i++ ) {
try {
String name = flds[i].getName();
if( name.equals(op) ) {
return flds[i].getInt(null);
}
} catch( IllegalAccessException e ) { continue;
}
catch( IllegalArgumentException e ) { continue; }
}
} catch( SecurityException e ) {}
return -1;
}
}
Compile the CustomOp.java file into the CustomOp.class file by entering the following command:
javac -d . path/CustomOp.java
For example:
javac -d . com/portal/classFiles/CustomOp.java
Package the CustomOp.class file into the CustomFields.jar file by entering the following command:
Note:
Make sure the JRE version that was used to generate the CustomFields.jar file is the same or lower than the version of the WebLogic Server JRE.jar -cvf CustomFields.jar path.CustomOp.class
For example:
jar cvf CustomFields.jar com.portal.classFiles.CustomOp.class
Make the CustomFields.jar file available to Web Services Manager by doing one of the following:
If you have not deployed Web Services Manager, do the following:
Copy the path/CustomFields.jar file to the local_dir/WEB-INF/lib directory, where path is the path to the CustomFields.jar file (for example, com/portal/classFiles).
Open the BRM_home/deploy/web_services/Infranet.properties file in a text editor.
Add or modify the following entry:
infranet.custom.field.package = package
where package is the name of the package that contains the CustomOp.java file; for example, com.portal.classFiles.
Add all the custom fields to the Infranet.properties file.
Save and close the file.
Copy the BRM_home/deploy/web_services/Infranet.properties file to the local_dir/WEB-INF/classes directory or the home directory on the machine on which you installed WebLogic Server.
If you have deployed Web Services Manager, do the following:
Copy the path/CustomFields.jar file to the local_dir/WEB-INF/lib directory.
where local_dir is the directory in which you deployed Web Services Manager on your application server.
Open the Webservices_deployment_dir/WEB-INF/classes/Infranet.properties file in a text editor.
Add or modify the following entry:
infranet.custom.field.package = package
where package is the name of the package that contains the
CustomOp.java file; for example, com.portal.classFiles.
Add all the custom fields to the Infranet.properties file.
Save and close the file.
Web Services Manager uses schema files to validate data it sends to or receives from BRM.
To generate schema files for your system:
If you modified any opcodes, generate schemas for the opcodes in your BRM system. See "Generating Schema for Your Opcodes".
Generate schemas for the storable classes and subclasses in your BRM system. See "Generating the Schema for Your Storable Classes and Subclasses" in BRM JCA Resource Adapter.
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" in BRM JCA Resource Adapter.
Note:
After generating the opcode and storable class schema files, copy the schema files to a location that is accessible to the Web Services Manager. Make sure that this location is the same as the location that is 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" in BRM JCA Resource Adapter.The Web Services Manager 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 Web Services Manager or if you added support for new opcodes, you must generate XSD schema files for the opcodes.
Note:
Before you customize an existing opcode specification, ensure that you update the opcode specification in the BRM system.After you customize web services, copy the customized schema files and the WSDL files to the infranetwebsvc.war file.
To generate schema files for an opcode that you customized and Web Services Manager already supports:
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 you installed the BRM components.
Do one of the following:
For web services that take payload as XML string:
Run the pin_opspec_to_schema utility. See "Creating Opcode Specification Schema Files".
Copy the customized XSD files to the BRM_home/deploy/web_services/schemas directory.
For web services that take payload as XML element:
Run the pin_opspec_to_schema_v2 utility. See "Creating Opcode Specification Schema Files".
Copy the customized XSD files to the BrmWebServices/WEB-INF/wsdll directory.
You must create opcode flist specification files for opcodes that you customize or add to the Web Services Manager. Create the specification XML files by following the BRM_home/apps/brm_integrations/stylesheets/opspec.xsd file.
You then convert the opcode flist specification XML files into XSD schema by using the pin_opspec_to_schema and pin_opspec_to_schema_v2 utilities.
To convert opcode flist specification XML files into XSD schema, go to the BRM_home/apps/brm_integrations directory and do the following:
For web services that supports XML string payload, run the following command:
pin_opspec_to_schema -i input_file [-o output_file]
For web services that supports XML element payload, run the following command:
Note:
Before you run the following command, specify the BRM installation directory in the pin_opspec_to_schema_v2 utility by replacing $PIN_HOME with BRM_home.pin_opspec_to_schema_v2 -i input_file > output_file
where:
input_file specifies 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 creates the XSD schema output file using the name you specify. By default, the utility creates a file named opcodename.xsd in the directory from which you run the utility.
You can also create XSD schema for web services that take payload as XML element by using the pin_opspec_to_schema_v2 XSD generator utility that is located in the BRM_home/bin directory.
To create the XSD schema file by using the pin_opspec_to_schema_v2 utility, run the following command using Groovy:
groovy pin_opspec_to_schema_v2 -i input.xml > output.xsd
where:
input.xml specifies the name of the opcode's XML flist specification
output.xsd creates the XSD schema output file using the name you specify
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 fields, you must customize the pin_opspec_to_schema.xsl style sheet to handle your custom fields.
For a list of the supported BRM data types, see "Understanding the BRM Data Types" in BRM Developer's Guide.
You can extend Web Services Manager to support custom web services. Before you create a custom web service or customize an existing web service in Web Services Manager, implement your custom opcodes in the BRM system. For more information on custom opcodes, see "Using Custom Opcodes" in BRM Developer's Guide.
To create a custom web service, do one of the following:
If you have deployed infranetwebsvc.war, create a custom web service that supports XML string payload. See "Creating a Custom Web Service that Supports XML String Payload."
If you have deployed BrmWebServices.war, create a custom web service that supports XML element payload. See "Creating a Custom Web Service that Supports XML Element Payload."
To create a custom web service that supports XML string payload:
If you created an opcode with custom fields for your custom web service, configure BRM to recognize the custom fields.
Create the XML specifications for your custom opcodes. See "Creating Opcode Specification Schema Files".
Create a /service storable class for your custom web service. See the BRM_home/deploy/web_services/sample/SampleWebService.java.template sample.
Note:
When you compile the /service storable class, use the libraries from the infranetwebsvc/WEB-INF/lib directory in addition to the JDK and JAX-WS reference implementation (RI).Build and generate custom web services jar file in an integrated development environment IDE or by using an Ant build file as follows:
Create the following directory structure in a local directory (local_dir) on the machine:
/src /classes /jar
Copy your custom service classes into the local_dir/src directory.
Create custom_services.xml as an Ant build file.
The following is a sample custom_services.xml file:
<?xml version="1.0"?>
<project name="Custom WebServices build file" default="all" basedir=".">
<property name="buildDir" value="classes"/>
<property name="srcDir" value="src"/>
<!-- define the classpath -->
<path id="classpath">
<pathelement path="${buildDir}"/>
<pathelement path="jar/web_services.jar"/>
<pathelement path="jar/webServicesUtils.jar"/>
</path>
<target name="all" custom_jar" description="build everything" />
<!-- compile task -->
<target name="compile" description="compile source files" >
<echo>" Compiling JAX-WS impl classes"</echo>
<javac srcdir="${srcDir}"
destdir="${buildDir}"
classpathref="classpath"
debug="on"
source="1.5"
/>
</target>
<!--Create custom service jar -->
<target name="custom_jar" depends="custom_service_gen, compile" description="generate jar file" >
<jar jarfile="custom_services.jar" basedir="${buildDir}" >
</jar>
</target>
</project>
Generate and build your custom web services by running the following command:
ant -file custom_services.xml
Add all the custom field enum constants to the Infranet.properties file. See "Connecting Web Services Manager to the BRM System" for more information.
Package your custom web service with the infranetwebsvc.war file by doing the following:
Extract the infranetwebsvc.war file to a local directory (local_dir) on the machine.
Do one of the following:
(WebLogic server) Add your custom service URL mapping to the local_dir/WEB-INF/Web.xml file. It should be similar to existing URL mapping.
(Apache Tomcat and GlassFish servers) Add your custom service implementation class to the local_dir/WEB-INF/sun.jaxws.xml file.
Copy your custom_services.jar file into the local_dir/WEB-INF/lib directory.
Copy your CustomFields.jar file into the local_dir/WEB-INF/lib directory.
Delete the existing infranetwebsvc.war file.
Create a new infranetwebsvc.war file by running the following command:
jar -cvf infranetwebsvc.war *
To create a custom web service that supports XML element payload:
If you created an opcode with custom fields for your custom web service, configure BRM to recognize the custom fields.
Create a WSDL file for the web service. See "Generating WSDL Files for Web Services" in BRM JCA Resource Adapter.
Create a WSDL file for your custom web service. See the BRM_home/deploy/web_services/BrmWebServices.war/WEB-INF/wsdl sample.
Create the XML specifications for your custom opcodes. See "Creating Opcode Specification Schema Files".
Build and generate custom web service classes for your custom service as follows:
Create the following directory structure in a local directory (local_dir) on the machine on which BRM is installed.
/wsdl /src /classes /jar
Copy your custom WSDL files and schema (XSD) files into the local_dir/wsdl directory.
Copy the BrmWebServices.war/WEB-INF/wsdl/BRMWebServiceException.xsd file into the local_dir/wsdl directory.
Copy the mentioned files from BrmWebServices.war/WEB-INF/lib/file into the local_dir/jar directory.
web_services.jar webServicesUtils.jar xmlparserv2.jar
Create custom_services.xml as an Ant build file.
The following is a sample custom_services.xml file:
<?xml version="1.0"?>
<project name="Custom BRM WebServices build file" default="all" basedir=".">
<property name="buildDir" value="classes"/>
<property name="srcDir" value="src"/>
<property name="wsdlDir" value="wsdl"/>
<property name="pinwsgen" value="pin_wsgen"/>
<!-- define the classpath -->
<path id="classpath">
<pathelement path="${buildDir}"/>
<pathelement path="jar/web_services.jar"/>
<pathelement path="jar/webServicesUtils.jar"/>
<pathelement path="jar/xmlparserv2.jar"/>
</path>
<!-- create Source files from WSDL and XSDs -->
<target name="custom_service_gen" description="Create java source files from wsdl" >
<exec executable="BRM_home/deploy/web-services/pin_wsgen/pin_wsgen" failonerror="true">
<arg value="-s"/>
<arg value="src"/>
<arg value="-d"/>
<arg value="${buildDir}"/>
<arg value="-p"/>
<arg value="com.portal.jax.'YourPackageSubdirName' "/>
<arg value="${wsdlDir}/'YourCustomServices_v2.wsdl'/>
</exec>
</target>
<target name="all" depends="custom_service_gen, custom_jar" description="build everything" />
<!-- compile task -->
<target name="compile" depends="custom_service_gen" description="compile source files" >
<echo>" Compiling JAX-WS impl classes"</echo>
<javac srcdir="${srcDir}"
destdir="${buildDir}"
classpathref="classpath"
debug="on"
source="1.5"
/>
</target>
<!--Create custom service jar -->
<target name="custom_jar" depends="custom_service_gen, compile" description="generate jar file" >
<jar jarfile="custom_services.jar" basedir="${buildDir}" >
</jar>
</target>
<!--ant clean task -->
<target name="clean" description="remove derived objects" >
<delete dir="classes/com"/>
<delete dir="custom_service.jar"/>
</target>
</project>
where:
BRM_home is the directory in which BRM is installed.
YourCustomServices_v2 is the custom service WSDL file name.
YourPackageSubdirName is the package directory for your custom service.
Generate and build your custom web services by running the following command:
ant -file custom_services.xml
Add all the custom field enum constants to the Infranet.properties file. See "Connecting Web Services Manager to the BRM System".
Package your custom web service with the BrmWebServices.war file as follows:
Extract the BrmWebServices.war file to a local directory (local_dir) on the machine on which you installed your application server.
Do one of the following:
(WebLogic server) Add your custom service URL mapping to the local_dir/WEB-INF/Web.xml file. It should be similar to existing URL mapping.
(Apache Tomcat and GlassFish servers) Add your custom service implementation class to the local_dir/WEB-INF/sun.jaxws.xml file.
Copy your custom WSDL files and schema (XSD) files into the local_dir/WEB-INF/wsdl/ directory.
Copy your custom_services.jar and all custom com.portal.classFiles into the local_dir/WEB-INF/classes and local_dir/WEB-INF/classes/com/portal/jax/classFiles directory respectively.
Delete the existing BrmWebServices.war file.
Create a new BrmWebServices.war file by running the following command:
jar -cvf BrmWebServices.war *