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.
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.
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.
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.
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.
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 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.
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.
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 "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.
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, "BEA Jolt Exceptions," in the Using BEA Jolt.
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.