This chapter provides information on creating Java client applications that communicate with Oracle Communications Billing and Revenue Management (BRM) by using the Java Portal Communication Module (Java PCM) Application Programming Interface (API).
For information on customizing Customer Center and Self-Care Manager, BRM Java customer management applications, see "Customizing the Customer Center Interface" and "Customizing the Self-Care Manager Interface".
You use the classes and their methods in the Java PCM API to write Java client APIs, see Java PCM API.
To use the Java PCM package, you must have the following skills and experience:
Experience in developing Java applications
A good understanding of the BRM architecture and the following concepts:
PCM opcodes
Portal Information Network (PIN) libraries
flists (field lists)
Context (PortalContext)
Buffers (Buffer, FileBuffer, ByteBuffer)
Fields (Fields)
Portal object IDs (POIDs)
For information on BRM architecture and concepts, see the following topics:
Use the Java PCM API on a supported version of the Java Development Kit (JDK). See "BRM Software Compatibility" in BRM Installation Guide.
The Java PCM API consists of a set of Java classes that represent the BRM C data structures, such as flists, fields, context, and POIDs, that are defined in the pcm.h file.
For information on BRM data types, see "Understanding the BRM Data Types".
For information on flists, see "Understanding Flists and Storable Classes".
The Java API differs from the C API in the following ways:
Timestamps and strings are represented by the Date and String Java classes. There is a separate array class for flist arrays (SparseArray).
The information stored in the C error buffer is part of EbufException in the Java PCM package.
In the Java PCM package, opcodes are constants in the PortalOp class and are named without the PCM_OP prefix. For example, PCM_OP_READ_FIELD in the C API is PortalOp.READ_FIELD in the Java PCM package.
For type safety, field names are provided as classes.
Field names follow the Java class-naming conventions and use mixed case without the underscores. The Java field classes in the Java PCM package use the C #define name without the PIN_ prefix. For example, PIN_FLD_NAME_INFO in C becomes FldNameInfo in Java.
Field instances are shared to improve performance; therefore, you pass a field to a method by using the following syntax:
obj.method(FldNameInfo.getInst());
where obj is the object that calls the method method.
Follow these steps when using the Java PCM API:
Make sure that the pcm.jar and pcmext.jar files are in your CLASSPATH.
Include the following import statements in the Java files that use PCM classes:
import com.portal.pcm.*;
import com.portal.pcm.fields.*;
When you run a Java program that communicates with BRM, make sure the Infranet.properties files and the custom .CLASS files are in the CLASSPATH.
When you create client applications that use the Java PCM API, you can use either the synchronous mode or the asynchronous mode of handling requests.
In BRM, when you create a client application to process requests in synchronous mode, the application sends a request and waits for a response from the Connection Manager (CM) before it sends the next request. If there is an error on the server side in processing the request, the client application may have to wait indefinitely. To address this, you can set a timeout value for the request your client application sends to the CM. If the CM does not respond within the time specified in the request, the PCP connection layer returns an error message to the client application and closes the connection. See "Specifying a Timeout Value for Requests".
Alternately, when you create a client application to process requests in asynchronous mode, it sends a request to BRM and then, instead of waiting for a response to the request, the client application continues to perform other operations. Throughput is improved in this mode because client applications can make multiple requests. When the response for a request becomes available, the client application retrieves the response and proceeds further with its processing of that request. See "Using the Asynchronous PCP Mode in Java PCM Client Libraries".
A BRM Java client application does the following.
Opens a connection.
Clears the error buffer.
Performs PCM operations.
Checks for errors.
Closes the connection.
For more information, see "Creating a Client Application in C".
When you call an opcode, you need to create an flist and pass it as an input. See the input flist specification in the opcode descriptions for information on the structure of the flist.
For information on how to create an flist, see "Flist Creation Samples".
You open a connection to BRM by using the Java PCM API, all communication is performed through the PortalContext class. You can use one of the following methods to open a connection:
Call the open() method on the context class with all the login information needed, including the host name and the port number.
Use the connect() method, if you want your program to log in automatically to BRM. You must store all the necessary login information in the Infranet.properties file and make sure that file is in the CLASSPATH.
For information on creating an Infranet.properties file, see "Setting Global Options".
Note:
Use the Infranet.properties file for configuring Java applications instead of the pin.conf file used by C applications.If your custom application supports multiple database schemas, you must use the database number returned by the PCM_CONNECT() or PCM_CONTEXT_OPEN() opcodes for all transactions within the context you open. The open() and connect() methods call these opcodes to open a connection to BRM. For more information, see "Maintaining Transactional Integrity".
To open a transaction on a specific database schema, use the opcode method within the PortalContext class to execute the opcode PCM_OP_TRANS_OPCODE with the schema POID specified in the input flist. For more information, see PCM_OP_TRANS_OPEN.
You use Storable Class Editor to create custom fields and to generate Java source files that you compile into classes. See "Creating, Editing, and Deleting Fields and Storable Classes" and Storable Class Editor Help for more information.
You can use custom fields in flists in your Java code in the same manner as BRM fields. Before class names are created from the fields, the prefix PIN_ is removed from the BRM fields and custom field names are used as they are for class names.
To create and use custom fields in the Java PCM package:
Start Storable Class Editor and create your storable classes and fields.
For information, see the Storable Class Editor Help.
From the File menu, choose Generate Custom Fields Source to create source files for your custom fields. See the Storable Class Editor Help system 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.
For each Java application that will use these fields, copy the contents of the InfranetPropertiesAdditions.properties file and paste it into each application's Infranet.properties file.
In the directory where Storable Class Editor created the Java source files, compile the source files:
javac -d . *.java
Package the class files created in step 4 into a JAR file:
jar cvf filename.jar *.class
In the CLASSPATH, add the location of the JAR file.
You use Storable Class Editor to create custom classes. See "Creating, Editing, and Deleting Fields and Storable Classes" and Storable Class Editor help for instructions. After you commit the classes in Storable Class Editor, create the object in Java:
Poid aPoid = new Poid(database, -1, "/customClass"); inFlist.set(FldPoid.getInst(), aPoid); /*... set other fields*/ FList outFList = ctx.opcode(PortalOp.CREATE_OBJ, inFlist);
To call custom opcodes:
Write and define your custom opcodes on the server:
#define custom_opcode1 10001
Call the appropriate method of the PortalContext class in Java. The method you call depends on the opcode processing mode:
Synchronous mode: Use the opcode method. See "Using Synchronous Mode for Opcode Processing".
Asynchronous mode: Use the opcodeSend method. See "How Asynchronous Mode for Opcode Processing Works".
For more information on creating custom opcodes, see "Defining New Opcodes".
For maintainability, you can create a class with all your opcodes, as shown in the following example:
Example 25-1 Creating a Class for Custom Opcodes
class CustomOpcode{
public static final int OPCODE1 = 10001;
public static final int OPCODE2 = 10002;
/*more custom opcodes here*/
}
To create client applications that use the synchronous mode of opcode processing, call the opcode method of the PortalContext class. For example, the following syntax would be used to call OPCODE1, the custom opcode shown in Example 25-1:
ctx.opcode(CustomOpcode.OPCODE1, inFlist);
Internally, the opcode method sends the information on the custom opcode (OPCODE1) to the BRM server and waits for a response. Your client application is blocked during this time interval and can resume further action only after the output is received from the execution of OPCODE1.
When debugging a client application, it is often useful to read a text representation of an flist. The flist API provides the following methods:
toString() method for general purposes
dump() method to display on standard output
Any call that causes a PCM-related error throws an EbufException exception. If partial information was available in an flist from an opcode call, you can retrieve it from the EbufException exception in the Java package.
Tip:
For efficiency, catch exceptions at the highest possible level.For help on the available options and usage, type ? at the prompt.
Note:
All the information available in the C error buffer is available in the Java EbufException exception when that exception is caught. For more information see, "Error Buffer".The ErrorLog class contains the API for logging status, errors, and other messages to a file or buffer. You can access the default log through the PortalContext class. Always use the log to ensure that you get the expected output.
Even when the error log function is used from an applet in a Web browser, where the Security Manager denies access to the file system, a log is generated in a buffer. You must access and display the log from the applet.
Infranet.properties has several options for controlling debugging, including automatic logging of all EbufException exceptions. For more information on the options, see "Setting Global Options".
The Java log function does not have an indefinite list of arguments. You must use string concatenation to form a simple string message. For example:
errorlog.log(ErrorLog.Error, "Here's the error and flist:\n" + error.toString() + "\n" + flist.toString());
You can specify a timeout value for each request to the CM in your client application. For more information on implementing timeout values, see "Implementing Timeout for Requests in Your Application".
To specify a timeout value in milliseconds for a connection, pass the PIN_FLD_TIMEOUT_IN_MS field in the input flist to the PortalContext class constructor or the open() or connect() methods of the PortalContext class. The PIN_FLD_TIMEOUT_IN_MS value is applicable after the client connects to the server. Before the connection happens this setting is not effective. It does not report a time out if the client cannot connect to the server at all.
For more information on the PortalContext class, see BRM PCM Java API Reference.
The timeout value you specify applies to all the opcodes called during that open session and overrides the value in the client properties file. You must ensure that your client application handles the timeout, closes its connection to the CM by calling PCM_CONTEXT_CLOSE, and cleans up the transaction context.
Note:
When the timeout happens, the CM does not provide any feedback about the success or failure of the request it received. When the CM detects the closed connection, it rolls back the ongoing transaction and shuts down.When a Java client application uses the Java PCM library and calls a BRM opcode, the PCP connectors forward the request and wait for the responses from BRM. Asynchronous mode of processing enables client applications to handle multiple requests and improve the throughput of opcode calls.
When you create a client application that uses asynchronous mode processing, you can call the opcodeSend method for as many opcode processing requests as required. As the responses from the execution of these opcode operations become available, your client application can call the opcodeReceive method to receive the responses and act upon them.
Asynchronous mode processing can be used for base opcodes as well as custom opcodes.
The following classes in the Java PCM client libraries enable you to create client applications that make use of the asynchronous mode:
PCPSelector, the PCP connection's socket channel selector. See "About PCPSelector".
PortalContextListener, the abstract listener. See "About PortalContextListener".
PCPSelector is the PCP connection's socket channel selector that uses Java NIO mechanism during the asynchronous mode. (NIO stands for New I/O, a set of non-blocking APIs for Java programming language that offer features for intensive Input/Output operations.)
This Java class provides a Java method named process and also internally calls other interfaces responsible for:
Registering the socket channels with the selector.
Changing the socket channel's interest to READ (data available) operation after the opcode is sent.
Sending the notification to PortalContextListener once the data has arrived.
The client application that you create must extend the PCPSelector class and implement its Runnable interface. To take full advantage of the multithreaded selector capabilities of the PCPSelector class, you must call the process method in your implementation's run method, as shown in the following example:
Example 25-2 Extending PCPSelector
public class SDPPCPSelector extends PCPSelector implements Runnable {
private static SDPPCPSelector instance = null;
private SDPPCPSelector() throws IOException {
super();
}
public static synchronized SDPPCPSelector getInstance() throws IOException
{
if (instance == null) {
instance = new SDPPCPSelector();
}
return instance;
}
public void run(){
System.out.println("inside Run of SDP PCPSelector");
process();
}
}
Below, an instance of the SDPPCPSelector class is created. It can be used to spawn multiple threads.
PCPSelector pcpSelector = SDPPCPSelector.getInstance(); Thread t = new Thread((Runnable) pcpSelector); t.start();
For more information on PCPSelector, see BRM PCM Java API Reference.
PortalContextListener is an abstract listener. It forces the client application to implement the notification-handling interface that is used when opcode operations are performed in an asynchronous mode. The handlePortalContextEvent method of PortalContextListener supplies the PortalContext object with the related event that has occurred recently.
The PCM library supports notifications for the following:
EVENT_READ_DATA_AVAILABLE
EVENT_CHANNEL_CLOSED
Client applications can extend PortalContextListener and use the child class to register their interest in these two events by calling the addListener method of PCPSelector.
For example:
Example 25-3 Extending PortalContextListener
public class ClientListener extends PortalContextListener {
ClientListener () {
pcpSelector = SDPPCPSelector.getInstance();
pcpSelector.addListener(this,EventType.EVENT_READ_DATA_AVAILABLE);
pcpSelector.addListener(this,EventType.EVENT_CHANNEL_CLOSED);
}
public void handlePortalContextEvent(PortalContext portalContext,
EventType eventType) {
// use another thread mechanism to call actual opcodeReceive()
...
}
}
For more information on PortalContextListener, see BRM PCM Java API Reference.
The asynchronous mode for opcode processing works in the following manner:
Your client application calls the opcodeSend method of the PortalContext class. For example code:
ctx.opcodeSend(CustomOpcode.OPCODE1, inFlist);
Internally, the opcodeSend method of the PortalContext class sends the information on the opcode (OPCODE1) to the BRM server, but it does not wait for the response from the opcode operation. Immediately after calling opcodeSend, the client application can perform other tasks.
The BRM framework takes care of monitoring the sockets to check if the PortalContext data (that is, the response from the opcode operation) is available. When this data is available, the handlePortalContextEvent method of the PortalContextListener object in your client application is called automatically.
When your client application receives the notification through the handlePortalContextEvent method, it invokes the opcodeReceive method to receive the response of the opcode operation from BRM. See Example 25-3.
Note:
For better performance, Oracle recommends that you use a separate thread to call the opcodeReceive method rather than calling the opcodeReceive method directly from the handlePortalContextEvent method.For information on PortalContext, see BRM PCM Java API Reference.
For the client application to use the asynchronous opcode processing feature in BRM:
Set up your client applications so that they have multiple threads of the PCPSelector object. To ensure asynchronous opcode processing, pass the PCPSelector object when you create the PortalContext object. For example:
PortalContext portalContext = new PortalContext(pcpSelector);
Register the client application's interest for specific events by calling the addListener method of the PCPSelector object.
Set up the client application to have multiple PortalContextListener objects, if necessary. Each PortalContextListener object provides a notification mechanism through its handlePortalContextEvent method.
If the client application uses multiple PortalContextListener objects, make the readable PortalContext object available to any one or all of the PortalContextListener objects.
To make the readable PortalContext object available to a specific PortalContextListener, use the registerContextToListener method, as shown in Example 25-4:
Example 25-4 Making PortalContext Data Available to Specific PortalContextListener Object
PortalContextListener pListener = new CustomPortalContextListener(); PortalContextListener qListener = new CustomPortalContextListener(); PortalContext portalContext = new PortalContext(pcpSelector); pListener.registerContextToListener(portalContext);
When this sample code executes, one specific PortalContextListener object (pListener) is registered with the PortalContext object. When data becomes available on the PortalContext object and that object is ready to call the opcodeReceive method, a notification is sent to that specific PortalContextListener object (pListener).
To make the readable PortalContext object available to all PortalContextListener objects, omit the registerContextToListener method, as in Example 25-5:
Example 25-5 Making PortalContext Data Available to All PortalContextListener Objects
PortalContextListener pListener = new CustomPortalContextListener(); PortalContextListener qListener = new CustomPortalContextListener(); PortalContext portalContext = new PortalContext(pcpSelector);
None of the PortContextListener objects is registered with the PortalContext object (because the registerContextToListener method was not called for any PortContextListener object). As a result, when data becomes available on the PortalContext object and that object is ready to call the opcodeReceive method, the notification is sent to all the PortalContextListener objects.
You can set up your client application for multiple opcode processing. For example, Example 25-6 issues a second opcodeSend request without waiting for the actual response from the first opcode operation:
Example 25-6 Multiple Opcode Processing
PortalContext portalContext1 = new PortalContext(pcpSelector); portalContext1.open(login_params_flist); portalContext1.opcodeSend(opcode_name, input_flist); PortalContext portalContext2 = new PortalContext(pcpSelector); portalContext2.open(login_params_flist); portalContext2.opcodeSend(opcode_name, input_flist);
PortalContext provides different APIs that your client application can use to check the status of the socket channel.
For more information on the PortalContext class, see BRM PCM Java API Reference.
Infranet.properties is an optional configuration file that contains entries to control all connections from Java applications to BRM. Java PCM looks in the Infranet.properties file for information not provided in the login flist. You must include the Infranet.properties file in the CLASSPATH.
The content of the Infranet.properties file conforms to the Java properties file conventions. Options are key-value pairs separated by the equal sign (=). For example, host=ip://test2:11960 and log.file=mylog.log.
Important:
You must include an entry of the form type = 1 in the Infranet.properties file if that entry is not in the login flist.Table 25-1 lists the predefined entries and their types:
Table 25-1 Entries in Infranet.Properties
| Entry | Value | Notes |
|---|---|---|
|
Infranet.login.type |
0 or 1 |
Specifies the type of login. A type 1 login requires the application to provide a user name and password. A type 0 login is a trusted login that comes through a CM Proxy, for example, and does not require a user name and password in the properties file. |
|
Infranet.connection |
For a type 1 login: pcp://username:password@hostname:port/ service:1 For a type 0 login: pcp:/hostname:port/database_no/service:1 Where:
|
Specifies the full URL to the BRM service. For a type 1 login, the URL must include a user name and password. You must specify the service name and service POID ("1"), but the CM determines the database number. A type 0 login requires a full POID, including the database number. |
|
Infranet.failover.nn |
pcp://hostname:port |
Specifies the alternative CM hosts that the application can use to connect to BRM if the main host (specified in the connection entry) is unavailable. The user name, password, and service for these alternative hosts is the same as for the main host and is not specified in the failover entries. Failover entries are numbered sequentially, starting with 1. |
The Infranet.properties file can contain other entries. Some of these are based on keys in the Java PCM API, and others are written specifically for an application or tool.
Table 25-2 shows entries from the Java PCM API:
Table 25-2 Optional Entries in Infrant.properties
| Entry | Description |
|---|---|
|
Infranet.log.file |
The file path. The default is javapcm.log. |
|
Infranet.log.logallebuf |
Boolean. If true, forces all EbufException exceptions to be logged automatically. |
|
Infranet.log.level |
Specifies how much information the application should log:
|
|
Infranet.pcp.debug.enabled |
true or false |
|
Infranet.pcp.debug.flags |
0: to log nothing 1: to log errors 0x1fff: to log all messages |
|
Infranet.log.opcodes.enabled |
Boolean. If true, enables a log that records the input and output flist for every opcode called by all client applications that support this feature. For more information, including the list of applications, see "Controlling Opcode Logging from a Client Application". |
|
Infranet.log.opcodes.file |
The file path. |
Table 25-3 shows entries used for NamedLogs. The log_name variable specifies the NamedLog name, such as the application doing the logging.
| Entry | Description |
|---|---|
|
Infranet.log.log_name.file |
Full path to the log file for the application. The log file shows errors, warnings, and debugging messages associated with the application, as specified by the Infranet.log.log_name.level entry. |
|
Infranet.log.log_name.style |
Specifies the logging control style. The value for this entry can be:
|
|
Infranet.log.log_name.level |
Specifies how much information the application should log. Possible values depend on the log control style specified by the Infranet.log.log_name.style entry: For priority style, set the level as a decimal value. All messages with a priority level lower than this level are logged. (Low number = high priority) For flag style, set the level to one of these values:
|
|
Infranet.log.log_name.logallebuf |
Boolean. If true, forces all EbufException exceptions to be logged automatically. |
|
Infranet.log.log_name.name |
Specifies the name of the log where all messages of a specific type are written to. |
|
Infranet.log.log_name.enabled |
Enables or disables NamedLog logging. To disable logging, set to f, n, or 0. |
Table 25-4 shows an entry that you can use to display a list of hosts:
Table 25-4 Entries used to List Hosts
| Entry | Description |
|---|---|
|
Infranet.application_name.host.nn |
A list of hosts, (for example, host.1, host.2), and so on, displayed when a user opens the application. The user can select to connect to any host in the list. Host entries, each consisting of a pair of values for hostname and port, are numbered sequentially, starting with 1. Other connection information, such as service, comes from the standard Infranet.connection entry. |
infranet.connection=pcp://sommachine:11960/service/admin_client 1 infranet.login.type=1 infranet.log.file=fullOutput.log infranet.log.logallebuf=true infranet.log.level=3 infranet.pcp.debug.flags=0x3FFFFFFF infranet.pcp.debug.enabled=true
An opcode log contains the input and output flist for every opcode called by the following applications:
Payment Center
Permissioning Center
Pricing Center
Resource Editor
Revenue Assurance Center
Suspense Management Center
Zone Mapper
You can dynamically turn opcode logging on and off for an individual application from the application itself, independent of the global opcode logging settings in the Infranet.properties file and without having to restart the application.
Note:
If you do not define an Infranet.log.opcodes.file entry in the Infranet.properties file and turn logging on using this procedure, the default is opcodes.log.To turn opcode logging on or off:
In the application, click Help then About, and then click System Information.
In the System Information dialog box, press CTRL+SHIFT and click three times on the label above the table to open the Opcode Logging dialog box.
Select or clear the Log Opcodes check box for an application to turn logging on or off.
The Java package includes the jnap test utility. You use jnap to test the database connection, load flists from files, use the flists as input when calling opcodes on the server, and display output flists.
The jnap utility is similar to and provides a subset of the functionality of testnap, the utility used for testing applications written using the BRM C API. You can use many of the same commands in jnap that you use in testnap. Unlike testnap, however, jnap uses Java PCM to communicate with BRM.
When you start jnap, you must include the Infranet.properties, pcm.jar, and pcmext.jar files in the CLASSPATH. In Windows, for example, if the Infranet.properties file is in the current directory and the pcm.jar and pcmext.jar files are in C:\Portal\jars, you would enter:
java -classpath .;c:\Portal\jars\pcm.jar;c:\Portal\jars\pcmext.jar com.portal.pcm.jnap
If you plan to use jnap frequently, you can also set CLASSPATH as an environment variable.
You can get command-line help for jnap by entering help at the prompt. You see a list of valid commands and variables:
jnap> help
jnap command set::
r <file> <bufnum> - read flist from file into buffer
i <bufnum> - insert flist from STDIN into buf
d <flist> - displays flist
w <buf> <file> - save buf to file
l - list buf nums used
login - login using values in Infranet.properties
login <flist> - login using specified flist
logout - logout and close context
xop <op> <flags> <flist> - execute op and set 'incoming' buf
q - quit
loop <flist> - stream out/in flist
pcpdebug <dbgflags> - set pcp debug flags
h or ? or help - displays this help
where
<flist> :: <file> | <buf>
<op> :: <num> | <opname>
<opname>:: READ_OBJ | commit_customer | TRANS_OPEN ...
<buf> :: <bufnum> | incoming
<flags> :: <number> | <flags>'+'<flag>
<flag> :: calc|meta|rev|count|add|poid|rdres|nores|ro|rw|lock
<dbgflags> :: <number> | <dbgflags>'+'<dbgflag>
<dbgflag> :: none|errors|flist_req|flist_resp|read|write|
read_wh|write_wh|read_dump|
write_dump|open|connect|trans|op|all
This section includes an example of using jnap. In this example, you create an flist and then use it as input to the PCM_OP_ACT_TEST_LOOPBACK opcode. This opcode tests the database connection and returns the same flist as output.
Use a text editor to create a simple flist and save it as flist1.
0 PIN_FLD_PROGRAM_NAME STR [0] "Example" 0 PIN_FLD_POID POID [0] 0.0.0.1 -1 0 0 PIN_FLD_NAME STR [0] "Test"
Read flist1 into buffer 1.
jnap> r flist1 1
To ensure that the flist was saved, display the contents of buffer 1.
jnap> d 1
Log in to the database.
jnap> login
Run the PCM_OP_ACT_TEST_LOOPBACK opcode with the xop command. Include the opcode without the PCM_OP_ACT prefix, 0 for the opcode flag, and 1 for the buffer you will use for the input flist.
xop TEST_LOOPBACK 0 1
The output of the opcode is displayed. In this case, the output is the same as the input.
Log out.
jnap> logout
Quit jnap.
jnap> q
For a sample program for creating a client application, see CreateContext.java.
This program creates a customer account by performing these steps:
Opening a database channel
Retrieving a price plan
Adding customer information to the account
Creating the customer account
Closing the database channel
To run CreateContext.java, first edit the Infranet.properties file to change the entry your server to the host name of the computer where BRM is installed. Then include the file in your CLASSPATH. For an example of the Infranet.properties file, see "Example Infranet.properties File".