Using BEA Jolt with BEA WebLogic Server

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Implementing Jolt for WebLogic

Setting up Jolt to connect to Tuxedo from your WebLogic application or servlet requires the following steps:

See page B-1 for a simple example that establishes a connection and accesses a Tuxedo service from an HTTP servlet.

 


Importing Packages

The Jolt Java class packages are automatically installed when you install Jolt for WebLogic Server. To use BEA Jolt for BEA WebLogic Server, import the following class packages that were installed with Jolt into your servlet:

bea.jolt.pool.*
bea.jolt.pool.servlet.*

There are other classes you must import into any servlet; for more information on writing Java servlets, read the Programming WebLogic HTTP Servlets guide.

 


Configuring a Session Pool

You can access session pools through the SessionPoolManager class. WebLogic Server uses a variation of the session pool called a servlet session pool. The servlet session pool provides extra functionality that is convenient for use inside an HTTP servlet.

When you configure a servlet session pool through the WebLogic Administration Console, the following information is added to the config.xml configuration file:

<StartupClass
ClassName="bea.jolt.pool.servlet.weblogic.PoolManagerStartUp"
FailureIsFatal="false"
Name="MyStartup Class"
Targets="myserver"
/>
<JoltConnectionPool
ApplicationPassword="tuxedo"
MaximumPoolSize="5"
MinimumPoolSize="3"
Name="MyJolt Connection Pool"
PrimaryAddresses="//TUXSERVER:6309"
RecvTimeout="300"
SecurityContextEnabled="true"
Targets="myserver"
UserName="joltuser"
UserPassword="jolttest"
UserRole="clt"
/>

When WebLogic is started (or restarted), it invokes the PoolManagerStartUp class and its associated startupArgs. On the first invocation, the PoolManagerStartUp class creates a ServletSessionPoolManager object, which contains every ServletSessionPool configured in the config.xml configuration file.

Subsequent calls add another ServletSessionPool to the same ServletSessionPoolManager. You must add an entry for each session pool, using a unique virtual name binding for each, as shown in the preceding example. The WebLogic Server creates a new ServletSessionPool as defined in the config.xml file.

For additional information about property settings and a list of definitions, see Jolt Startup Class and Connection Pool.

Accessing a Servlet Session Pool

Once a WebLogic Server is configured to set up a Jolt session pool on startup, you can access and use the Jolt session pool from your Java application or servlet. As described earlier, in the WebLogic Server all ServletSessionPool objects are managed by the same ServletSessionPoolManager.

  ServletSessionPoolManager poolMgr = (ServletSessionPoolManager) 
    SessionPoolManager.poolmanager;

The WebLogic Server uses a ServletSessionPoolManager class that is derived from SessionPoolManager. The ServletSessionPoolManager manages ServletSessionPool objects, which offer additional HTTP servlet methods.

SessionPoolManager provides several methods for managing the administration of a session pool. In the following example, the SessionPoolManager is used to retrieve the SessionPool that has been named joltpoolname:

  SessionPool sPool = poolMgr.getSessionPool("joltpoolname");

However, because the WebLogic Server uses the subclass ServletSessionPoolManager, the above example actually returns a ServletSessionPool object in the guise of a SessionPool.

You must cast the SessionPool to a ServletSessionPool, as in the following code example:

  ServletSessionPool ssPool =
    (ServletSessionPool) poolMgr.getSessionPool("joltpoolname");

Because WebLogic Server creates and configures the ServletSessionPoolManager, it is likely that this is the only method you will use. Other SessionPoolManager methods allow you to create, suspend, stop, or shut down individual or all the session pools it manages. We recommend that you leave these administrative operations to the WebLogic Server by configuring and managing your session pools using the WebLogic config.xml configuration file.

 


Using a Servlet Session Pool

The reference to the named ServletSessionPool from the pool manager represents a pool of sessions (or connections) to the Jolt Server in Tuxedo. The size of this pool and the Tuxedo system to which it connects are abstracted from the application code and are defined in the WebLogic config.xml configuration file. When you initiate a request, the SessionPool uses the least-busy connection available.

Calling a Tuxedo Service

A Jolt request usually consists of a single call to a Tuxedo service using the call() method of the SessionPool. You supply the name of the Tuxedo service and a set of parameters to the call() method, and it returns a set of results from the Tuxedo service. It is possible to make multiple calls within a single transaction, which allows a servlet to comply with transactional demands of a Tuxedo application or preserve integrity between databases. This transaction is described in more detail in "Using a Transaction" on page 3-9.

Sending a ServletDataSet

The ServletSessionPool provides overloaded call() methods for use inside an HTTP servlet. These methods accept their input parameters in terms of an HttpServletRequest object, and therefore can conveniently be passed the same HttpServletRequest object that was passed into your HTTP servlet's doPost() or doGet() methods. However, in this instance, you must ensure that the names of the HTTP posted name=value pairs correspond to those expected by the Tuxedo service. The ordering is not important, because the data is ultimately converted into a Java Hashtable. Other non-related data in the HttpServletRequest will not disrupt the Tuxedo service.

A Tuxedo service is invoked from within an HTTP servlet with the following method:

    ssPool.call("serviceName", request);

where ssPool is a reference to a ServletSessionPool, "serviceName" is the name of the Tuxedo service you wish to call, and the request argument is the HttpServletRequest object associated with the servlet.

The ServletSessionPool.call() method internally converts the HttpServletRequest into a ServletDataSet, which can be submitted to a regular SessionPool.

Adding Parameters to the Dataset

You may wish to add extra data to the parameter set before calling the Tuxedo service. For example, you may need to add a parameter representing the date and time of the request. You would not expect to receive this parameter from the FORM data in the HttpServletRequest. Instead, add it in the servlet, then submit the augmented data set to the Tuxedo service. The following example illustrates this procedure:

  // Create a new dataset
  ServletDataSet dataset = new ServletDataSet();
  // Import the HttpServletRequest into the dataset.
  dataset.importRequest(request);
  // Insert an extra parameter into the dataset.
  dataset.setValue("REQUEST_TIME", (new Date()).toString());
  // Send the dataset to the named service.
  ssPool.call("service_name", dataset, null);

This code example demonstrates the manual conversion of the HttpServletRequest object into a ServletDataSet object. In this new format you can add extra parameters using the setValue() method. The new value is associated with a key, represented by a string. Next, the call() method that is inherited from the SessionPool is invoked. This method accepts the ServletDataSet class, but requires an extra argument for use with transactions. Supply null for this last parameter, indicating that you are not using a transaction to group multiple session calls. See Using a Transaction for more details.

 


Accessing a Tuxedo Service Through Jolt

To access an existing Tuxedo service through Jolt, you must define and export the service in the Jolt Repository. For details, refer to the Using BEA Jolt sections "Using the Jolt Repository Editor" and "Bulk Loading BEA Jolt Services." The Jolt service definition defines the parameters that are expected by the Tuxedo application service.

 


Converting Java Data Types to Tuxedo Data Types

The following table is a mapping between Java types and Tuxedo parameter types required by a Tuxedo service. Use the appropriate Java types for the value of the DataSet or ServletDataSet. If you specify any parameter as a Java String, it is translated automatically to the appropriate type according to the service definition in the Jolt Repository.

This feature is also used to convert all data inside an HttpServletRequest object, because all parameters associated with the request are represented in string format. Otherwise, use the type specified in the table below. Providing the correct data type may improve efficiency because no lookup is required to convert from a string.

BEA Tuxedo Type
Java Type
char
Byte
short
Short
long
Integer
float
Float
double
Double
char*
String
CARRAY
byte[ ]
XML
byte[ ]

A Tuxedo CARRAY is specified in a Java string by describing each byte value as a two-digit hexadecimal number. You specify multiple bytes by concatenating these hexadecimal digit-pairs together. For example, the string "FF0A20" would represent the Tuxedo type CARRAY { 255, 10, 32 }.

 


Receiving Results from a Service

The ServletSessionPool.call() method returns a ServletResult object that contains the results from the Tuxedo service. If the service call fails, an exception is thrown. You should always attempt to catch exceptions and handle them appropriately. Refer to "Appendix A, BEA Jolt Exceptions" in Using BEA Jolt for details about the possible exceptions that can occur.

The following example retrieves a ServletResult object using the ServletSessionPool.call() method in an HTTP servlet:

  ServletResult sResult = ssPool.call("service_name", request);

where ssPool is a ServletSessionPool, and request is an HttpServletRequest.

The ServletSessionPool.call() method returns a Result object that you must cast as a ServletResult object. The ServletResult object provides extra methods for retrieving data as Java Strings.

Provided the call was successful, the individual parameters can be retrieved from the Result or ServletResult object using various forms of the getValue() method.

Using the Result.getValue() Method

The data is retrieved from a ServletResult by providing a key that corresponds to the parameter names of the Tuxedo service, as defined in the Jolt Repository. You supply the key to the appropriate getValue() method, which returns the corresponding value object.

The Result.getValue() method also expects a default value object; this is returned if the key lookup fails. It is your responsibility to cast the returned object to the appropriate type, as defined by the Tuxedo service. For example, this line of code:

  Integer answer = (Integer) resultSet.getValue("Age", null);

sets the integer answer to the returned value in the ServletResult identified by the key "Age", or returns null if this key does not exist in the ServletResult. Refer to the table in Converting Java Data Types to Tuxedo Data Types for the Java equivalents of the Tuxedo types.

It is possible to have an array of values associated with a key. In this case, the simple getValue() method returns the first element of an array in this instance. Use this method signature in that case:

  public Object getValue(String name, int index, Object defVal)

to reference a particular indexed element in an array value.

Using the ServletResult.getStringValue() Method

ServletResult extends Result, and provides the additional methods:

  public String getStringValue(String name,
                               int index,
                               String defVal)
                             
  public String getStringValue(String name,
                               String defVal)

These methods behave like the getValue() methods of the Result class, except that they always return a Java string equivalent of the value object expected. The CARRAY is converted into a string of two digit hexadecimal byte values as described in Converting Java Data Types to Tuxedo Data Types.

 


Using a Transaction

You can use a transaction object to group multiple service calls into an atomic action, maintaining data integrity within your application logic. You obtain a transaction from a session pool with the method:

  Transaction trans = ssPool.startTransaction(timeout);

where the transaction object trans holds the reference to the transaction, ssPool is the SessionPool or ServletSessionPool object, and the timeout argument for the transaction is specified in seconds.

Once a transaction obtains a session, that session cannot be used by other transactions until the transaction is committed, aborted, or times out. The session may, however, still be used by single requests that are not part of a transaction. If a transaction fails to obtain a session from the pool, this method throws a bea.jolt.pool.TransactionException. If the session pool is suspended, the method throws a bea.jolt.pool.SessionPoolException.

Each time your application uses the call() method, you should supply the transaction object as the last parameter. For example:

  ssPool.call("svcName", request, trans);

You can make multiple calls in the same transaction. The calls will not complete until you either commit or roll back the transaction using the methods of the transaction object. The trans.commit() method completes the transaction. This method returns 0 if the commit was successful, or throws a TransactionException if the transaction failed to commit.

If you need to abort the transaction, use the Transaction.rollback() method. This method attempts to abort the transaction. It returns 0 if successful; otherwise it throws a TransactionException.

Handling Exceptions

Errors or failures that may occur when Jolt initiates a Tuxedo service call are reported to your application through Java exceptions. Always enclose the call() method within a try / catch block and attempt to deal with any exceptions appropriately. The call() method can throw any of the following exceptions for the following reasons:


  Back to Top       Previous  Next