Chapter 7 . Jolt Class Library Reference

The Jolt Class Library consists of object-oriented Java language classes for accessing BEA TUXEDO services and defining transactions. The Jolt Class Library package is designed to be small, simple, and easy to incorporate into your Java application. The classes for this package provide TUXEDO logon/logoff, synchronous calling, and transaction services for a client Java applet.

The Jolt Class Library reference includes the following topics:

Each class description includes information about the class constructor and class methods.

To use the following information, you need to be generally familiar with the Java programming language and object-oriented programming concepts. The reference material follows the Java standard terminology for classes and for the methods that operate on the class instances.

For information about programming the Jolt Class Library, refer to Chapter 6, "Using the Jolt Class Library." For information about the Jolt exception classes and related TUXEDO errors listed for the Jolt classes, refer to Appendix A, "Jolt Class Library Errors and Exceptions."

Jolt Methods

The Jolt classes and class methods that form the Jolt Class Library follow the Java language structure and are intended for use in Java programs. However, since the Jolt Class Library is designed for accessing TUXEDO System applications, you need to be aware of how get, set, add, and delete methods operate within the context of transaction processing.

For example, if you are working with a series of account numbers for a banking transaction and are changing the value from one account number to another account number, you must be aware of how the Jolt methods determine the position of an item in a list. Understanding how these methods work will help you avoid inadvertently reversing the order of a transaction, assigning incorrect values to an item, or deleting the wrong item.

Methods for Handling Items

The get, set, and setItem methods are used to obtain information about a specified item or to change information about a specified item. The add methods append a specified item to a list and the delete and deleteItem methods remove specified items. The following sections describe how these methods operate on an item in a list of items.

Changing the First Item Occurrence

The set and delete methods operate on the first occurrence of an item in a list. In Jolt, the first occurrence of an item is always at position zero. For example, if you have a list of account numbers and you use a delete method, the item at position zero is deleted. For example: 

delete ( "ACCTNUM")

Deletes the account number at position zero of the account number list. 

setInt ( "ACCTNUM", 3200)

Sets the account number at position zero to the value 3200.

Changing Items by Item Position

The following types of methods in the Jolt Class Library are position dependent. To change a position-dependent item, you specify the location or index of the item in a list.

For example, to set the third item in a list of account numbers to a value, you would specify the following: 

setIntItem ("ACCTID", 2, 5000)

The example sets the account number at position three to the value 5000. You specify an index of 2 because the index numbering starts at 0 and 2 is at the third position of the list.

To delete the first item in a list of account numbers, you would specify the following: 

deleteItem ("ACCTID", 0)

The example deletes the account number at position 0 and is exactly equivalent to using just the delete method. A set...Item (name, 0, value) also works exactly as the set method.

Getting Items

The Jolt Class Library includes a number of get methods. However, the get methods operate differently from the other types of methods. The following three get methods retrieve information with a single value.

All other get methods are in the form of a get...Def or get...ItemDef. The get...Def methods retrieve information about the first item (item 0). The get...ItemDef methods retrieve information about an item that you specify by its position or index number. If the item has no information, these methods allow you to set a default. For example: 

getIntItemDef ("CreditRating", 4, -1)

The example gets the credit rating for the fifth item in a list of items starting at position zero. If the item has no value for a credit rating, the get returns the default value of -1. You specify the value for the method in the defValue parameter.

Appending Items

The add methods append an item to the end of a list of items. Of course if your list of items is empty, an add will make the item the first one in the list. In the following example, the add method appends a name to the end of a list of names: 

addString ("CompanyName", "BoltBikeWorks")

JoltSessionAttributes Class

 
java.lang.Object
   |
   +----bea.jolt.JoltSessionAttributes

The JoltSessionAttributes class defines the acceptable attributes for the JoltSession constructor. The set methods add the attribute if one does not exist. Otherwise, the set method overwrites the old value.

The get and set methods throw the java.lang.NoSuchFieldError or java.lang.IllegalAccessError. By default, these errors are caught by the Java virtual machine. 

public class JoltSessionAttributes 
{
/* The supported authentication levels. */
  public final static int NOAUTH;        // No authentication
  public final static int APPASSWORD;    // Application password
  public final static int USRPASSWORD;     // App and User passwords
  /* The attribute names for set and get. */
  public final static String APPADDRESS    // String "//host:port"
                                           // Used with setString()
  public final static String IDLETIMEOUT;  // Used with SetInt()"
  public final static String SENDTIMEOUT;  // Used with SetInt()"
  public final static String RECVTIMEOUT;    // Used with SetInt()"
 
  /* The attribute name for get only. */
  public final static String SESSIONTIMEOUT;    // getIntDef()
 
  public JoltSessionAttributes();
 
  //JoltSessionAttributes methods.
  public int  checkAuthenticationLevel() 
              throws SessionException;
  public void   clear();
  public byte   getByteDef( String name, byte defValue );
  public byte[] getBytesDef( String name, byte[] defValue );
  public double getDoubleDef( String name, double defValue );
  public float  getFloatDef( String name, float defValue );
  public int    getIntDef( String name, int defValue );
  public short  getShortDef( String name, short defValue );
  public String getStringDef( String name, String defValue );
  public void   setByte( String name, byte value );
  public void   setBytes( String name, byte[] value, int len);
  public void   setDouble( String name, double value );
  public void   setFloat( String name, float value );
  public void   setInt( String name, int value );
  public void   setShort( String name, short value );
  public void   setString( String name, String value );
}

JoltSessionAttributes Constructor

The following constructor creates an instance of the JoltSessionAttributes class.

JoltSessionAttributes

Allocates a new instance of the JoltSessionAttributes class.

Synopsis

public JoltSessionAttributes();

Usage

Specific components are extracted to assist in defining the attributes of the Session constructor.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

JoltSessionAttributes Methods

The following methods are used in conjunction with the JoltSessionAttributes class.

These JoltSessionAttributes methods are described in the following sections.

checkAuthenticationLevel

Gets the authentication level set up by the TUXEDO administrator.

Synopsis

int checkAuthenticationLevel()  throws SessionException;

Usage

The authentication level determines which values are set to the JoltSession constructor parameters. This method returns the authentication level specified in Table 7-1.

You must set APPADDRESS before calling this method (refer to Table 7-2).

Returns

Table 7-1 describes the possible return values for the checkAuthenticationLevel method.

Table 7-1 Return Values for the checkAuthenticationLevel Method
Return Value Description

NOAUTH

No authentication is required to access the system.

APPASSWORD

System authentication is required. Clients provide user name, user role, and application password to authenticate the system.

USRPASSWORD

System and application authentication are required to access the system. Clients provide user name, user role, user password, and application password to authenticate the system.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

clear

Removes all attributes.

Synopsis

void clear();

Usage

The JoltSessionAttributes class contains data that must be removed for object reuse. Use the clear method to remove data.

getByteDef

Gets the byte value of a specified item.

Synopsis

byte getByteDef ( String name, byte defValue );

Usage

Gets the byte value (8-bit) of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a single byte value.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getBytesDef

Gets an array of byte values.

Synopsis

byte[ ] getBytesDef ( String name, byte[] defValue );

Usage

Gets an array of byte values of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns an array of values.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getDoubleDef

Gets the double precision value of an item.

Synopsis

double getDoubleDef( String name, double defValue );

Usage

Gets the double precision value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns an double precision floating point value (64-bit).

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getFloatDef

Gets the floating point value of an item.

Synopsis

float getFloatDef( String name, float defValue );

Usage

Gets the floating point value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a floating point value (32-bit).

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getIntDef

Gets the integer value of an item.

Synopsis

int getIntDef( String name, int defValue );

Parameters

 name

Specifies the attribute name.

defValue

Specifies a default value for an item if it does not have an existing name.

Usage

Gets the integer value of the item specified in the name parameter or the specified defValue, if the name does not exist. Use these values to specify the defValue parameter for this method.

Returns

This method returns an integer value (32-bit).

Example

attr.getIntDef(attr.SESSIONTIMEOUT, 1);

Throws

 java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getShortDef

Gets the short integer value of an item.

Synopsis

short getShortDef( String name, short defValue );

Usage

Gets the short integer value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a short integer value (16-bit).

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

getStringDef

Gets the string value of an item.

Synopsis

String getStringDef( String name, String defValue );

Usage

Gets the string value of the item specified in the name parameter or the specified defValue, if the name does not exist. The default value can be a null string or any other text string.

Returns

This method returns a text string.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setByte

Sets the byte value of a specified item.

Synopsis

void setByte( String name, byte value );

Usage

Sets the value of the item specified in the name parameter to the byte value specified in the value parameter. The value is an 8-bit byte.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setBytes

Sets the byte array value of a specified item.

Synopsis

void setBytes( String name, byte[ ] value, int len );

Usage

Sets the value of the item specified in the name parameter to the byte array value specified in the value parameter, with the length set by the len parameter. The value is in 8-bit bytes.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setDouble

Sets the double precision value of a specified item.

Synopsis

void setDouble( String name, double value );

Usage

Sets the value of the item specified in the name parameter to the double precision value specified in the value parameter. The value is in 64-bits.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setFloat

Sets the floating point value of a specified item.

Synopsis

void setFloat( String name, float value );

Usage

Sets the value of the item specified in the name parameter to the floating point (32-bit) value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setInt

Sets the integer value of a specified item.

Synopsis

void setInt( String name, int value );

Usage

Sets the value of the item specified in the name parameter to the integer (32-bit) value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setShort

Sets the short integer value of a specified item.

Synopsis

void setShort( String name, short value );

Usage

Sets the value of the item specified in the name parameter to the short (16-bit) integer value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

setString

Sets the string value of a specified item.

Synopsis

void setString( String name, String value );

Usage

Sets the value of the item specified in the name parameter to the string value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

Occurs when the user tries to set a value to a get-only attribute, or to get a value from a set-only attribute.

java.lang.NoSuchFieldError.

Occurs when the user tries to set an attribute which is not one of the predefined attributes.

Attributes Names for Get and Set Methods

The attribute names for the JoltSessionAttributes class include static final variables (essentially predefined constants) for setting the application address, and for setting and getting timeouts. The predefined attribute names listed in Table 7-2 are used for specifying the String name parameter of the JoltSessionAttributes get and set methods.

Note: The get methods are unrestricted. That is, the programmer can define names in addition to using the predefined ones. The set methods are currently restricted to the use of the predefined names listed in Table 7-2.

Table 7-2 Predefined Attribute Names
Attribute Name Description

APPADDRESS

Defines the location of the machine where the application resides. The format is as follows:

String "//host:port"

Host is the host machine name or IP address and port is the TCP port number for the Jolt JSL or Jolt Relay. Use setString() to set the value of this attribute.

IDLETIMEOUT

Defines an integer representing the timeout interval in seconds. Set the IDLETIMEOUT to an interval of time that is less than the SESSIONTIMEOUT value.

IDLETIMEOUT is used to hint to the system when to drop the network connection while retaining the session. When the IDLETIMEOUT is set to 0, the system is notified that the network connection is always retained. This ensures that when the system times out, the network connection to the target system is terminated, and the session is terminated. The system administrator may override this parameter.

Use setIntDef() to set the value of this attribute.

RECVTIMEOUT

Defines the number of seconds to wait after Jolt issues the TCP/IP recv() before timing out. The default is 120 seconds. Use setInt() to set the value of this attribute.

SENDTIMEOUT

Defines the number of seconds to wait after Jolt issues the TCP/IP send() before timing out. The default is 10 seconds.

SESSIONTIMEOUT

SESSIONTIMEOUT is the only attribute used for the get...methods. This attribute is the integer value in minutes of the SESSIONTIMEOUT that is configured in the Jolt server. When a session has been idle for the specified time, the server terminates the session. See the -T option in JSL. Use setString() to set the value of this attribute.

Note: For more information about the JSL -T timeout refer to "*SERVERS Section."

JoltSession Class

 
java.lang.Object
   |
   +----bea.jolt.Session
           |
           +----bea.jolt.JoltSession

The JoltSession class represents the logon session object and is used to access available TUXEDO services. The GUI-based Jolt Repository handles the propagation of TUXEDO services to Jolt client applications. (For more information about the Jolt Repository, see Chapter 5, "Using the Jolt Repository Editor.") The programmer must instantiate an object for each logon session. The JoltSession object communicates data from, and connects to the TUXEDO System. The session ends with a call using the endSession() method.

The JoltSession object is passed, by reference, to the JoltRemoteService and JoltTransaction objects. All Jolt transactions must pass a JoltSession to access the TUXEDO application. 

public class JoltSession
{
  // JoltSession Constructor
  public JoltSession( JoltSessionAttributes attr, String 
  userName, String userRole, String userPassword, String 
  appPassword )	throws SessionException;
 
  // JoltSession Method
  public void endSession( )throws SessionException; 
  public final isAlive( );
  public void onReply ( JoltReply reply );
  protected void finalize( );
}

For more information see the following classes: JoltSessionAttributes, JoltRemoteService, JoltTransaction, JoltReply.

JoltSession Constructor

The JoltSession constructor creates a JoltSession object with attributes from the JoltSessionAttributes class. The JoltSession object is the logon to the target system which is identified in the APPADDRESS name of the JoltSessionAttributes. In addition, programmers can specify the IDLETIMEOUT value (in seconds) in JoltSessionAttributes to hint to the system when to drop the network connection while retaining the session. Value 0 means the network connection should be retained throughout the session. The administrator can override the behavior.

The programmer can set all other parameters for this constructor to null, depending upon the authentication level.

JoltSession

Creates an instance of the JoltSession class with the specified attributes.

Synopsis

JoltSession( JoltSessionAttributes attr, String userName,
String  userRole, String userPassword, String appPassword )
throws  SessionException;

Usage

The JoltSession class creates an instance of the JoltSession class with the specified attributes. Specific components are extracted to assist in joining an application and terminating a session.

JoltSession allows the user identified by the userName parameter to log on to the Jolt/TUXEDO system. All parameters must be set according to the authentication level. If the logon is not successful, a SessionException is thrown. The object is returned upon completion.

Throws

The JoltSession constructor throws the following exceptions: SessionException

TPEJOLT: Missing host name or missing port number.
TPEJOLT: Protocol Error
TPEJOLT: Network Error
TPEJOLT: Can't connect to (host name)

The JoltSession constructor throws the following TUXEDO errors: tpinit(3)

TPEINVAL, TPENOENT, TPEPERM, TPEPROTO, TPESYSTEM, TPEOS

Refer to "TUXEDO Errors" in Appendix A or tperrno(5) in the TUXEDO System Reference Manual for explanations of these error messages.

JoltSession Method

The JoltSession class contains one method, the endSession method, for handling session logoff activities, two additional methods, isAlive() and onReply() for handling event subscription, and the overridden finalize() method.

endSession

Performs a session termination procedure.

Synopsis

void endSession( ) throws SessionException;

Usage

The endSession method is used to terminate the session and obsolete the session object. The endSession method allows the user to log off the Jolt/TUXEDO system. When logged off, the session is invalid.

Throws

The endSession() method throws the following exceptions: SessionException

TPEJOLT: Invalid Session
TPEJOLT: Connection send error

The endSession() method generates a Jolt exception upon receipt of one of the following TUXEDO errors: tpterm():

TPEPROTO, TPESYSTEM, TPEOS

See Also

"TUXEDO Errors" in Appendix A or tperrno(5) in the TUXEDO System Reference Manual.

isAlive

Checks if the session is still alive.

Synopsis

boolean isAlive() throws SessionException

Usage

The isAlive method will return a Boolean (true/false) value indicating whether the client session is valid or not. The validity of the client session is checked at the Jolt Session Handler (JSH). If a client which is operating in connection-less mode calls isAlive() while its network connection is closed, this method will cause the network connection to be re-opened and closed.

Returns

True if this session is still alive; false otherwise.

Throws

The isAlive() method throws a SessionException.

onReply

Is the default event handler for all events.

Synopsis

void onReply( JoltReply reply )

Parameter

 reply

Specifies an object containing the data message.

Usage

This method is the default event handler for all events. This method is invoked by Jolt applications and it should be overridden by the user. Client application developers need to provide an implementation of the onReply() method to invoke when any notification is received. The JoltReply object that is passed to the onReply() method contains any data that is included with the notification. The application can use the methods in JoltReply and JoltMessage to retrieve this data.

Since Jolt is a multithreaded environment, the onReply() method executes on a separate thread simultaneously with other application threads. You must, therefore, write a thread-safe handler. Separate threads could be executing the onReply() method concurrently, so the method must be written to accommodate this possibility. Alternately, you can declare the onReply() method as synchronized-this will cause all its invocations to be serialized.

Overrides

The onReply method overrides another onReply() method.

finalize

Calls the endSession() method if an endSession() has never been called.

Synopsis

protected void finalize( )

Usage

This method is automatically called by the Java garbage collector.

Overrides

The finalize method overrides java.lang.Object.finalize().

JoltRemoteService Class

 
java.lang.Object
   |
   +----bea.jolt.JoltRequestMessage
           |
           +----bea.jolt.JoltRemoteService

The JoltRemoteService class is a subclass (child class) of the JoltRequestMessage class. It is derived from and inherits the characteristics of its parent class, JoltRequestMessage. The JoltRemoteService object is reusable; therefore, the programmer should invoke the JoltRequestMessage clear method to reset any previous data (such as flags, priority, and parameters) before invoking the object again.

JoltRemoteService is used to perform the Request/Reply call. To make a call, the programmer:

  1. Instantiates an object of this class for each service, using the add methods from JoltRequestMessage to add the parameters.

  2. Invokes the call method to send the request.

  3. Uses the JoltRequestMessage get methods, upon successful completion of the call, to retrieve the reply result.

The JoltRemoteService methods are described as part of the JoltRequestMessage class. Refer to the JoltRequest Message, JoltSession, and JoltTransaction classes for additional information. 

public class JoltRemoteService extends JoltRequestMessage
{
  public JoltRemoteService( String name, JoltSession s ) throws 
  ServiceException;

  // JoltRemoteService methods
  public void call( Transaction t )
  throws ServiceException,
  TransactionException, ApplicationException
}

JoltRemoteService Constructor

The following JoltRemoteService constructor is used to create instances of the JoltRemoteService class.

JoltRemoteService

Defines a constructor for a remote service object.

Synopsis

JoltRemoteService( String name, JoltSession s ) throws 
ServiceException;

Usage

JoltRemoteService defines the constructor for a remote service object. The name parameter specifies the service name. The s parameter specifies the session object from the JoltSession class. This constructor receives the most current version from a repository that holds the service definitions. If the service does not exist, an exception is thrown.

Throws

ServiceException

TPENOENT - Service (service name) is not available.
TPEJOLT - Invalid session
TPEJOLT - bea.jolt.DefinitionException: Invalid (message)

JoltRemoteService Methods

Provides the means to call a transaction service for the JoltRemoteService object.

call

The call method calls the specified service.

Synopsis

void call( Transaction t ) throws ApplicationException,
TransactionException, ServiceException;

Usage

The call method calls the service. The t parameter specifies the transaction object. The transaction must belong to the same session as the current service. If a TUXEDO error (not service failure) occurs, the call method throws a ServiceException.

You can pass a null to this call method to call services without defining a JoltTransaction object or to exclude the services from a transaction.

You can use a getErrno to retrieve the TUXEDO error code and error message from the ServiceException. If there is a service failure (i.e., TPESVCFAIL), the call method throws a runtime exception, ApplicationException.

When programming in multithreaded mode, if the transaction is aborted, all outstanding calls associated with such a transaction receive a TransactionException with a TPEABORT error code. The associated message contains the service name.

To call services without defining a JoltTransaction object or to exclude the services from a transaction, you can pass a null to the call method.

Throws

ApplicationException

(application code) - "this" object is included.

ServiceException

TPEJOLT: Invalid session
TPEJOLT: Connection send error
TPEJOLT: Connection recv error
TPEJOLT: Protocol error
TPEJOLT: bea.jolt.BufException:....
TPEJOLT: bea.jolt.MessageException:...

TransactionException

TPEJOLT - Invalid Transaction
TPEABORT - (service name)

The call() method generates an exception upon receipt of the following TUXEDO errors: tpcall

TPEINVAL, TPENOENT, TPEITYPE, TPETRAN,
TPETIME, TPESVCFAIL, TPESVCERR, TPEBLOCK,
TPGOTSIG, TPEPROTO, TPESYSTEM, TPEOS

See Also

"TUXEDO Errors" in Appendix A or tperrno in the TUXEDO System Reference Manual.

JoltRequestMessage Abstract Class

JoltRequestMessage is an abstract class whose main purpose is to serve as a base or parent class for JoltRemoteService. The JoltRemoteService class extends from (or is a subclass of) the JoltRequestMessage. All of the methods provided for the JoltRequestMessage class only work with the JoltRemoteService class.

Note: All JoltRequestMessage method exceptions are caught by the Java virtual machine by default. 

public abstract class JoltRequestMessage
{
  public String getName();
  public void setRequestPriority( int priority );
  public int  getApplicationCode();
  public void clear();
  public void addByte( String name, byte val );
  public void addShort( String name, short val );
  public void addInt( String name, int val );
  public void addFloat( String name, float val );
  public void addDouble( String name, double val );
  public void addString( String name, String val );
  public void addBytes( String name, byte[] val, int len );
  public void delete( String name );
  public void deleteItem( String name, int itemNo );
  public void setByte( String name, byte value );
  public void setShort( String name, short value );
  public void setInt( String name, int value );
  public void setFloat( String name, float value );
  public void setDouble( String name, double value );
  public void setString( String name, String value );
  public void setBytes( String name, byte[] value, int len );
  public void setByteItem( String name, int itemNo, byte val );
  public void setShortItem( String name, int itemNo, short val );
  public void setIntItem( String name, int itemNo, int val );
  public void setFloatItem( String name, int itemNo, float val );
  public void setDoubleItem( String name, int itemNo, double val );
  public void setStringItem( String name, int itemNo, String val );
  public void setBytesItem( String name, int itemNo, byte[] val, 
  int len);
  public int  getOccurrenceCount( String name );
  public byte getByteDef( String name, byte defValue );
  public short getShortDef( String name, short defValue );
  public int  getIntDef( String name, int defValue );
  public float getFloatDef( String name, float defValue );
  public double getDoubleDef( String name, double defValue );
  public String getStringDef( String name, String defValue );
  public byte[] getBytesDef( String name, byte[] defValue );
  public byte getByteItemDef( String name, int itemNo, byte def


 JoltRequestMessage Methods



The JoltRequestMessage methods are used in conjunction with the abstract JoltRequestMessage class. These methods are divided into five categories: the clear method, get methods, set methods, add methods, and delete methods.




Note:	
 The clear() method removes JoltRequestMessage settings.


 Get Methods



The get JoltRequestMessage methods are used to get values from the remote service object. These methods encompass two types of get methods: service and request methods, and output parameter methods.


Service and Request Methods. The service methods handle queries about service attributes such as the name of the current service, or the application code (i.e., tpusrcode in ATMI). These methods include:



Output Parameter Methods. All of the get methods are used to obtain the value of a named item that must be one of the result parameters. If the item does not exist, the method returns the specified default value. A get method without itemNo parameter is equivalent to a get method with itemNo 0 (i.e., first occurrence). These methods include the following:



The corresponding set methods for these get methods are located in the "setByte" section.


 Set Methods



The set methods are used to set values for the remote service object. These methods manipulate the input parameters. The set JoltRequestMessage methods are divided into two categories:


Service and Request Method. The service method sets the request priority service attribute, this includes:



Input Parameter Methods. These methods are used to set the value of a named item that must be one of the input parameters. If the named item does not exist, the value is added. These methods include the following:



For all of the set...Item methods, if an item exists, the set method will overwrite it. The parameter itemNo specifies an index that points to the value. If there are gaps in the index (that is, you set a value for itemNo 3 and there are no values set for itemNo 0, 1, and 2) these items will be set with:



In the following example, the setStringItem method is used to change the name John to Jim. The itemNo parameter specifies a list of names. Currently, the name John exists for itemNo 2. To change the name you might write:


setStringItem ("names", 2, "jim");



All indexes specified by itemNo start at 0 and increment. Therefore, the second item in a list is actually itemNo 1 and the first item in the list is actually itemNo 0.


 Add and Delete Methods



The add and delete methods are used to add or delete values for the remote service object. These methods manipulate the input parameters. These methods include:

clear

Resets all input/output parameters or any information.

Synopsis

void clear();

Usage

The clear() method handles removal of parameter settings or information set by the JoltRequestMessage class.

getApplicationCode

Gets the application code returned by the service.

Synopsis

int getApplicationCode();

Usage

The getApplicationCode() method is equivalent to tpurcode or the rcode in the TUXEDO tpreturn(3).

Returns

This method returns an integer value (32-bit).

getName

Gets the name of the current service.

Synopsis

String getName();

Returns

This method returns a string value.

getOccurrenceCount

Gets the number of occurrences of a specified item.

Synopsis

int getOccurrenceCount( String name );

Usage

This method retrieves the number of occurrences of an item specified by the name parameter. The item must be one of the result or output parameters.

Returns

This method returns an integer value (32-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getByteDef

Gets the byte value of a specified parameter.

Synopsis

byte getByteDef( String name, byte defValue );

Usage

This method gets the byte value of the name parameter or the specified defValue, if the name does not exist. The item must be one of the result or output parameters.

Returns

This method returns a byte value (8-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getBytesDef

Gets the byte array value of a specified parameter.

Synopsis

byte[ ] getBytesDef( String name, byte[] defValue );

Usage

This method gets the byte array value of the first item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns an array of byte values.

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getDoubleDef

Gets the double precision value of a specified parameter.

Synopsis

double getDoubleDef( String name, double defValue );

Usage

This method gets the double precision value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a double precision value (64-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getFloatDef

Gets the floating point value of a specified parameter.

Synopsis

float getFloatDef( String name, float defValue );

Usage

This method gets the floating point value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a floating point value (32-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getIntDef

Gets the integer value of a specified parameter.

Synopsis

int getIntDef( String name, int defValue );

Usage

This method gets the integer value of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns an integer value (32-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getShortDef

Gets the short integer value of a specified parameter.

Synopsis

short getShortDef( String name, short defValue );

Usage

This method gets the short integer value (16-bit) of the item specified in the name parameter or the specified defValue, if the name does not exist.

Returns

This method returns a short integer value (16-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getStringDef

The getStringDef() method gets the string value of a specified parameter.

Synopsis

String getStringDef( String name, String defValue );

Usage

This method gets the string value of the item specified in the name parameter or the specified defValue, if the name does not exist. The default value can be a null string or any string that you specify.

Returns

This method returns a string value.

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getByteItemDef

Gets the byte item.

Synopsis

byte getByteItemDef( String name, int itemNo, byte def );

Usage

This method gets the byte value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns a byte value (8-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getBytesItemsDef

Gets the byte array item.

Synopsis

byte[] getBytesItemDef( String name, int itemNo, byte[] def );

Usage

This method gets the byte value of the itemNo of the name parameter. If the item does not exist, the get method uses the default value.

Returns

This method returns a byte value (8-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getDoubleItemDef

Gets the double precision item.

Synopsis

double getDoubleItemDef( String name, int itemNo, double def );

Usage

This method gets the double precision value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns a double precision value (64-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getFloatItemDef

Gets the floating point item.

Synopsis

float getFloatItemDef( String name, int itemNo, float def );

Usage

This method gets the floating point value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns a floating point value (32-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getIntItemDef

Gets the integer item.

Synopsis

int getIntItemDef( String name, int itemNo, int def );

Usage

This method gets the integer value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns an integer value (32-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getShortItemDef

Gets the short item.

Synopsis

short getShortItemDef( String name, int itemNo, short def );

Usage

This method gets the short value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns a short integer value (16-bit).

Throws

java.lang.NoSuchFieldError.

(field name) Attempt to get a field that is not defined for this service.

getStringItemDef

Gets the string value of a specified item.

Synopsis

String getStringItemDef( String name, int itemNo, String def );

Usage

This method gets the string value of the itemNo of the name parameter. If the item does not exist, the get method returns the default value.

Returns

This method returns a string value.

Throws

java.lang.NoSuchFieldError. (field name) Attempt to get a field that is not defined for this service.

setRequestPriority

Sets the request priority service attribute.

Synopsis

void setRequestPriority( int priority );

Parameter

 priority

Specify a priority value between 1 and 100 inclusive.

Usage

Sets the absolute request priority for the current service. It is set until clear() is called.

setByte

Sets the value of the specified item.

Synopsis

void setByte( String name, byte value );

Usage

Sets the value of the item specified in the name parameter to the byte value specified in the value parameter. The value is an 8-bit byte.

Throws

java.lang.IllegalAccessError.

(field name) - Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) - Attempt to set a field which is not defined for this service.

setBytes

Sets the value of the specified item.

Synopsis

void setBytes( String name, byte[ ] value, int len );

Usage

Sets the value of the item specified in the name parameter to the byte array value specified in the value parameter, with the length set by the len parameter. The value is in 8-bit bytes.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setDouble

Sets the double precision value of the specified item.

Synopsis

void setDouble( String name, double value );

Usage

Sets the value of the item specified in the name parameter to the double precision (64-bit) value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) - Attempt to set a field which is not defined for this service.

setFloat

Sets the floating point value of the specified item.

Synopsis

void setFloat( String name, float value );

Usage

Sets the value of the item specified in the name parameter to the floating point (32-bit) value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

(field name) - Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) - Attempt to set a field which is not defined for this service.

setInt

Sets the integer value of the specified item.

Synopsis

void setInt( String name, int value );

Usage

Sets the value of the item specified in the name parameter to the integer (32-bit) value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setShort

Sets the short integer value of the specified item.

Synopsis

void setShort( String name, short value );

Usage

Sets the value of the item specified in the name parameter to the short (16-bit) integer value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setString

Sets the string value of the specified item.

Synopsis

void setString( String name, String value );

Usage

Sets the value of the item specified in the name parameter to the string value specified in the value parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setByteItem

Sets a named item at a specified index with a byte value.

Synopsis

void setByteItem( String name, int itemNo, byte value );

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the byte value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setBytesItem

Sets a named item at a specified index with a byte value.

Synopsis

void setBytesItem( String name, int itemNo, byte[] value, int len );

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the byte array value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setDoubleItem

Sets a named item at a specified index with a double precision value.

Synopsis

void setDoubleItem( String name, int itemNo, double value );

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the double precision value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setFloatItem

Sets a named item at a specified index with a floating point value.

Synopsis

void setFloatItem( String name, int itemNo, float value);

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the floating point value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setIntItem

Sets a named item at a specified index with a integer value.

Synopsis

void setIntItem( String name, int itemNo, int value);

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the integer value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setShortItem

Sets a named item at a specified index with a short integer value.

Synopsis

void setShortItem( String name, int itemNo, short value );

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the short value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

setStringItem

Sets a named item at a specified index with a string value.

Synopsis

void setStringItem( String name, int itemNo, string value );

Usage

Sets the item specified in the name parameter at the index specified by itemNo with the string value specified by the value parameter. If the item already exists, the value is overwritten.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to set a value to an output parameter field.

java.lang.NoSuchFieldException.

(field name) Attempt to set a field which is not defined for this service.

addByte

Adds the byte input parameters.

Synopsis

void addByte( String name, byte val );

Usage

The addByte() method adds specified byte items to the input parameters.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addBytes

Adds the byte array input parameter.

Synopsis

void addBytes( String name, byte[] val, int len );

Usage

The addBytes() method adds the byte value (8-bit) of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addDouble

Adds the double precision input parameter.

Synopsis

void addDouble( String name, double val );

Usage

The addDouble() method adds the double precision value (64-bit) of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addFloat

Adds the floating point input parameter.

Synopsis

void addFloat( String name, float val );

Usage

The addFloat() method adds the floating point value (32-bit) of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addInt

Adds the integer input parameter.

Synopsis

void addInt( String name, int val );

Usage

The addInt() method adds the integer value (32-bit) of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addShort

Adds the short integer value (16-bit) input parameter.

Synopsis

void addShort( String name, short val );

Usage

This method adds the short integer value (16-bit) of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

addString

Adds the string value input parameter.

Synopsis

void addString( String name, String val );

Usage

This method adds the string value of the item specified in the name parameter.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

delete

Deletes a first occurrence of the named item or any existing item.

Synopsis

void delete( String name );

Usage

This method deletes the first named item. The named item must be one of the input parameters.

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

deleteItem

Deletes an occurrence of an existing named item.

Synopsis

void deleteItem( String name, int itemNo );

Usage

This method deletes an existing named item (input parameter). If the item does not exist, an exception will be thrown. The deleteItem method without the itemNo parameter is equivalent to delete methods with itemNo 0 (i.e., first occurrence).

Throws

java.lang.IllegalAccessError.

(field name) Attempt to add a value to an input parameter field, or delete a value from an input parameter field.

java.lang.NoSuchFieldError.

(field name) Attempt to add or delete a field that is not defined for this service.

JoltTransaction Class

 
java.lang.Object
   |
   +----bea.jolt.Transaction
           |
           +----bea.jolt.JoltTransaction

The JoltTransaction class is the explicit transaction model for Jolt. The JoltTransaction class implements the transaction object. This object can be used by JoltRemoteService to include several services into a single transaction. When a transaction is timed out, the user must rollback the transaction immediately. Due to the current implementation of TUXEDO, only one transaction object can be instantiated at one time.

Refer also to the JoltRemoteService and JoltSession classes. 

public class JoltTransaction
{
  public JoltTransaction( int timeout, JoltSession s) throws 
  TransactionException;
  public void commit() throws TransactionException;
  public void rollback() throws TransactionException;
}

JoltTransaction Constructor

The JoltTransaction class provides a constructor to create the JoltTransaction object.

JoltTransaction

Creates an instance of the JoltTransaction object with the specified parameters.

Note: You can pass a null to the JoltRemoteService call() method to call services without defining a JoltTransaction object or to exclude the services from a transaction.

Synopsis

public JoltTransaction( int timeout, JoltSession s) throws TransactionException;

Usage

The constructor (or the method that is invoked automatically when a new instance of a class is created) implies the beginning of the transaction. The s (session) parameter in the constructor ensures that the transaction does not span over multiple sessions. The current Jolt release allows only one transaction per session.

JoltTransaction requires that you set the timeout for a transaction. Specifying a timeout parameter of zero, sets the timeout to the maximum value for the system. If the transaction is not completed within this period of time (the time between the tpbegin() and the tpcommit()), then Jolt generates a TransactionException.

The RECVTIMEOUT for each transactional JoltRemoteService.call() is automatically adjusted to the proper timeout value.

Throws

TransactionException

TPEJOLT: Invalid session
TPEJOLT: Connection send error
TPEJOLT: Connection recv error
TPEJOLT: Protocol error

The JoltTransaction constructor generates an exception upon receipt of the following TUXEDO errors: tpbegin

TPEINVAL, TPETRAN, TPEPROTO, TPESYSTEM, TPEOS

See Also

"TUXEDO Errors" in Appendix A or tperrno(5) in the TUXEDO System Reference Manual.

JoltTransaction Methods

The JoltTransaction methods provide the means to start or end a transaction process. The following methods handle commit and rollback transaction processing for the JoltTransaction class.

commit

Performs the transaction commit.

Synopsis

void  commit()

Usage

After commit() is called, the object is obsolete.

Throws

TransactionException

TPEJOLT: Invalid transaction
TPEJOLT: Connection send error
TPEJOLT: Connection recv error
TPEJOLT: Protocol error
TPEABORT: Requests pending

The commit() method generates an exception upon receipt of the following TUXEDO errors: tpcommit(3)

TPEINVAL, TPETIME, TPEABORT, TPEHEURISTIC, TPEHAZARD, TPEPROTO, TPESYSTEM, TPEOS

rollback

Aborts the transaction.

Synopsis

void  rollback()

Usage

After rollback() is called, the object is obsolete.

Throws

TransactionException

TPEJOLT: Invalid transaction
TPEJOLT: Connection send error
TPEJOLT: Connection recv error
TPEJOLT: Protocol error

The rollback() method generates an exception upon receipt of the following TUXEDO errors: tpabort(3)

TPEINVAL, TPEHEURISTIC, TPEHAZARD, TPEOS, TPEPROTO, TPESYSTEM

See Also

"TUXEDO Errors" in Appendix A or tperrno(5) in the TUXEDO System Reference Manual.

JoltEvent Class 

java.lang.Object
  |
  +----bea.jolt.JoltEvent

The JoltEvent class extends the java.lang.Object class and is a base class for various event subscriptions. This class is not designed to be instantiated directly. The JoltEvent class provides some common implementations for all subscriptions. An event can be a notification event or service event. A notifiable event generates an event subscription while a service event invokes a service.

For additional information, refer also to the JoltSession class. 

public class JoltEvent
  unsubscribe()
  unsubscribeAll(Session)

JoltEvent Methods

The following methods are used with the JoltEvent class.

unsubscribe

Deletes the subscription to an event.

Synopsis

public int unsubscribe()

Usage

This method is used to stop subscribing to the event specified in the constructor. Once it is unsubscribed, this object becomes obsoleted. All notifications received as a result of a subscription will cause the onReply() method in the session to be invoked.

Returns

Number of subscriptions deleted.

Throws

EventException.

No such event or invalid event.

SessionException.

An error occurs in this session.

unsubscribeAll

Unsubscribes all event subscriptions in the specified session.

Synopsis

public static int unsubscribeAll(Session session)

Usage

Unsubscribe all event subscriptions in the specified session. The session parameter requires a Jolt session object.

Returns

Number of subscriptions deleted.

Throws

EventException.

Unsubscription error from TUXEDO.

SessionException.

Invalid session or a session error.

JoltUserEvent Class 

java.lang.Object
  |
  +----bea.jolt.JoltEvent
          |
          +----bea.jolt.JoltUserEvent

The JoltUserEvent class extends JoltEvent. JoltUserEvent implements a subscription to an asynchronous (async) notification event. An async notification is either an unsolicited event notification or event notification from the TUXEDO Event Broker. Unsolicited notifications are produced in response to a TUXEDO tpnotify() call or a TUXEDO tpbroadcast() call. Event notifications are produced as a result of a TUXEDO tppost() call.

The JoltUserEvent class is used in Jolt 1.1 to support notification. This class provides support for both unsolicited notification (produced as a result of tpnotify() or tpbroadcast()) and event notifications (produced as a result of tppost()).

The String JoltUserEvent.UNSOLMSG in the class is a constant which the application programmer uses to request unsolicited messages.

Note: In TUXEDO, an unsolicited notification is indistinguishable from event notification. This is also reflected in Jolt.

The handler for unsolicited notification and event notification is done in the Session object. A thread is used in this class to monitor any incoming messages.

For additional information, refer also to the JoltSession, JoltMessage, and JoltReply classes. 

public class JoltUserEvent
  UNSOLMSG 
JoltUserEvent(String, String, Session)

UNSOLMSG

The regular expression constant for unsolicited notification subscription.

Synopsis

final static String UNSOLMSG

JoltUserEvent Methods

The following methods are used with the JoltUserEvent class.

JoltUserEvent

Subscribes to the specific asynchronous notification.

Synopsis

JoltUserEvent(String expr, String filter, Session session)
                       throws EventException, SessionException

Parameters

 expr

JoltUserEvent.UNSOLMSG for unsolicited notification or a regular expression for event notification. The parameter expr is a string containing a regular expression of the same format as the event expression used in tpsubscribe(). The maximum length of this parameter is 255 characters. Setting this parameter to the constant JoltUserEvent.UNSOLMSG will allow the client to receive unsolicited messages (generated as a result of tpnotify() or tpbroadcast()).

filter

Null or Boolean expression. The parameter filter is a string of the same format as the filter parameter passed to tpsubscribe(). The maximum length of this parameter is 255 characters. Filter rules are specific to the buffers to which they are applied. Refer to TUXEDO documentation for complete explanation of the filtering function. Filtering is done on the TUXEDO server, not the Jolt client.

session

A JoltSession object. The parameter session is the JoltSession to which the subscription is bound. An event is bound to a single session.

Usage

This constructor subscribes the specific asynchronous notification. An asynchronous notification may be an unsolicited notification or event notification. If the expr is JoltUserEvent.UNSOLMSG, the filter must be null. Otherwise, the filter can be either null or a Boolean expression (see Fboolco(3) in the TUXEDO System Reference Manual).

This constructor will return a JoltUserEvent object, which will provide notification when the event identified by the parameter event occurs.

Throws

SessionException.

Invalid session or a session error.

EventException.

Filter for unsolicited subscription is not null, or event subscription failed.

JoltReply Class 

java.lang.Object
  |
  +----bea.jolt.JoltReply

The JoltReply class extends the java.lang.Object. JoltReply is a place holder of the message for unsolicited messages or event notifications. This class provides the application with access to any message received with a TUXEDO event or notification. 

public class JoltReply
    Message getMessage()

JoltReply Methods

The following method is used with the JoltReply class.

getMessage

Gets the response message.

Synopsis

Message getMessage()

Usage

The getMessage() method returns a JoltMessage object. The returned object provides the application with access to any data that is associated with the event or notification.

Returns

The getMessage() method returns a message object.

JoltMessage Class 

java.lang.Object
  |
  +----bea.jolt.Message
          |
          +----bea.jolt.JoltMessage

The JoltMessage class extends java.lang.Object. This class implements the Message class, which encapsulates the attribute-value pair data for the application protocol. This class allows the user to get an output attribute to the message. For more information, refer also to the JoltReply classes. 

public class JoltMessage
//These methods are duplicates of the JoltRequestMessage class
//They are inherited from that class. 
  public int getOccurrenceCount(String name);
  public byte getByteDef(String name, byte def); 
  public short getShortDef(String name, short def); 
  public int getIntDef(String name, int def); 
  public float getFloatDef(String name, float def);
  public double getDoubleDef(String name, double def); 
  public String getStringDef(String name,String def); 
  public byte[] getBytesDef(String name, byte def[]); 
  public byte getByteItemDef(String name, int itemNo, byte def); 
  public short getShortItemDef(String name, int itemNo, short def);
  public int getIntItemDef(String name, int itemNo, int def); 
  public float getFloatItemDef(String name, int itemNo, float def); 
  public double getDoubleItemDef(String name, int itemNo, double
  def); 
  public byte[] getBytesItemDef(String name, int itemNo, byte
  def[]); 
  public String getStringItemDef(String name, int itemNo, String
  def);

JoltMessage Methods

The following methods are used with the JoltMessage class.

getOccurrenceCount

Gets the number of occurrence of a named item.

Synopsis

synchronized int getOccurrenceCount(String name)

Parameters

 name

Specifies the name of the item.

Throws

NoSuchFieldError.

It is an invalid name.

getByteDef

Gets the first item based on its name.

Synopsis

public byte getByteDef(String name, byte def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default byte value.

Usage

Get the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError.

It is an invalid name.

getShortDef

Gets the first item based on its name.

Synopsis

short getShortDef(String name, short def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default short value.

Usage

Get the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError. It is an invalid name.

IllegalAccessError.

Cannot delete an input item.

getIntDef

Gets the first item based on its name.

Synopsis

int getIntDef(String name, int def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default int value.

Usage

Get the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError. It is an invalid name.

IllegalAccessError.

Cannot delete an input item.

getFloatDef

Gets the first item based on its name.

Synopsis

float getFloatDef(String name, float def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default float value.

Usage

Get the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError. It is an invalid name.

getDoubleDef

Gets the first item based on its specified name.

Synopsis

double getDoubleDef(String name, double def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default double value.

Usage

Get the first item based on its specified name. If it does not exist, the default value is returned.

Throws

NoSuchFieldError. It is an invalid name.

getStringDef

Gets the first item based on its name.

Synopsis

String getStringDef(String name,String def)

Parameters

 name

Specifies the name of the item.

def

Specifies the default string value.

Usage

Gets the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError. It is an invalid name.

getBytesDef

Gets the first item based on its name.

Synopsis

byte[] getBytesDef(String name, byte def[])

Parameters

 name

Specifies the name of the item.

def

Specifies the default byte-array value.

Usage

Get the first item based on its name. If it does not exist, the default value will be returned.

Throws

NoSuchFieldError. It is an invalid name.

getByteItemDef

Gets an occurrence of a named item of byte data type.

Synopsis

byte getByteItemDef(String name, int itemNo, byte def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A byte value.

Throws

NoSuchFieldError. It is an invalid name.

getShortItemDef

Gets an occurrence of a named item of short data type.

Synopsis

short getShortItemDef(String name, int itemNo, short def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A short value.

Throws

NoSuchFieldError. It is an invalid name.

getIntItemDef

Gets an occurrence of a named item of int data type.

Synopsis

int getIntItemDef(String name, int itemNo, int def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

An integer value.

Throws

NoSuchFieldError. It is an invalid name.

getFloatItemDef

Gets an occurrence of a named item of float data type.

Synopsis

float getFloatItemDef(String name, int itemNo, float def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A floating point value.

Throws

NoSuchFieldError. It is an invalid name.

getDoubleItemDef

Gets an occurrence of a named item of double data type.

Synopsis

double getDoubleItemDef(String name, int itemNo, double def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A double precision value.

Throws

NoSuchFieldError. It is an invalid name.

getBytesItemDef

Gets an occurrence of a named item of byte-array data type.

Synopsis

byte[] getBytesItemDef(String name, int itemNo, byte def[])

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A byte-array object.

Throws

NoSuchFieldError. It is an invalid name.

getStringItemDef

Gets an occurrence of a named item of string data type.

Synopsis

String getStringItemDef(String name, int itemNo, String def)

Parameters

 name

Specifies the name of the item.

itemNo

Specifies the occurrence number of the item.

def

Specifies the default value.

Usage

The occurrence starts from 0. If it does not exist, the default value will be returned.

Returns

A string value.

Throws

NoSuchFieldError. It is an invalid name.