Invoking BEA Tuxedo Services


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WebLogic Enterprise Doc Home \| Java Enterprise Tuxedo Topics \| Previous Topic \| Next Topic \| Contents \| Index

This topic includes the following sections:

The JET Class Library provides developers with a set of object-oriented Java language classes for accessing BEA Tuxedo services. The bea.jolt package contains the JET Class Library. For more information about the classes that make up the JET Class Library, see the bea.jolt package in the WebLogic Enterprise API Javadoc in the WebLogic Enterprise online documentation.

Configuring JET for Java Server Access

This topic includes the following sections:

Before a Java server application can use the JET Class Library to invoke BEA Tuxedo services, you must first define one or more Jolt Repository Servers (JREPSVRs) to manage service definitions stored in the Jolt Repository. The configuration must include a pointer to the location of the Jolt Repository file. You must configure these JREPSVRS on the same host on which the BEA Tuxedo services are running. For more information about the JREPSVR, see Jolt Repository Server.

To define JREPSVRs, you change settings in the GROUPS and SERVERS section of the UBBCONFIG file for the application. The UBBCONFIG file is an ASCII version of the BEA Tuxedo configuration file. For each UBBCONFIG file, you can configure a single Jolt Repository. Thereafter, you must create the tuxconfig file using tmloadcf, set environment variables (including TUXDIR and CLASSPATH), and then boot the Tuxedo application using tmboot, as described in "Starting and Shutting Down Applications" in the Administration Guide.

Default Repository File

JET includes a sample Jolt Repository file, jrepository (in the udataobj\jolt directory), which includes service definitions for the BEA Tuxedo TOUPPER service, along with other sample service definitions. Start with the jrepository file provided with the installation, even if you are not going to use the service definitions it contains. You can simply delete the packages or services that you do not need.

In addition, the CORBA/Java-to-Simpapp and EJB-to-Tuxedo Simpapp sample applications include local repository files that contain the service definitions needed to run the samples. For more information about these sample applications, see CORBA, J2EE, and Tuxedo Interoperability and Coexistence.

Warning: Do not modify the Repository files manually or you will not be able to use the Jolt Repository Editor. Although the jrepository file can be modified and read with any text editor, JET does not have integrity checks to ensure that the file is in the proper format. Any manual changes to the jrepository file might not be detected until run time. For more information, see Using the BEA Jolt Repository Editor.

Parameters to Specify in the UBBCONFIG File

Table 2-1 describes the parameters in the UBBCONFIG file to specify.

Table 2-1 Parameters To Specify in UBBCONFIG File

Option
Parameters

GROUPS

LMID, GRPNO

SERVERS

SRVGRP, SRVID

Option	Parameters
GROUPS	LMID, GRPNO
SERVERS	SRVGRP, SRVID

For more information about the UBBCONFIG file, see "Creating a Configuration File" in the Administration Guide and the BEA Tuxedo Command Reference.

GROUPS Section

A GROUPS entry is required for the group that includes the Jolt Repository. The group name parameter is a name selected by the application. In the GROUPS section, complete the following steps:

Specify the same identifiers given as the value of the LMID parameter in the MACHINES section.
Specify the value of the GRPNO, between 1 and 30000.

SERVERS Section

The JREPSVR contains services for accessing and editing the Repository. Multiple JREPSVR instances share Jolt Repository information through a shared file.

Note: To achieve the fastest performance, configure the Jolt Repository on a local drive of the machine on which the Java server runs. At a minimum, the Jolt Repository must reside on a volume that is network accessible to the JREPSVR.

To configure JREPSVR, modify the SERVERS section of the UBBCONFIG file by completing the following steps:

Indicate a new server identification (for example, 98) with the SRVID parameter.
Specify the -W flag for one (and only one) JREPSVR to ensure that you can edit service definitions using the Bulk Loader program or the Jolt Repository Editor.
Without explicitly setting this flag, the Repository is read-only.

Note: You must install only one writable JREPSVR (that is, only one JREPSVR with the -W flag). Multiple read-only JREPSVRs can be installed on the same host.
Type the -P flag to specify the path of the Jolt Repository file.
Note: An error message is displayed in the BEA Tuxedo ULOG file if the argument for the -P flag is not entered.
Add the file pathname of the Repository file (for example, /app/jrepository).
Boot the BEA Tuxedo system by using the tmloadcf (for example, tmloadcf -y ubbconfig) and tmboot commands.
For information about tmloadcf and tmboot, see Administering a BEA Tuxedo Application at Run Time.

Sample UBBCONFIG File

Listing 2-1 shows relevant portions of a sample UBBCONFIG file.

Listing 2-1 Sample UBBCONFIG File

*GROUPS
   JREPGRP        GRPNO=94 LMID=SITE1
*SERVERS
   JREPSVR SRVGRP=JREPGRP SRVID=98 
   RESTART=Y GRACE=0 CLOPT="-A -- -W -P /app/jrepository"
   JREPSVR SRVGRP=JREPGRP SRVID=97 
    RESTART=Y RQADDR=JREPQ GRACE=0 CLOPT="-A -- -P /app/jrepository"
   JREPSVR SRVGRP=JREPGRP SRVID=96 
   RESTART=Y RQADDR=JREPQ REPLYQ=Y GRACE=0 CLOPT="-A -- -P /app/jrepository"

Notes: For the CLOPT parameter, the pathname of the file must match the argument of the -P option.

For UNIX systems, use the slash (/) when setting the path to the jrepository file (for example, app/repository). For Windows NT systems, use the backslash (\) and specify the drive name (for example, c:\app\repository).

Invoking BEA Tuxedo Services with the JET Class Library

This topic includes the following sections:

This topic shows how to invoke a BEA Tuxedo service using the JET Class Library. It uses sample Java code from the EJB-to-Tuxedo Simpapp sample application, as well as some code fragments from unshipped applications to illustrate other programming techniques. The EJB-to-Tuxedo Simpapp sample application invokes a BEA Tuxedo service, TOUPPER, that converts a text string to all uppercase letters. The EJB-to-Tuxedo Simpapp sample application is located in samples\interop\ejb_tux.

This topic walks through the portions of the SimpBean code that use the JET Class Library. For a complete description of this sample application, see "EJB-to-Tuxedo Simpapp Sample Application" in CORBA, J2EE, and Tuxedo Interoperability and Coexistence.

Note: At run time, the BEA Tuxedo service(s) that you want to invoke must be running on the BEA Tuxedo server. The configuration settings specified in Configuring JET for Java Server Access must be activated for the Tuxedo application.

Importing Packages

To use JET, an application must import the bea.jolt.* package, which contains the JET Class Library. Listing 2-2, from the EJB-to-Tuxedo Simpapp sample application, shows how the SimpBean imports the required packages, including the bea.jolt package.

Listing 2-2 Importing the bea.jolt Package

package ejb;

import java.rmi.*;
import javax.ejb.*;

import bea.jolt.*;

Instantiating a JoltService Object

The joltNativeCall method is where the SimpBean invokes the TOUPPER BEA Tuxedo service using the JET Class Library. The key component of the Jolt Class Library is the JoltService class.

To access a BEA Tuxedo service using JET, an application begins by creating an instance of the JoltService class. The JoltService object represents the BEA Tuxedo service that you want to invoke. The constructor requires the name of the BEA Tuxedo service. JET uses this service name to locate the associated service definition in the Jolt Repository.

Listing 2-3, from the EJB-to-Tuxedo Simpapp sample application, shows the declaration of the joltNativeCall method and the instantiation of a JoltService to represent the BEA Tuxedo TOUPPER service.

Listing 2-3 Creating an Instance of the JoltService Class

  String joltNativeCall (String svcName, String data)

  {
    JoltService svc;

    try {
      svc = new JoltService (svcName);

Specifying Parameters for the BEA Tuxedo Service

After instantiating a JoltService, an application specifies parameters for the BEA Tuxedo service. The JoltService class provides addXXXX methods that are used to specify the parameters. For each parameter, the application specifies the buffer type (such as STRING, CARRAY, VIEW, and FML) and the buffer value. For more information, see Using BEA Tuxedo Buffer Types with JET.

Note: The parameters must be valid for the BEA Tuxedo service. If invalid parameters are specified, the BEA Tuxedo service will return an error.

Specifying String Parameters

Listing 2-4, from the EJB-to-Tuxedo Simpapp sample application, shows the call to the addString method, passing the buffer type (STRING) and the text string (data) supplied by the user.

Listing 2-4 Specifying the Parameters for the TOUPPER Service

      svc.addString("STRING", data);

Specifying Array Parameters

Listing 2-5 is a code fragment that shows how to specify array elements for two array parameters: a String array named svarray and a short array named harray.

Listing 2-5 Specifying Array Parameters

j_service.addString("svarray", "String[0]");
j_service.addString("svarray", "String[1]");
j_service.addShort("harray", (short) (600));
j_service.addShort("harray", (short) (700));

Specifying Parameters of Various Data Types

Listing 2-6 is a code fragment that shows how to specify parameters of various data types.

Listing 2-6 Specifying Parameters of Various Data Types

j_service.addInt("ctime", 100);
j_service.addString("hname", "***NoName***");
j_service.addFloat("fval", (float) 200.00);
j_service.addByte("cval", (byte) 'S');
j_service.addInt("lval", 300);
j_service.addString("sval","10  bytes(unexpected string)");
j_service.addShort("hval", (short) 400);
j_service.addDouble("dval", 500.00);

Calling the BEA Tuxedo Service

After the parameters are specified, an application calls the call method, which submits a service request to BEA Tuxedo. The call method provides two syntax options:

An application uses call() to have the BEA Tuxedo service call participate in the current transaction, if applicable. JET uses the implicit transaction mechanisms provided by WebLogic Enterprise and BEA Tuxedo. If the BEA Tuxedo service call is part of a transaction and the transaction is rolled back, any changes made by the BEA Tuxedo service call are rolled back automatically.
An application uses call(null) to exclude the BEA Tuxedo service call from participating in the current transaction. Pass null only if you are certain that any operations performed by the BEA Tuxedo service will never need to be rolled back.

Listing 2-7, from the EJB-to-Tuxedo Simpapp sample application, shows the call to the call method, passing null because the operation performed by the TOUPPER service is not transactional.

Listing 2-7 Invoking the BEA Tuxedo TOUPPER Service

      svc.call (null);

At this point, JET obtains the TOUPPER service definition from the Jolt Repository, converts the buffer data to BEA Tuxedo buffers, submits the request to BEA Tuxedo, and awaits a reply.

Handling Results

This section describes how to handle the results (exceptions and parameters) returned from a Tuxedo service call.

Handling Exceptions

The JET Class Library returns JET and BEA Tuxedo errors as exceptions. For a complete list of JET exceptions, see the WebLogic Enterprise Javadoc in the WebLogic Enterprise online documentation.

Listing 2-8, from the EJB-to-Tuxedo Simpapp sample application, shows the code to catch a ServiceException.

Listing 2-8 Handling the Results of the BEA Tuxedo Service Call

    } catch (ServiceException e) {
      System.out.println("JoltService got "+e);
      return new String("");

Handling Returned Parameters

This section describes how to handle parameters that were returned from the BEA Tuxedo service call. The JoltService class provides getXXXX methods that are used to retrieve individual parameters. The application passes the name of the parameter to retrieve, as well as a default value in case no value is returned.

Retrieving String Parameters

Listing 2-9, from the EJB-to-Tuxedo Simpapp sample application, shows how to retrieve the String parameter, specified in Listing 2-4, that was returned by the TOUPPER service. In the call to the getStringDef method, the application passes the parameter name (STRING) and the default value ("no_response") if no value was returned.

Listing 2-9 Retrieving a String Parameter

return svc.getStringDef("STRING", "no_response");

Retrieving Arrays

Listing 2-10 is a code fragment that shows how to handle the returned array elements for the two arrays, svarray and harray, that were specified in Listing 2-5.

Listing 2-10 Retrieving Returned Arrays

// retrieve svarray elements
for (int i = 0; i < 2; i++)
{
    String s;
    if ((s = j_service.getStringItemDef(
       "svarray", i, null)) == null)
     break;
System.out.println( hdr+"]: svarray["+i+"]="+s);
}
// retrieve harray elements
for (int i = 0; i < 2; i++)
   {
    short h;
    if ((h = j_service.getShortItemDef(
       "harray", i, (short) 0)) == 0)
     break;
    System.out.println( hdr+"]: harray["+i+"]="+h);
}

Retrieving Parameters of Various Data Types

Listing 2-11 is a code fragment that shows how to handle the returned parameters, of various data types, that were specified in Listing 2-6.

Listing 2-11 Retrieving Parameters of Various Data Types

System.out.println(hdr+"]: ctime="+
j_service.getIntDef("ctime", 0)+
nhdr+"]: hname="+
j_service.getStringDef("hname", null)+
nhdr+"]: sval="+
j_service.getStringDef("sval", null)+
nhdr+"]: fval="+
j_service.getFloatDef("fval",(float) 0.0)+
nhdr+"]: cval="+
j_service.getByteDef("cval", (byte) '.')+
nhdr+"]: lval="+
j_service.getIntDef("lval", 0)+
nhdr+"]: hval="+
j_service.getShortDef("hval", (short) 0)+
nhdr+"]: dval="+
j_service.getDoubleDef("dval",(double)0.0));

Table 2-1 Parameters To Specify in UBBCONFIG File