Chapter 4. Web Application Services Class Library Reference

The Web Application Services Class Library consists of object-oriented Java language classes for creating a TUXEDO session.

The Web Application Services Class Library Reference includes the following topics:

bea.web Package

This Java package contains all the core Jolt wrapper classes that are neutral to all Web servers. These classes are:

UserInfo Class

java.lang.Object
   |
   +----bea.web.UserInfo

This class contains the TUXEDO user authentication information. This information may be needed to create a TUXEDO session. If the user does not want to expose the authentication information on the web server, the user may embed the authentication information within a derived class.

UserInfo Constructor

The following constructor creates an instance of the UserInfo class.

UserInfo

This constructor creates an instance of the UserInfo class.

Synopsis

UserInfo()

UserInfo Methods

The following methods are used in conjunction with the UserInfo class:

setUserName

Synopsis

void setUserName(String username)

Parameters

username: Specifies a valid user name.

Usage

You must set the TUXEDO user name before creating a session pool. This is only required if the user authorization level is specified in TUXEDO.

setUserPassword

Synopsis

void setUserPassword(String password)

Parameters

password: A valid user password.

Usage

You must set the TUXEDO user password before creating a session. This is only required if the user authorization level is specified in TUXEDO.

setUserRole

Synopsis

void setUserRole(String userrole)

Parameters

userrole: A valid user role.

Usage

You must set the TUXEDO user role before creating a session. This is only required if the user authorization level is specified in TUXEDO.

setAppPassword

Synopsis

void setAppPassword(String password)

Parameters

password: A valid application password.

Usage

You must set the TUXEDO application password before creating a session. This is only required if the application or user authorization level is specified in TUXEDO.

SessionPoolManager Class

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----bea.web.SessionPoolManager

This base class represents a session pool manager which manages one or more session pools. Each session pool identified by an ID contains a pool of connections to Jolt servers.

When an HTTP request arrives, the session pool manager uses an ID to find the corresponding session pool to serve the request.

SessionPoolManager Methods

The following methods are used in conjunction with the SessionPoolManager class:

done

Synopsis

final void done()

Usage

Done with this session manager.

createSessionPool

Synopsis

final int createSessionPool(String addrs[], String saddrs[], 
int minCons, int maxCons, UserInfo usr, String id)

stopSessionPool

Synopsis

final void stopSessionPool(String id)

Parameters

id: Reserved for future use. Must be null.

Usage

Shut down a session pool; all active connections in the session are also terminated immediately. The ID must be null for this release. This method is part of the administrative class library.

getSessionPool

Synopsis

final SessionPool getSessionPool(String id)

Parameters

id: Reserved for future use. Must be null.

Usage

Get the session pool. If the session pool does not exist, this method will return a null object. The ID must be null for this release.

Returns

A session pool or null if it does not exist.

suspendSessionPool

Synopsis

final void suspendSessionPool(String id, boolean action)

Parameters

id: Reserved for future use. Must be null.
action: true to suspend the session pool; false to resume it.

Usage

Suspend this session pool so it will not accept any new requests. It allows the administrator to shut down the session pool gracefully. The ID must be null for this release. This method is part of the administrative class library.

removeSessionPool

Synopsis

final void removeSessionPool(String id)

Parameters

id: Removed for future use. Must be null.

Usage

Shut down and remove the session pool; all active connections in this session pool are terminated immediately. The ID must match the id in createSessionPool(). This method is part of the administrative class library.

SessionPool Class

java.lang.Object
   |
   +----bea.web.SessionPool

This base class represents a session pool that contains one or more connections (sessions) to Jolt servers. The session pool is responsible to select the least busy connection to serve each service call. An application may tie multiple service calls into a transaction. To start a transaction, the session pool selects the least busy connection and puts it in transactional mode.

Unless the number of connections in the session pool is one or the request is engaged in a transaction, there is no guarantee that the service calls in each HTTP request will be served by the same connection. All service calls associated with the transaction are handled by the same connection. The connection is locked until the transaction is committed or aborted. The transaction should be committed or aborted before continuing to another page, unless programmatic arrangements to commit or abort the transaction have been made.

SessionPool Methods

The following methods are used in conjunction with the SessionPool class:

startTransaction

Synopsis

Transaction startTransaction(int timeout)

Parameters

timeout: The transaction time-out value in seconds.

Usage

Start a transaction. The transaction should be committed or aborted before continuing to another page, unless programmatic arrangements to commit or abort the transaction have been made. Otherwise, the connection is locked until the transaction is terminated.

Returns

A transaction object, or null if failure occurs.

getConnection

Synopsis

int getConnection(int index)

Usage

Get a connection. This method is part of the administrative class library.

Parameters

index: A connection index.

getMaxConnections

Synopsis

int getMaxConnections()

Usage

Get the maximum number of connections configured in this session. This method is part of the administrative class library.

setMaxConnections

Synopsis

int setMaxConnections(int maxCons)

Parameters

maxCons: The new session pool size.

Usage

Change the session pool size. Currently shrinking the session pool is disallowed. This method is part of the administrative class library.

Returns

The new spool size, or -1 for shrinking the session pool.

isSuspended

Synopsis

boolean isSuspended()

Usage

Check if this session pool is suspended. A suspended session pool does not accept any new requests. This method is part of the administrative class library.

Connection Class

java.lang.Object
   |
   +----bea.web.Connection

This class represents a connection (session) to a Jolt server and provides simple methods for service invocations and transaction demarcation. This class is a part of the administrative class library.

Connection Methods

The following methods are used in conjunction with the Connection class:

getAccessTime

Synopsis

final Date getAccessTime()

Usage

Get the last access time of this object.

getAddr

Synopsis

final String getAddr()

Usage

Get the server address.

getErrorCount

Synopsis

final int getErrorCount()

Usage

Get the cumulative system error count.

getUseCount

Synopsis

final int getUseCount()

Usage

Get the outstanding request count.

inTransaction

Synopsis

boolean inTransaction()

Usage

Check if the connection is in a transaction.

Returns

True if the connection is in a transaction; false otherwise.

isAlive

Synopsis

boolean isAlive()

Usage

Check if the connection is still alive.

Returns

True if the connection is still alive; false otherwise.

Transaction Class

java.lang.Object
   |
   +----bea.web.Transaction

This class is a wrapper for the bea.joltJoltTransaction class. If an error occurs, the method in this class returns an error code instead of throwing an exception.

Transaction Methods

The following methods are used in conjunction with the Transaction class:

commit

Synopsis

int commit()

Usage

Commit the transaction.

Returns

0 if successful; otherwise, a TUXEDO error number.

rollback

Synopsis

int rollback()

Usage

Roll back the transaction.

Returns

0 if successful; otherwise, a TUXEDO error number.

Template Class

java.lang.Object
   |
   +----bea.web.Template

This base class processes a template and replaces tags of the form <%=name%> or indexed tags of the form <%=name[index]%> (where name and index are user-defined constructs) with values. name must start with an underscore (_) or letter and be followed by one or more letters, digits, or underscores. The values from the TemplateData Class are used to populate the tags. If a duplicate name exists in the multiple TemplateData objects, the later element has a higher precedence.

Template Methods

The following methods are used in conjunction with the Template class:

load
unload

load

Synopsis

final int load(String path)

Parameters

path: The path to the template file.

Usage

Load the template file into memory. The contents are cached until the unload method is called.

Returns

0 if success; -1 if file cannot be opened.

unload

Synopsis

final void unload()

Usage

Unload the cached template contents.

TemplateData Class

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----bea.web.TemplateData

This base class extends from java.util.Hashtable and it provides a fast mechanism to store and retrieve a data element by name and index. The keys in the hash table are the names of the data elements.

TemplateData Methods

The following methods are used in conjunction with the TemplateData class:

setValue - by index

Synopsis

void setValue(String name, int index, String value)

Parameters

name: The name of the data element.
index: The index of the data element.
value: The value of the data element.

Usage

Set the string value of a data element associated with a name and an index.

setValue

Synopsis

void setValue(String name, String value)

Parameters

name: The name of the data element.
value: The value of the data element.

Usage

This method is the same as setValue(name,0,value) for a non-octet value.

getValue - by index

Synopsis

String getValue(String name, int index, String defaultValue)

Parameters

name: The name of the data element.
index: The index of the data element.
defaultValue: The default value if the element does not exist.

Usage

Get the string value of a data element associated with a name and an index. Most output data, except carray (octets) data type, are automatically converted to String. If there is a typecast error, the default value will be returned.

Returns

The value of the data element or the default value.

getValue

Synopsis

String getValue(String name, String defaultValue)

Parameters

name: The name of the data element
defaultValue: The default value if the element does not exist

Usage

This method is same as getValue(name,0,defaultValue).

Returns

The value of the data element, or the default value.

getBytesValue - by index

Synopsis

byte[] getBytesValue(String name, int index, byte defval[])

Parameters

name: The name of the data element.
index: The index of the data element, starting from 0.
defval: The default value if the data element does not exist.

Usage

Get the octet value of a data element associated with a name and an index. If an output field has carray (octets) data type, the data remains as byte[]. The caller must use this method to retrieve the data. If there is a typecast error, the default value will be returned.

Returns

The octet value of the data element or the default value.

getBytesValue

Synopsis

byte[] getBytesValue(String name, byte defval[])

Parameters

name: The name of the data element.
defval: The default value if the attribute does not exist.

Usage

This method is same as getBytesValue(name, 0, defval) method.

Returns

The octet value of the data element or the default value.

setBytesValue - by index

Synopsis

void setBytesValue(String name, int index, byte value[])

Parameters

name: The name of the data element.
index: The index of the data element.
value: The octet value for the data element.

Usage

Set the octet value of a data element associated with a name and an index. The data element should be defined as carray in TUXEDO.

setBytesValue

Synopsis

void setBytesValue(String name, byte value[])

Parameters

name: The name of the data element.
value: The octet value for the data element.

Usage

This method is same as setBytesValue(name,0,value) for the octet value.

getCount

Synopsis

int getCount(String name)

Parameters

name: The name of the data element.

Usage

Get the occurrence count of a data element.

Returns

The count.

Result Class

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----bea.web.TemplateData
                           |
                           +----bea.web.Result

This class represents the result set from the service invocation. Most output data types are converted into String, except carray which remains as byte[]. The caller must use the getBytesValue() methods to get the carray data. The keys to the hash table are the field names in the result set. Since this class is derived from the TemplateData class, it can be used by the Template class for template processing.

Result Methods

The following methods are used in conjunction with the Result class:

applicationError

Synopsis

boolean applicationError()

Usage

Test if an application error occurred in the last service invocation. The application error is equivalent to TPESVCFAIL in TUXEDO.

Returns

True if an application error occurred; false otherwise.

getApplicationCode

Synopsis

int getApplicationCode()

Usage

Get the application code returned by the service. The application code is same as the tpurcode in TUXEDO.

Returns

The application code.

getError

Synopsis

int getError()

Usage

Get the system (non-TPESVCFAIL) error number. The error number is the same as the tperrno in TUXEDO.

Returns

The error number.

getErrorDetail

Synopsis

int getErrorDetail()

Usage

Get the detail system error number. This information is available only to TUXEDO 6.4 and then only if the service call has timed out.

Returns

The detail system error number, if TUXEDO 6.4; otherwise 0.

getStringError

Synopsis

String getStringError()

Usage

Get the system error message.

Returns

The system error message. If it is not a system error, null is returned.

getStringErrorDetail

Synopsis

String getStringErrorDetail()

Usage

Get the detail system error message. This information is available only to
TUXEDO 6.4 and then only if the service call has timed out.

Returns

The detail system error message, if TUXEDO 6.4; otherwise null.

noError

Synopsis

boolean noError()

Usage

Test whether no error was encountered in the last service invocation.

Returns

True if no error occurred; false otherwise.

systemError

Synopsis

boolean systemError()

Usage

Test whether a system error occurred in the last service invocation.

Returns

True if a system error occurred; false otherwise.

bea.web.ns Package

The bea.web.ns package contains the classes specific for the Netscape server-side JavaScript. These classes are:

SessionPoolManager Class

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----bea.web.SessionPoolManager
                           |
                           +----bea.web.ns.SessionPoolManager

This class provides a session pool factory for the Netscape-specific SessionPool object and provides the conversion from LiveWire JSObject to Jolt object. The actual implementation of the session pool manager is in its parent class.

SessionPoolManager Constructor

The following constructor creates an instance of the SessionPoolManager class.

SessionPoolManager

This constructor creates an instance of the SessionPoolManager class.
Synopsis

SessionPoolManager()

SessionPoolManager Method

The following method is used in conjunction with the SessionPoolManager class:

createSessionPool

createSessionPool

Synopsis

int createSessionPool(JSObject addrs, JSObject saddrs, 
int minCons, int maxCons, UserInfo usr, String id)

Parameters

addrs: A JavaScript Array of primary server addresses.
saddrs: A JavaScript Array of secondary fail-over server addresses, or null.
minCons: The minimum number of connections.
maxCons: The maximum number of connections.
usr: The user authentication information, or null.
id: A unique ID for the session pool, or null.

Usage

Create a session pool with multiple restartable connections. This method is the same as bea.web.createSessionPool, except the addrs and saddrs parameters are JavaScript Array objects (for example, addrs[0] = "//mach:7000").

Returns

The number of successful connections.

SessionPool Class

java.lang.Object
   |
   +----bea.web.SessionPool
           |
           +----bea.web.ns.SessionPool

This class extends from the bea.web.SessionPool and it provides an additional call() method that understands Netscape server-side JavaScript object.

SessionPool Methods

The following methods are used in conjunction with the SessionPool class:

call

Synopsis

Result call(String name, JSObject indata)

Parameters

name: The name of a TUXEDO service.
indata: JavaScript string Array or built-in request object

Usage

Call a service without involving any transaction. This is equivalent to using the call(name, indata, null) method.

Returns

A Result object.

call - with transaction

Synopsis

Result call(String name, JSObject indata, Transaction tran)

Parameters

name: The name of a TUXEDO service.
indata: JavaScript string Array or built-in request object.
tran: A Transaction object.

Usage

Call a service with a transaction. The indata parameter is either a JavaScript Array of name-value pairs or a server-side JavaScript Request object. (A name-value pair is a construct of the form name=value.) The name in the name-value pair should match the parameter name in the Jolt service definition. The member name in the Request object can have a trailing underscore and an index number (as, for example, SBALANCE_0) if it is a multiple occurrence field. Any nonmatching names in the indata parameter are ignored. The tran parameter must be the object returned by the startTransaction() method.

Returns

A Result object.

Template Class

java.lang.Object
   |
   +----bea.web.Template
           |
           +----bea.web.ns.Template

This class extends from bea.web.Template and it provides some additional methods that understands Netscape server-side JavaScript objects.

Template Constructors

The following constructor creates an instance of the Template class.

Synopsis

Template()

Usage

A default constructor.

Template Methods

The following methods are used in conjunction with the Template class:

eval - data set array

Synopsis

int eval(JSObject data)

Parameters

data: An array of TemplateData objects.

Usage

Process the cached template with a list of data set and send the processed template to the client. The list must be a JavaScript Array object.

Results

0 if success; -1 for any I/O error.

eval - data set

Synopsis

final int eval(TemplateData data)

Parameters

data: A template data set, or null.

Usage

Process the cached template with a data set and send the processed template to the client.

Returns

0 if success; -1 for any I/O error.

evalFile - data set array

Synopsis

int evalFile(String path, JSObject data)

Parameters

path: An absolute path of the template file
data: An array of TemplateData objects.

Usage

Process a template file with a list of data sets. The list must be a JavaScript Array object.

Returns

0 if success; -1 if the template file cannot be opened or there is an I/O error.

evalFile - data set

Synopsis

final int evalFile(String path, TemplateData data)

Parameters

path: A path of the template file.
data: A template data set, or null.

Usage

Process a template file with a data set and send the processed template to the client.

Returns

0 if success; -1 if the template file cannot be opened or there is an I/O error.

TemplateData Class

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----bea.web.TemplateData
                           |
                           +----bea.web.ns.TemplateData

This class represents the data set that can be used by template processing or service invocation to store the result set. It provides an extra method to import the server-side JavaScript request object. The keys to the hash table are the field names in the data set.

TemplateData Constructors

The following constructor creates an instance of the TemplateData class.

Synopsis

TemplateData()

Usage

A default constructor.

TemplateData Methods

The following method is used in conjunction with the TemplateData class:

importRequest

importRequest

Synopsis

void importRequest(JSObject request)

Parameters

request: A server-side JavaScript Request object.

Usage

Import the values from the server-side Request into this data set object.