Jolt Class Library Walk-through


	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

Tuxedo Doc Home \| Jolt \| Topic List \| Previous \| Next \| Contents \| Index

Using BEA Jolt

Use Jolt classes to perform the basic functions of transaction processing: log on/log off; synchronous service calling; transaction begin, commit, and rollback. The following sections describe how Jolt classes are used to perform these functions.

You can also use the Jolt class library to develop multithreaded applications, define Tuxedo buffer types, and subscribe to events and unsolicited messages. These functions are discussed in later sections.

Logon and Logoff

The client application must log on to the BEA Tuxedo environment prior to initiating any transaction activity. The Jolt Class Library provides the JoltSessionAttributes class and JoltSession class to establish a connection to a BEA Tuxedo system.

The JoltSessionAttributes class will contain the connection properties of Jolt and BEA Tuxedo systems as well as various other properties of the two systems. To establish a connection, the client application must create an instance of the JoltSession class. This instance is the JoltSession object. After the developer instantiates a Jolt Session and BEA Tuxedo object, the Jolt and BEA Tuxedo logon capability is enabled. Calling the endSession method ends the session and allows the user to log off.

Synchronous Service Calling

Transaction activities such as requests and replies are handled through a JoltRemoteService object (an instance of the JoltRemoteService class). Each JoltRemoteService object refers to an exported BEA Tuxedo request/reply service. You must provide a service name and a JoltSession object to instantiate a JoltRemoteService object before it can be used.

To use a JoltRemoteService object:

Set the input parameters.
Invoke the service.
Examine the output parameters.

For efficiency, Jolt does not make a copy of any input parameter object; only the references to the object (for example, string and byte array) are saved. Because JoltRemoteService object is a stateful object, its input parameters and the request attributes are retained throughout the life of the object. You can use the clear() method to reset the attributes and input parameters before reusing the JoltRemoteService object.

Because Jolt is designed for a multithreaded environment, you can invoke multiple JoltRemoteService objects simultaneously by using the Java multithreading capability. Refer to Multithreaded Applications for additional information.

Transaction Begin, Commit, and Rollback

In Jolt, a transaction is represented as an object of the class JoltTransaction. The transaction begins when the transaction object is instantiated. The transaction object is created with a time out and JoltSession object parameter:

trans = new JoltTransaction(timeout, session)

Jolt uses an explicit transaction model for any services involved in a transaction. The transaction service invocation requires a JoltTransaction object as a parameter. Jolt also requires that the service and the transaction belong to the same session. Jolt does not allow you to use services and transactions that are not bound to the same session.

The sample code in the listing Jolt Transfer of Funds Example (SimXfer.java) describes how to use the Jolt Class Library and includes the use of the JoltSessionAttributes, JoltSession, JoltRemoteService, and JoltTransaction classes.

The same sample combines two user-defined BEA Tuxedo services (WITHDRAWAL and DEPOSIT) to perform a simulated TRANSFER transaction. If the WITHDRAWAL operation fails, a rollback is performed. Otherwise, a DEPOSIT is performed and a commit completes the transaction.

The following programming steps describe the transaction process shown in the sample code listing Jolt Transfer of Funds Example (SimXfer.java):

Set the connection attributes like hostname and portnumber in the JoltSessionAttribute object.
Refer to this line in the following code listing:
```
sattr = new JoltSessionAttributes();
```
The sattr.checkAuthenticationLevel() allows the application to determine the level of security required to log on to the server.
Refer to this line in the following code listing:
```
switch (sattr.checkAuthenticationLevel())
```
The logon is accomplished by instantiating a JoltSession object.
Refer to these lines in the following code listing:
```
session = new JoltSession (sattr, userName, userRole, 
userPassword, appPassword);
```
This example does not explicitly catch SessionException errors.
All JoltRemoteService calls require a service to be specified and the session key returned from JoltSession().
Refer to these lines in the following code listing:
```
withdrawal = new JoltRemoteService("WITHDRAWAL", session);
```
```
deposit = new JoltRemoteService("DEPOSIT", session);
```
These calls bind the service definition of both the WITHDRAWAL and DEPOSIT services, which are stored in the Jolt Repository, to the withdrawal and deposit objects, respectively. The services WITHDRAWAL and DEPOSIT must be defined in the Jolt Repository; otherwise a ServiceException is thrown. This example does not explicitly catch ServiceException errors.
Once the service definitions are returned, the application-specific fields such as account number ACCOUNT_ID and withdrawal amount SAMOUNT are automatically populated.
Refer to these lines in the following code listing:
```
withdrawal.addInt("ACCOUNT_ID", 100000);
```
```
withdrawal.addString("SAMOUNT", "100.00");
```
The add*() methods can throw IllegalAccessError or NoSuchFieldError exceptions.
The JoltTransaction call allows a timeout to be specified if the transaction does not complete within the specified time.
Refer to this line in the following code listing:
```
trans = new JoltTransaction(5,session);
```
Once the withdrawal service definition is automatically populated, the withdrawal service is invoked by calling the withdrawal.call(trans) method.
Refer to this line in the following code listing:
```
withdrawal.call(trans);
```
A failed WITHDRAWAL can be rolled back.
Refer to this line in the following code listing:
```
trans.rollback();
```
Otherwise, once the DEPOSIT is performed, all the transactions are committed. Refer to these lines in the following code listing:
```
deposit.call(trans);
```
```
trans.commit();
```

The following listing shows an example of a simple application for the transfer of funds using the Jolt classes.

Jolt Transfer of Funds Example (SimXfer.java)

/* Copyright 1999 BEA Systems, Inc.  All Rights Reserved */
import bea.jolt.*;
public class SimXfer
{
    public static void main (String[] args)
    {
        JoltSession  session;
        JoltSessionAttributes  sattr;
        JoltRemoteService withdrawal;
        JoltRemoteService  deposit;
        JoltTransaction  trans;
        String userName=null;
        String userPassword=null;
        String appPassword=null;
        String userRole="myapp";

        sattr = new JoltSessionAttributes(); 					
        sattr.setString(sattr.APPADDRESS, "//bluefish:8501");

        switch (sattr.checkAuthenticationLevel())		 
        {
        case JoltSessionAttributes.NOAUTH:
            System.out.println("NOAUTH\n");
            break;
        case JoltSessionAttributes.APPASSWORD:
            appPassword = "appPassword";
            break;
        case JoltSessionAttributes.USRPASSWORD:
             userName = "myname"; 
            userPassword = "mysecret";
            appPassword = "appPassword";
            break;
        }
        sattr.setInt(sattr.IDLETIMEOUT, 300);
        session = new JoltSession(sattr, userName, userRole,
        userPassword, appPassword);
        // Simulate a transfer
        withdrawal = new JoltRemoteService("WITHDRAWAL", session);
        deposit = new JoltRemoteService("DEPOSIT", session);

        withdrawal.addInt("ACCOUNT_ID", 100000);
        withdrawal.addString("SAMOUNT", "100.00");

        // Begin the transaction w/ a 5 sec timeout
        trans = new JoltTransaction(5, session);
        try
        {
            withdrawal.call(trans);
        }

        catch (ApplicationException e)
        {
            e.printStackTrace();
            // This service uses the STATLIN field to report errors
            // back to the client application.
            System.err.println(withdrawal.getStringDef("STATLIN","NO 
            STATLIN"));
            System.exit(1);
        }

        String wbal = withdrawal.getStringDef("SBALANCE", "$-1.0");

        // remove leading "$" before converting string to float
        float w = Float.valueOf(wbal.substring(1)).floatValue();
        if (w < 0.0)
        {
            System.err.println("Insufficient funds");
            trans.rollback();
            System.exit(1);
        }
        else            // now attempt to deposit/transfer the funds
        {
            deposit.addInt("ACCOUNT_ID", 100001);
            deposit.addString("SAMOUNT", "100.00");

            deposit.call(trans);
            String dbal = deposit.getStringDef("SBALANCE", "-1.0");
            trans.commit();

            System.out.println("Successful withdrawal");
            System.out.println("New balance is: " + wbal);

            System.out.println("Successful deposit");
            System.out.println("New balance is: " + dbal);
        }

        session.endSession();
        System.exit(0);
        } // end main
    } // end SimXfer