Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
Jolt for WebLogic Server User's Guide:   Previous topic   |   Next topic   |   Contents   |  Index

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

• Importing Packages

• Configuring a Session Pool

• Accessing a Servlet Session Pool

• Using a Servlet Session Pool

• Accessing a Tuxedo Service Through Jolt

• Converting Java Data Types to Tuxedo Data Types

• Receiving Results From a Service

• Using a Transaction

• Handling Exceptions

Importing Packages

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

bea.jolt.pool.*

bea.jolt.pool.servlet.*

weblogic.jndi.*

You must import the JNDI package to look up the SessionPoolManager.

There are other classes you must import into any servlet; for more information on writing Java servlets, read the "Using WebLogic HTTP Servlets" section in the WebLogic Developer Guide.

You create and access session pools through the SessionPoolManager class. You can use the SessionPoolManager to create a session pool from within your application code, or have the WebLogic Server perform this task for you on startup by setting a property in the weblogic.properties file. The latter method is recommended, because it provides a soft-coded configuration that is not part of your application logic so that you can administer it without changing and recompiling your code. The instructions in this section assume that you are using the property settings method.

WebLogic Server uses a variation of the session pool called a servlet session pool. The servlet session pool provides some extra functionality that is convenient for use inside an HTTP servlet.

You configure a servlet session pool in the weblogic.properties file by adding a set of properties:

weblogic.system.startupClass.joltpool=\
bea.jolt.pool.servlet.weblogic.PoolManagerStartUp
weblogic.system.startupArgs.joltpool=\
    poolname=joltpoolname,\
    appaddrlist=//hostname:port;//hostname:port,\
    failoverlist=//hostname:port,\
    minpoolsize=1
    maxpoolsize=3

When WebLogic is started (or restarted), it invokes the PoolManagerStartUp class and its associated startupArgs. This association is made via a virtual name binding; in this example, we used joltpool. For more information on virtual names and the WebLogic properties file, see the WebLogic Administrator's Guide section "Setting WebLogic Properties."

On the first invocation, the PoolManagerStartUp class creates a ServletSessionPoolManager object, which contains every ServletSessionPool configured in the WebLogic properties file. Subsequent calls add another ServletSessionPool to the same ServletSessionPoolManager. You must add registrations to the WebLogic properties file for each session pool, using a unique virtual name binding for each, as shown in the preceding properties example.

The ServletSessionPoolManager object is always bound to the name defined by SessionPoolManager.POOLMANAGER_NAME, and is added to WebLogic's JNDI tree so that it may be retrieved by your application code later. This process is described in Accessing a Servlet Session Pool.

The WebLogic Server creates a new ServletSessionPool as defined by the startupArgs you supply in the properties file.

For additional information about property settings and a list of definitions, see " Jolt Startup Properties.

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. You can look up the pool manager in the WebLogic JNDI InitialContext using the following code:

  // Create the InitialContext

  Context ctx = new InitialContext (new Environment());

  // Lookup the pool manager

  ServletSessionPoolManager poolMgr = (ServletSessionPoolManager) 

    ctx.lookup(SessionPoolManager.POOLMANAGER_NAME);

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 properties file.

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 properties file. When you initiate a request, the SessionPool uses the least-busy connection available.

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.

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.

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.

To access an existing Tuxedo service through Jolt, you must define and export the service in the Jolt Repository. For details, refer to the Jolt User's Guide sections "Jolt Repository Editor" and "Jolt Bulk Loader." 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[ ]

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 }.

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 the Jolt WAS Developer's Guide 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.

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.

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.

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.

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:

• bea.jolt.pool.ApplicationException

  Thrown when an error occurs in the logic of the Tuxedo service. For example, a client illegally attempts to use a withdrawal service to withdraw more money from an account than the current balance. The ApplicationException is thrown when the Tuxedo service returns a TPESVCFAIL. Application-specific information about the error can be included in the Result object that was returned from the service invocation. You can access the Result object through the ApplicationException.getResult() method.

  Be sure to use the full package name of the bea.jolt.pool.ApplicationException, because Jolt defines another exception whose full package name is bea.jolt.ApplicationException.

• bea.jolt.JoltException

  A JoltException is the super class of all the following exceptions. These exceptions all signify that a system error has occurred that is not part of the application logic. JoltException is documented in Appendix A, "Jolt Class Library Reference," in the Jolt User's Guide.

• bea.jolt.pool.SessionPoolException

  Thrown when an error occurs in the Jolt SessionPool. For example, this may occur if all sessions are busy, or if the session pool is suspended.

• bea.jolt.ServiceException

  Thrown when an error occurs related to invoking the Tuxedo service that contains the application. For example, a service timeout, or a non existent service is called.

• bea.jolt.TransactionException

  Thrown when a transaction cannot be either started, committed, or aborted.