Introducing Java Enterprise Tuxedo

 

This topic includes the following sections:

• Key Features

• JET Workflow

• Key Components

• Comparison Between Jolt and JET

Java Enterprise Tuxedo^TM (JET) is a Java-based application programming interface (API) to the BEA Tuxedo system for Java servers (CORBA/Java, EJB, and RMI servers) running in the WebLogic Enterprise (WLE) environment. JET is a Java class library and API that enables Java servers to invoke BEA Tuxedo services and process the results.

 

---

Key Features

With JET, you can leverage existing BEA Tuxedo services from a WebLogic Enterprise Java server application (CORBA/Java, EJB, or RMI servers). The key feature of the JET architecture is its simplicity. You can build, deploy, and maintain robust, modular, and scalable electronic commerce systems that operate over the Internet.

JET provides the following features:

• Java-based API for simplified development-with its Java-based API, JET simplifies application development by providing well-designed object interfaces into BEA Tuxedo services.

• Implicit transaction support-JET enables Java programmers to build Java servers that use the BEA Tuxedo application and transaction services without needing to understand detailed transactional semantics or rewrite existing BEA Tuxedo applications. Transactions are handled implictly by WebLogic Enterprise and BEA Tuxedo. Java programmers can decide whether a Java server application participates in, or is excluded from, a transaction.

• BEA Tuxedo-enabled Java server development-using JET, you can build Java servers that leverage your BEA Tuxedo services. Tuxedo processes can span multiple domains. JET calls can occur across a bridge or a domain gateway. JET provides the automatic conversion between Java and native BEA Tuxedo data types and buffers.

• Easy access to BEA Tuxedo services through the Jolt Repository-the Jolt Repository contains service definitions that represent Tuxedo services. JET provides graphical and command-line tools for dynamically populating and editing service definitions in the Jolt Repository.

 

---

JET Workflow

Figure 1-1 provides an overview of how JET works.

Figure 1-1 Java Servers Using JET to Invoke BEA Tuxedo Services

A BEA Tuxedo service invocation using JET involves the following steps:

1. A Java server (CORBA/Java, EJB, or RMI server) uses the API in the JET Class Library to prepare and submit a BEA Tuxedo service request.

2. JET retrieves the service definition for the requested BEA Tuxedo service and routes the request to the BEA Tuxedo server, which forwards the request to the Tuxedo service.

3. The BEA Tuxedo service receives the request and generates the results.

4. The BEA Tuxedo service returns the results to the Java server.

5. The Java server uses the JET Class Library to translate the results into a Java format and process the results.

This entire procedure occurs within the WebLogic Enterprise environment. For a more detailed description of this process, see Invoking BEA Tuxedo Services.

 

---

Key Components

JET consists of the following key components:

• JET Class Library

• Jolt Repository Server

• Tools for Managing Service Definitions

  Note: JET leverages technology from BEA Jolt®, a BEA product that links Web clients to BEA Tuxedo services. Certain JET components therefore include Jolt in the name. However, these components are used by JET, not Jolt. To use Jolt, you must purchase a Jolt license and install the Jolt software separately. For more information about Jolt, see Comparison Between Jolt and JET.

JET Class Library

The JET Class Library is a Java package that contains the class files that implement the JET API. These classes enable Java servers to invoke BEA Tuxedo services. The JET Class Library includes the functionality needed to prepare, submit, and process a BEA Tuxedo service request.

The following types of Java servers can use the JET Class Library:

• CORBA/Java servers

• EJB servers

• RMI servers

When developing a JET client application, you need to know only about the classes that JET provides and the BEA Tuxedo services that are defined in the Jolt Repository. JET hides the underlying application details. To use the JET Class Library, you do not need to understand the underlying transactional semantics, the language in which the services were coded, buffer manipulation, the location of services, or the names of databases used. JET handles these operations for you and leverages the implicit transaction processing mechanisms that WebLogic Enterprise and BEA Tuxedo provide.

Table 1-1 describes the flow of activity involved in using the JET Class Library to access BEA Tuxedo services.

Table 1-1 Using the JET Class Library

Step	Process	Action
1	Import Library	Java server (CORBA/Java, EJB, or RMI server) imports the package containing the JET Class Library.
2	Prepare Request	Java server instantiates a JoltService object and prepares a BEA Tuxedo service request object using the JET API.
3	Submit Request	Java server invokes the call method to submit the service request.
4	Process Request	BEA Tuxedo application server receives and processes the service request.
5	Reply	BEA Tuxedo returns the results of the service invocation to the Java server.
6	Process Results	The Java server processes the results, including any exception handling.

For more information about calling Tuxedo services from within Java servers, see Invoking BEA Tuxedo Services.

Jolt Repository Server

A BEA Tuxedo application is a collection of one or more services. The Jolt Repository Server (JREPSVR) is a Tuxedo server that manages service definitions of BEA Tuxedo services for JET. A service definition describes the properties of a BEA Tuxedo service, such as its name, input and output buffer types, and individual parameters.

JET uses these service definitions to perform data conversions. Tuxedo service definitions are stored in a central file, the Jolt Repository, which the JREPSVR manages. JET uses the JREPSVR to retrieve Tuxedo service definitions from the Jolt Repository. In addition, the JREPSVR manages updates to service definitions in the Jolt Repository.

For each BEA Tuxedo service that you want to access using JET, an associated service definition must be stored in the Jolt Repository. In order to invoke a Tuxedo service, its service definition must also be explicitly exported, or made available, to Java servers. All Repository services that are exported to one Java server are exported to all Java servers. BEA Tuxedo handles the cases where subsets of services may be needed for one client and not others. You specify and export service definitions using the graphical and command-line tools described in Tools for Managing Service Definitions.

Before you can use JET, you must configure the JREPSVR in the UBBCONFIG file, as described in Configuring JET for Java Server Access. For each Jolt Repository, you can configure one or more JREPSVRs. Only one instance of the JREPSVR can be configured with read-write access to the Jolt Repository; all others are configured with read-only access.

How BEA Tuxedo Services are Distributed

Figure 1-2 illustrates how the JREPSVR distributes BEA Tuxedo services to multiple Java servers. In this example, the BEA Tuxedo server has four services, but only three are defined in the Jolt Repository. The WITHDRAW service is not defined and therefore is unavailable to Java servers. In addition, the TRANSFER service is defined in the Jolt Repository but is not exported, or made available, to the Java servers. The Java servers are able to invoke only the DEPOSIT and INQUIRY services.

Figure 1-2 Distributing BEA Tuxedo Services via JET

Workflow for Handling BEA Tuxedo Service Requests

Figure 1-3 shows how JREPSVRs handle BEA Tuxedo service requests from Java servers.

Figure 1-3 Workflow for Handling BEA Tuxedo Service Requests

The workflow occurs in the following sequence:

1. The Java server submits a request for a BEA Tuxedo service.

2. JET retrieves the service definition for the requested service from the Jolt Repository using a JREPSVR. Because it is a read-only request, any available JREPSVR can service the request.

3. JET uses the service definition to translate buffer data. It submits the request to the BEA Tuxedo server and returns the results to the calling Java server.

Tools for Managing Service Definitions

This topic describes the following JET components, which are used for managing service definitions:

• Bulk Loader

• Jolt Repository Editor

• Jolt Servers

• Jolt Internet Relay

JET leverages these components from BEA Jolt for the sole purpose of managing service definitions used by the JREPSVR. In addition, the topic Using BEA Tuxedo Buffer Types with JET describes the BEA Tuxedo buffer types that JET supports.

In order to use the Bulk Loader or Jolt Repository Editor to edit service definitions, you must first configure the Jolt servers. If you want to use these tools across a firewall, you must also configure Jolt Internet Relay. For configuration instructions, see Configuring JET for Client Access.

Bulk Loader

The Bulk Loader program populates service definitions for the JREPSVR. It uses service definitions that are specified in a specially-formatted text file. For more information about the Bulk Loader program, see Using the Bulk Loader Program.

Jolt Repository Editor

The Jolt Repository Editor is a GUI-based administration tool that allows developers and administrators to add, edit, delete, export, and test individual service definitions. You can modify parameters for BEA Tuxedo services, logically group BEA Tuxedo services into packages, and remove services from created packages. For more information, see Using the BEA Jolt Repository Editor.

Note: The Jolt Repository Editor controls services for JET client applications only. You cannot use it to make changes to the BEA Tuxedo application.

Jolt Servers

JET includes the following Jolt servers to handle communications with the JREPSVR when the Repository Editor or Bulk Loader programs are used:

• Jolt Server Listener (JSL)-receives requests from clients and assigns them to an available Jolt Server Handler. The JSL is a BEA Tuxedo server.

• Jolt Server Handler (JSH)-manages network connectivity, executes service requests, and handles the translation of buffer data between BEA Tuxedo and Jolt buffers. Each JSH retains a cache copy of the Jolt Repository for performance purposes.

These servers work together to handle incoming requests from the Bulk Loader program or Jolt Repository Editor to update service definitions. The JSH communicates with the JREPSVR.

Note: You must configure these Jolt servers before you can update service definitions. For more information, see Configuring JET for Client Access.

Figure 1-4 shows how the Jolt servers work together to handle requests from the Jolt Repository Editor or the Bulk Loader program.

Figure 1-4 Workflow for Handling Requests from the Jolt Clients

The workflow occurs in the following sequence:

1. The Jolt Repository Editor or Bulk Loader sends an access request to the JSL.

2. The JSL forwards the request to an available JSH.

3. The JSH directs the request to an available JREPSVR. If the request is for write-access to the Jolt Repository, the JSH directs the request to the one JREPSRVR that has write-access to the Jolt Repository.

4. The JREPSVR processes the request in the Jolt Repository and returns the results to the JSH.

5. The JSH saves the results in its cache and returns the results to the client application that made the request.

   The JSL also updates the Jolt Repository cache in other JSHs.

Jolt Internet Relay

You use Jolt Internet Relay only if you want to run the Jolt Repository Editor or Bulk Loader and access Tuxedo service definitions on the other side of a firewall. Jolt Internet Relay handles message routing from the Jolt Repository Editor or Bulk Loader running outside a firewall to a JSL or JSH behind a firewall.

Components of Jolt Internet Relay

Jolt Internet Relay consists of the following components:

• Jolt Relay (JRLY)-a standalone software component that routes Jolt messages to the Jolt Relay Adapter. Requiring only minimal configuration to work with Jolt clients, the Jolt Relay eliminates the need for the BEA Tuxedo system to run on the same machine as the Web server.

• Jolt Relay Adapter (JRAD)-a BEA Tuxedo system server, but does not include any BEA Tuxedo services. It requires command-line arguments to allow it to work with the JSH and the BEA Tuxedo system. JRAD receives client requests from JRLY, and forwards the request to the appropriate JSH. Replies from the JSH are forwarded back to the JRAD, which sends the response back to the JRLY.

A single Jolt Internet Relay (JRLY/JRAD pair) handles multiple clients concurrently.

Note: You must configure Jolt Internet Relay before you can use the Repository Editor or Bulk Loader outside a firewall. For more information, see Configuring JET for Client Access.

Workflow of Client Requests Using Jolt Internet Relay

Figure 1-5 shows how the JRLY and JRAD work together to route requests from the Jolt Repository Editor or the Bulk Loader program to a JSH across a firewall.

Figure 1-5 Workflow for Jolt Internet Relay

The workflow occurs in the following sequence:

1. The Jolt Repository Editor or Bulk Loader sends an access request to the JRLY on the Web server.

2. The JRLY forwards the request across the firewall to the JRAD in the WebLogic Enterprise environment.

3. The JRAD forwards the message to the JSL.

4. The JSL forwards the request to an available JSH.

5. The JSH directs the request to an available JREPSVR (see Figure 1-4 for an example). If the request is for write-access to the Jolt Repository, the JSH directs the request to the one JREPSRVR that has write-access to the Jolt Repository.

6. The results are returned along the same route.

7. For subsequent access requests from the Jolt Repository Editor or Bulk Loader, the JRAD forwards the request to the selected JSH, bypassing the JSL.

Using BEA Tuxedo Buffer Types with JET

This topic describes the BEA Tuxedo buffer types that you use when defining parameters for a Tuxedo service call, as described in Specifying Parameters for the BEA Tuxedo Service. Using a buffer type involves the following steps:

1. Specifying the buffer type in the service definition using the Bulk Loader program or the Jolt Repository Editor.

2. Writing the code that uses the buffer specified in the service definition, as described in Invoking BEA Tuxedo Services.

Supported BEA Tuxedo Buffer Types

JET supports the following built-in BEA Tuxedo buffer types:

• FML, FML32

• VIEW, VIEW32

• X_COMMON

• X_C_TYPE

• CARRAY

• X_OCTET

• STRING

  Note: X_OCTET is used identically to CARRAY.
  X_COMMON and X_C_TYPE are used identically to VIEW.

For detailed information about the BEA Tuxedo typed buffers, data types, and buffer types, see the BEA Tuxedo Programmer's Guide.

Of the BEA Tuxedo built-in buffer types, the JET application programmer should be particularly aware of how JET handles the CARRAY (character array) and STRING built-in buffer types. The CARRAY type is used to handle data opaquely (for example, the characters of a CARRAY data type are not interpreted in any way). No data conversion is performed between a JET client and BEA Tuxedo service.

For example, if a BEA Tuxedo service uses a CARRAY buffer type and the user sets a 32-bit integer (in Java the integer is in big-endian byte order), then the data is sent unmodified to the BEA Tuxedo service. If the BEA Tuxedo service is run on a machine whose processor uses little-endian byte-ordering (for example, Intel processors), the BEA Tuxedo service must convert the data properly before the data can be used.

STRING Buffer Type

The STRING buffer type is a collection of characters. STRING consists of non-null characters and is terminated by a null character. The STRING data type is character and, unlike CARRAY, you can determine its transmission length by counting the number of characters in the buffer until reaching the null character.

Note: During the data conversion from JET to STRING, the null terminator is automatically appended to the end of the STRING buffers because a Java string is not null-terminated.

CARRAY Buffer Type

The CARRAY buffer type is a simple character array buffer type that is built into the BEA Tuxedo system. Because the system does not interpret the data (although the data type is known) when you use the CARRAY buffer type, you must specify a data length in the JET client application. The JET client must specify a data length when passing this buffer type.

To use the CARRAY buffer type, you first define the BEA Tuxedo service that you will be using with the buffer type. Then, write the code that uses the buffer type.

Note: X_OCTET is used identically to CARRAY.

FML Buffer Type

FML (Field Manipulation Language) is a flexible data structure that can be used as a typed buffer. The FML data structure stores tagged values that are typed, variable in length, and may have multiple occurrences. The typed buffer is treated as an abstract data type in FML.

FML gives you the ability to access and update data values without having to know how the data is structured and stored. In your application program, you simply access or update a field in the fielded buffer by referencing its identifier. To perform the operation, the FML run time determines the field location and data type.

FML is especially suited for use with JET clients because the client and server code can be in two languages (for example, Java and C); the client/server platforms can have different data type specifications; or the interface between the client and the server can change frequently.

VIEW Buffer Type

VIEW is a built-in BEA Tuxedo typed buffer. The VIEW buffer provides a way to use C structures and COBOL records with the BEA Tuxedo system. The VIEW typed buffer enables the BEA Tuxedo run-time system to understand the format of C structures and COBOL records based on the view description that is read at run time.

When allocating a VIEW, your application specifies a VIEW buffer type and a subtype that matches the name of the view (the name that appears in the view description file). The parameter name must match the field name in that view. Because the BEA Tuxedo run-time system can determine the space needed based on the structure size, your application need not provide a buffer length. The run-time system can also automatically handle such things as computing how much data to send in a request or response, and handle encoding and decoding when the message transfers between different machine types.

 

---

Comparison Between Jolt and JET

This topic includes the following sections:

• Overview of Jolt and JET

• Architecture Comparison

• Components Comparison

• Functionality Comparison

• Class Library Comparison

Overview of Jolt and JET

WebLogic Enterprise provides two technologies that enable Java applications to invoke BEA Tuxedo services:

• Jolt provides client-side access to BEA Tuxedo services. Jolt enables browser-based clients (applications, such as the Jolt Bulk Loader program, or applets such as the Jolt Repository Editor) to invoke BEA Tuxedo services and process the results. Jolt is an optional WebLogic Enterprise component that is installed separately from WebLogic Enterprise.

• Java Enterprise Tuxedo (JET) provides server-side access to BEA Tuxedo services. JET enables Java servers (CORBA/Java, EJB, or RMI servers) running within the WebLogic Enterprise domain to invoke BEA Tuxedo services and process the results. JET is automatically installed when you install WebLogic Enterprise.

The technology that you use depends on the nature of your application. Use Jolt to provide client applets with access to BEA Tuxedo services, or use JET to provide Java servers, running in the WebLogic Enterprise domain, with access to BEA Tuxedo services.

Architecture Comparison

Figure 1-6 provides an overview of the Jolt and JET architectures.

Figure 1-6 Overview of Jolt and JET Architectures

At run time, requests for BEA Tuxedo services are handled differently:

• For servlets that make service requests using Jolt, requests and replies are routed to the BEA Tuxedo service through the Java Listener (JSL) to a Java Handler (JSH).

• For Java servers that make service requests using JET, requests and replies are routed directly through JET, without using the JSL/JSH. The server-side object lives inside JavaServer(.exe). Because the JavaServer(.exe) is a regular Tuxedo server, it can call Tuxedo services within its domain or across domains.

For more detailed information about Jolt, see the BEA Jolt documentation in the WebLogic Enterprise online documentation.

Components Comparison

Because JET runs in the WebLogic Enterprise environment, it does not require all of the components that Jolt uses. Table 1-2 compares the components used in Jolt and JET.

Table 1-2 Comparison of Jolt and JET Components

Component	Used in Jolt?	Used in JET?
Class Library	Yes	Yes
JoltBeans	Yes	No
Jolt Repository	Yes	Yes
Jolt Repository Editor	Yes	Yes
Bulk Loader	Yes	Yes
Jolt Repository Server (JREPSVR)	Yes	Yes
Jolt Servers: Jolt Listener (JSL) Jolt Handler (JSH)	Yes	Yes
Jolt Internet Relay: Jolt Relay (JRLY) Jolt Relay Adapter (JRAD)	Yes	Yes
Servlet Connectivity for Tuxedo	Yes	No
ASP Connectivity for Tuxedo	Yes	No

At run time, Java servers using JET require only the JET Class Library, the Jolt Repository, and the JREPSVR. All other components are used only when editing BEA Tuxedo service definitions in the Jolt Repository, as described in Tools for Managing Service Definitions.

Functionality Comparison

Table 1-3 compares the major features used in Jolt and JET.

Table 1-3 Comparison of Jolt and JET Functionality

Function	Jolt	JET
Calling code	Applets launched inside web browsers	Java servers: CORBA/Java, EJB, and RMI servers
Sessions	Yes	No
Transactions	Explicit; client must establish transactions explicitly.	Implicit; calls can be excluded from transactions.
Events	Yes	No
Security	56-bit and 128-bit	40-bit only
Class for invoking BEA Tuxedo service	JoltRemoteService class	JoltService class
Jolt version	Jolt 1.2.1	Jolt 1.2

Class Library Comparison

The Jolt and JET class libraries share some common components. This topic describes the packages, interfaces, and classes that Jolt and JET use.

Packages

Table 1-4 describes the bea.jolt.* packages that Jolt and JET use. The only common package is bea.jolt, of which JET uses the subset described in Table 1-5.

Table 1-4 Packages Used in Jolt and JET

Package Name / Component	Used in Jolt?	Used in JET?
package bea.jolt	Yes	Yes
package bea.jolt.beans	Yes	No
package bea.jolt.beans.awt	Yes	No
package bea.jolt.beans.swing	Yes	No
package bea.jolt.beans.swi ng11	Yes	No
package bea.jolt.pool	Yes	No
package bea.jolt.pool.asp	Yes	No
package bea.jolt.pool.servlet	Yes	No
package bea.jolt.pool.servlet.weblogic	Yes	No

Package bea.jolt Components

Table 1-5 describes the components of the bea.jolt package that Jolt and JET use. JET uses a subset of the bea.jolt package.

Table 1-5 Components of the bea.jolt Package

Package Name / Component	Used In Jolt?	Used in JET?
Interfaces
Message	Yes	No
Classes
JoltAdmSession	Yes	No
JoltDefinition	Yes	Yes
JoltMessage	Yes	No
JoltParam	Yes	No
JoltRemoteService	Yes	Yes
JoltReply	Yes	No
JoltRepository	Yes	No
JoltRequest	Yes	No
JoltService	No	Yes
JoltServiceBase	No	Yes
JoltSession	Yes	No
JoltSessionAttributes	Yes	No
JoltTransaction	Yes	No
JoltUserEvent	Yes	No
LockMonitor	Yes	No
SBuffer	Yes	Yes
Session	Yes	No
Exceptions
ApplicationException	Yes	Yes
DefinitionException	Yes	No
EventException	Yes	No
JoltException	Yes	Yes
MessageException	Yes	Yes
ServiceException	Yes	Yes
SessionException	Yes	No
TransactionException	Yes	No

Note: Jolt application developers must use the JoltRemoteService class, while JET application developers should use the JoltService class. Differences exist between the constructors and the call method.

For detailed information about these classes, see the BEA Jolt Javadoc and the bea.jolt package in the WebLogic Enterprise API Javadoc in the WebLogic Enterprise online documentation.