WebT API

This chapter describes the classes that are required for WebT to connect to a Tmax server to call a service, and also explains fields and methods that can be used in each class.

1. Overview

The following tables contain classes needed for WebT to connect to a Tmax server and to call a service. For details about each class, refer to each relevant section.

  • Classes related to connections:

    Class Description

    WebtConnection

    Connects a Tmax server to WebT.

    WebtConnectionPool

    Manages WebtConnection objects.

    WebtConnectionGroup

    Pools connections in a connection pool.

  • Classes related to service call data:

    Class Description

    WebtAttribute

    Contains information about flags used to call the TP functions of a WebtRemoteService to a Tmax server.

    WebtBuffer

    Manages user data that is exchanged between WebT and a Tmax server.

    WebtCarrayBuffer

    Inherits WebtBuffer. This class has the CARRAY type data.

    WebtStringBuffer

    Inherits WebtBuffer. This class has the STRING type data.

  • Classes related to service call

    Class Description

    WebtRemoteService

    Provides an API by using a WebtConnection class and its children classes, and manages attributes and service names required to call Tmax services.

    WebtRQService

    Inherits WebtRemoteService. This class is used to utilize services that manage a RQ.

    WebtDialogueService

    Inherits WebtRemoteService. This class provides interactive services.

  • Classes related to field data

    Class Description

    WebtFieldElement

    This interface contains field data for field keys of WebtField.

    WebtFDLKeyTable

    Manages field keys when the buffer type used to call a Tmax service is WebtBuffer.BT_FIELD.

    WebtFieldSet

    This utility class helps use elements of field data more conveniently when the buffer type used for Tmax services is WebtBuffer.BT_FIELD.

    WebtField

    This abstract class manages data (WebtFieldElement) that corresponds to the field keys and the field key values used by a field type buffer.

    WebtFieldBuffer

    A child class of WebtBuffer. The class is a WebtBuffer object containing WebtField type data.

  • Classes related to event message handling

    Class Description

    WebtEventConnecion

    Handles event messages transmitted from a Tmax server or other clients.

    WebtEventHandler

    This interface is used to process unsolicited messages received by a Tmax server.

  • Other classes

    Class Description

    WebtTransaction

    Provides APIs to process multiple services as a single work unit, and handles exceptions.

    WebtSystem

    Manages information about WebT system versions, character sets, and field key tables.

2. Connection Classes

2.1. WebtConnection

Connects a Tmax server to WebT. In order to use the services provided by a Tmax server, it is necessary to use WebtConnection for network connections, and then request a service. The WebtConnection class sets and manages the information needed to connect to a Tmax server.

Constructor

The WebtConnection constructor creates a connection that accesses the port set in the hostPort parameter of Tmax. The IP address of the Tmax server is set in the hostAddr parameter.

The following describes WebtConnection class constructors:

  • Constructor 1

    • Prototype

      WebtConnection(String hostAddr,
                     int hostPort,
                     [boolean doConnect,]
                     [int conntimeout])
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the Tmax server to connect to.

      hostPort

      The port number on the Tmax server.

      doConnect

      An option used to connect to a Tmax server.

      • TRUE : Attempts to connect.

      • FALSE : Does not attempt to connect.

      conntimeout

      A timeout value to connect to a Tmax server (unit: seconds).

      If the connection is not established within a specified period of time, an exception (tperrno = TPETIME) will be thrown.

  • Constructor 2

    • Prototype

      WebtConnection(String hostAddr,
                     int hostPort,
                     String backupAddr,
                     int backupPort,
                     [boolean doConnect,]
                     [int conntimeout])
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the Tmax server to connect to.

      hostPort

      The port number on the Tmax server.

      backupAddr

      The IP address of a backup server to connect to if the connection with hostAddr:hostPort fails.

      backupPort

      The port number on a backup server to connect to if the connection with hostAddr:hostPort fails.

      doConnect

      An option used to connect to a Tmax server.

      • TRUE : Attempts to connect.

      • FALSE : Does not attempt to connect.

      conntimeout

      A timeout value to connect to a Tmax server (unit: seconds).

      If the connection is not established within a specified period of time, an exception (tperrno = TPETIME) will be thrown.

  • Constructor 3

    • Prototype

      WebtConnection(String hostAddr,
                     int hostPort,
                     String username,
                     String userpwd,
                     String domainname,
                     String domainpwd)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the Tmax server to connect to.

      hostPort

      The port number on the Tmax server.

      username

      A user name for user security authentication.

      usernpwd

      A password for user security authentication.

      domainname

      A domain name for domain security authentication.

      domainpwd

      A password for domain security authentication.

  • Exception

    Exception Description

    WebtIOException

    A network error occurred while initializing a connection, or connection is not established within a set timeout value.

    WebtServiceException

    An error related to the service itself, excluding network I/O and transaction-related service errors.

Method

The following is a list of methods for a WebtConnection class:

  • boolean checkConnection(int timeout)

    • Checks the connection state of a client.

    • Parameter

      Parameter Description

      timeout

      Checks whether a connection to the client is established within the specified timeout period. If the timeout value is not a positive number, the default of 20 seconds is applied. (Unit: seconds)

  • boolean close()

    • Closes the socket connection to Tmax. If the connection is managed by the connection pool, the connection can be returned to the pool without being disconnected to be used again.

  • void connect()

    • Attempts to connect to Tmax.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred while initializing a connection, or connection is not established within a set timeout value.

      WebtServiceException

      An error related to the service itself, excluding network I/O and transaction-related service errors.

  • String getAddress()

    • Returns the address of the main Tmax server.

  • int getBackupPort()

    • Returns the port number of the main Tmax server.

  • String getBackupAddress()

    • Returns the address of a backup Tmax server.

  • String getConnectionId()

    • Returns the ID of a connection.

  • String getCurrentHostAddress()

    • Returns the IP address of the current Tmax server.

  • int getCurrentHostPortNo()

    • Returns the port number of the current Tmax server.

  • String getDomainName()

    • Returns the name of a client connected to a main Tmax server.

  • String getGroupName()

    • Returns the name of a connection group that contains a connection.

  • int getPort()

    • Returns the port number of the main Tmax server.

  • int getTPtimeout()

    • Returns a specified blocking timeout value in seconds.

  • WebtTransaction getTransaction()

    • Returns the WebtTransaction object that a connection is currently using.

  • int getTxBlocktimeout()

    • Returns the timeout value of the Commit and Rollback parameters of a current transaction.

  • getUserName()

    • Returns an account name for user security authentication of a main Tmax server.

  • boolean isAlive()

    • Checks whether a connection is active.

  • void setTPtimeout(int sec)

    • Specifies a blocking timeout value in seconds.

  • void setTxBlocktimeout(int txBlockTimeout)

    • Specifies a timeout value for the Commit and Rollback parameters of transactions. (unit: seconds)

  • void setTxtimeout(int txTimeout)

    • Specifies a timeout value of a transaction. (unit: seconds)

  • void startReader()

    • Starts a message processing thread through a connection.

  • void stopReader()

    • Terminates a message processing thread through a connection.

Example

The following example describes how to create a connection with a WebtConnection object and to get a service. For more information, refer to WebtRemoteService.

...
WebtConnection conn = new WebtConnection("61.77.153.1",8888);
WebtRemoteService svc = new WebtRemoteService("TOUPPER",conn);
...
conn.close()

2.2. WebtConnectionPool

A WebtConnectionPool manages WebtConnection objects, which are network connections to the Tmax server. By using the WebtConnectionPool class, it is not necessary to create a new WebtConnection object whenever a Tmax service is requested, and a WebtConnection object that was previously used can be reused. By utilizing a WebtConnectionPool, the necessary resources and time required to create or close a network connection to the Tmax server can be reduced.

A WebtConnectionPool has the following features:

  • Manages a connection pool that connects to multiple Tmax servers.

  • Monitors a connection pool to close connections that have been idle for a certain time period, or to search for disconnected connections to reuse.

createGroup

Creates a WebtConnectionGroup class object.

The following describes WebtConnectionGroup creation methods:

  • Creation method 1

    • Prototype

      public static void createGroup(String groupname,
                                     String hostAddr,
                                     int hostPort,
                                     [String username,]
                                     [String userpwd,]
                                     [String domainname,]
                                     [String domainpwd,]
                                     int init,
                                     int max,
                                     int inc)
    • Parameter

      Parameter Description

      groupname

      A connection group name. If there is another connection group with the same name, a new connection group will not be created.

      hostAddr

      The host name of a Tmax server to connect.

      hostPort

      The port number on the Tmax server.

      username

      A name for user security authentication.

      userpwd

      A password for user security authentication.

      domainname

      A domain name for domain security authentication

      domainpwd

      A password for domain security authentication.

      init

      The number of initial connections.

      max

      The maximum allowable number of connections.

      inc

      The number of connections to be created when no connection is available.

  • Creation method 2

    • Prototype

      public static void createGroup(String groupname,
                                     String hostAddr,
                                     int hostPort,
                                     String backupAddr,
                                     int backupPort,
                                     [String username,]
                                     [String userpwd,]
                                     [String domainname,]
                                     [String domainpwd,]
                                     int init,
                                     int max,
                                     int inc,
                                     [int idle])
    • Parameter

      Parameter Description

      groupname

      A connection group name. If another connection group with the same name already exists, a new one will not be created.

      hostAddr

      The host name of the Tmax server to connect to.

      hostPort

      The port number on the Tmax server.

      backupAddr

      The host name of a backup Tmax server to connect to.

      backupPort

      The port number on a backup Tmax server.

      username

      A user name for user security authentication.

      userpwd

      A password for user security authentication.

      domainname

      A domain name for domain security authentication.

      domainpwd

      A password for domain security authentication.

      init

      The number of initial connections.

      max

      The maximum allowable number of connections.

      inc

      The number of connections to be created when no connection is available.

      idle

      The maximum idle time allowed for a connection. (unit: seconds)

      Used for a WebtConnectionPoolMonitor to check the idle time.

  • Exception

    Exception Description

    WebtIOException

    Failed to create a connection in a connection group.

    WebtServiceException

    The groupName parameter of a createGroup method of a connection pool is NULL.

    WebtException

    Exceptions that might occur while using WebT. All exception situations, excluding WebtIOException and WebtServiceException, are included in WebtException.

Method
  • public static void destroy()

    • Deletes all connection groups.

  • public static void destroyGroup(String name)

    • Removes a connection group that has the same group name as a name parameter. All connections in the connection group will be closed. The index number of a connection group that is larger than that of a removed connection group will be reduced by 1.

    • Parameter

      Parameter Description

      name

      A connection group name.

  • public static void endWait()

    • Keeps a connection.

  • public static WebtConnection getConnection(String groupname)

    • Returns the connections in a connection group that have the same group name as the groupname parameter. If the connection is not obtained within a specified timeout period, a WebtException will occur.

    • Parameter

      Parameter Description

      groupname

      A connection group name.

    • Exception

      Exception Description

      WebtIOException

      No connection is available or enabled in a connection group.

      WebtServiceException

      The connection group name is NULL or exceeds the timeout value.

  • public static WebtConnection getConnection(String groupname, long timeout_mili)

    • Returns connections in the connection group that has the same name with the groupname parameter. If failed to get a connection within the timeout period specified at timeout_mili, WebtException will occur.

    • Parameter

      Parameter Description

      groupname

      A connection group name.

      timeout_mili

      A timeout value to get a connection. (unit: milliseconds)

    • Exception

      Exception Description

      WebtIOException

      No connection is available or enabled in a connection group.

      WebtServiceException

      The connection group name is NULL or exceeds a set timeout value.

  • public static WebtConnectionGroup getGroup(String groupname)

    • Returns a connection group that has the same name as the groupname parameter. If there is no matched connection group, NULL is returned.

    • Parameter

      Parameter Description

      groupname

      A connection group name.

  • public static void startMonitor(int interval, boolean checkAlive, boolean failback)

    • Creates a thread to monitor a connection pool. If both checkAlive and checkIdle are set to FALSE, no thread will be created.

    • Parameter

      Parameter Description

      interval

      An interval value for monitoring. The default value is 5. (unit: seconds)

      checkAlive

      Checks whether a connection is alive. If disconnected, attempts to reconnect will be made.

      failback

      If set to true, the main server is monitored and restored automatically after a failure.

  • public static void stopMonitor()

    • Stops monitoring a connection pool, and terminates the monitoring thread.

Example

The following example shows the initialization of a connection pool using the createGroup method in order for the following two Tmax servers to provide a connection pool. The connection pool obtains a connection by using a groupname, which is the first parameter of the createGroup method.

...
WebtConnectionPool.createGroup("tmax1", "192.168.128.1", 8888,2,10,2);
WebtConnectionPool.createGroup("tmax2", "192.168.128.2", 8888,1,10,2);
...

In the following example, a WebtConnection is obtained from the initialized connection pool.

try {
     // tmax1 group (Get a WebtConnection object from 192.168.128.1:8888)
     WebtConnection con = WebtConnectionPool.getConnection(**"tmax1"**);
} catch (WebtIOException wioe) {
     System.out.println("fail to get WebtConnection of tmax1");
     return;
}
WebtRemoteService service = new WebtRemoteService("MYSVC", con);
...

// Return the WebtConnection object
WebtConnectionPool.putConnection(con);

2.3. WebtConnectionGroup

This abstract class manages a connection pool that contains multiple connections that have the same IP addresses and port numbers.

Constructor

User cannot directly create a WebtConnectionGroup object, but must use the createGroup creation method. For information about creating a WebtConnectionGroup object, refer to the description of createGroup in WebtConnectionPool.

Method

The following is a list of methods in the WebtConnectionGroup class:

  • int available()

    • Returns the number of currently remaining connections in a connection pool.

  • void destroy()

    • Deletes the current connection pool.

  • WebtConnection getConnection()

    • Waits to get a connection for a specified timeout period, and then returns an obtained connection. (Default value: 20 seconds)

    • Exception

      Exception Description

      WebtException

      The connection pool is disabled, or connection is not obtained within the specified time period.

  • WebtConnection getConnection(long timeout)

    • Waits to get a connection for the specified timeout period, and then returns an obtained connection. (Default value: 20 seconds)

    • Parameter

      Parameter Description

      timeout

      Timeout period for waiting for a connection. (unit: milliseconds)

    • Exception

      Exception Description

      WebtException

      The connection pool is disabled, or connection is not obtained within the specified time period.

  • tmax.webt.io.WebtConnectionPoolInfo getConnectionPoolInfo()

    • Returns information about a connection pool.

  • String getName()

    • Returns the name of a connection pool.

  • boolean isActive()

    • Checks if the current connection pool is active.

  • int size()

    • Returns the number of connections managed by the current pool.

3. Service Call Data Classes

3.1. WebtAttribute

Contains information about the flags that are used to call TP functions such as tpcall(), tpacall(), and tpgetrply() in a WebtRemoteService from the Tmax server.

Constructor

Creates a WebtAttribute object.

The following describes WebAttribute constructors:

  • Constructor 1

    Creates a WebtAttribute object with no specified attributes.

    • Prototype

      public WebtAttribute()
  • Constructor 2

    Creates a WebtAttribute object containing the attributes specified by the flag parameter.

    • Prototype

      public WebtAttribute(int flag)
    • Parameter

      Parameter Description

      flag

      Each field in the WebtAttribute class can be used as a flag.

Field

The following is a list of fields in the WebtAttribute class:

  • public static final int TPBLOCK

    • Calls the WebtRemoteService.tpacall method.

    • By setting a TPBLOCK, it is possible to receive a response containing information about an error of a service or a server. If a TPBLOCK is set, and a call for a WebtRemoteService.tpacall method fails, a WebtServiceException or WebtIOException will be thrown.

  • public static final int TPFUNC

    • Calls the WebtRQService.tpenq method or the WebtRQService.tpdeq method. TPFUNC is used to manage RQ data for each service.

  • public static final int TPGETANY

    • Calls the WebtRemoteService.tpgetrply method.

    • If TPGETANY is set, and a WebtBuffer which corresponds to an identifier(cd) has not been received when a WebtRemoteService.tpgetrply method is called, the identifier that was passed as a parameter of tpgetrply will be ignored, and a previously received WebtBuffer will be returned.

  • public static final int TPNOBLOCK

    • Mainly used for the WebtRemoteService.tpgetrply() method.

    • If TPNOBLOCK is set, and the network is blocked when calling the TP method, WebtServiceException(tperrno=TPETIME) will be thrown.

  • public static final int TPNOCHANGE

    • Used to call the tpcall and tpgetrply methods of a WebtRemoteService.

    • If TPNOCHANGE is set, and the receive buffer type specified when calling a tpcall method or a tpgetrply method does not match the received WebtBuffer type, a WebtServiceException(tperrno=TPEOTYPE) will be thrown.

  • public static final int TPNOFLAGS

    • Indicates that no attribute has been set.

  • public static final int TPNOREPLY

    • Setting TPNOREPLY allows a request to be sent without expecting a response. When TPNOREPLY is set and the WebtRemoteService.tpacall method completes successfully, an identifier value of 0 is returned. This identifier cannot be used with the WebtRemoteService.tpgetrply method.

    • If a WebtRemoteService.tpacall method is in a transaction state, it is impossible to use a TPNOREPLY because a response is required. To use a TPNOREPLY in such a state, it must be used with a TPNOTRAN in order to be excluded from the transaction boundary.

  • public static final int TPNOTIME

    • If a TPNOTIME is set, a BLOCKTIME value specified in a Tmax server configuration file or the blocking timeout value specified by a WebtConnection.setTPtimeout(int) method will be ignored, and they will be set to 'infinite', which means they will wait infinitely for a response.

    • By setting a TPNOTIME for a tpcall, tpacall, or tpgetrply method in a transaction boundary, a transaction timeout will be applied, and a TPNOTIME will be ignored.

  • public static final int TPNOTRAN

    • Used for the tpcall and tpacall methods of a WebtRemoteService. Even though the methods are included in a transaction boundary by WebtTransaction, if a TPNOTRAN is set, they can be excluded from the boundary.

  • static final int TPRETRY

    • Sets a user method in Java gateways.

  • public static final int TPRQS

    • Calls the WebtRQService.tpenq method or the WebtRQService.tpdeq method.

    • Setting a TPRQS means that when using a RQ service, data will be recorded in the request queue and received from the reply queue.

For more information about each attribute, refer to "Tmax Application Development Guide".

Method

The following is a list of methods of the WebtAttribute class:

  • public void clearAttribute()

    • Clears all attributes.

  • public WebtAttribute duplicate()

    • Copies a WebtAttribute object.

  • public boolean getAttribute(int attr)

    • Examines whether a specific attribute is set. If all attributes specified in a attr parameter are set, a TRUE value will be returned, otherwise a FALSE value will be returned.

    • Parameter

      Parameter Description

      attr

      Specify one or more of the following: TPNOBLOCK, TPNOREPLY, TPNOTRAN, TPNOTIME ,TPGETANY, TPNOCHANGE, TPBLOCK, TPRQS, TPFUNC

      Any values not listed above will be ignored. Multiple values can be combined using the OR operator (|).

  • public String toString()

    • Returns the string value of an object.

  • public boolean isTPBLOCK()

    • Checks if TPBLOCK is set.

  • public boolean isTPFUNC()

    • Checks if TPFUNC is set.

  • public boolean isTPGETANY()

    • Checks if TPGETANY is set.

  • public boolean isTPNOBLOCK()

    • Checks if TPNOBLOCK is set.

  • public boolean isTPNOCHANGE()

    • Checks if TPNOCHANGE is set.

  • public boolean isTPNOREPLY()

    • Cheks if TPNOREPLY is set.

  • public boolean isTPNOTIME()

    • Cheks if TPNOTIME is set.

  • public boolean isTPNOTRAN()

    • Checks if TPNOTRAN is set.

  • public boolean isTPRQS()

    • Checks if TPRQS is set.

  • public void setTPBLOCK(boolean value)

    • Sets or releases TPBLOCK.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPBLOCK will be set. If FALSE, TPBLOCK will be released.

  • public void setTPFUNC(boolean value)

    • Sets or releases TPFUNC.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPFUNC will be set. If FALSE, TPFUNC will be released.

  • public void setTPGETANY(boolean value)

    • Sets or cancels a TPGETANY.

    • Parameter

      Parameter Description

      value

      If set to TRUE, a TPGETANY will be set. If FALSE, TPGETANY will be released.

  • public void setTPNOBLOCK(boolean value)

    • Sets or cancels TPNOBLOCK.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPNOBLOCK will be set. If FALSE, TPNOBLOCK will be released.

  • public void setTPNOCHANGE(boolean value)

    • Sets or releases TPNOCHANGE.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPNOCHANGE will be set. If FALSE, TPNOCHANGE will be released.

  • public void setTPNOREPLY(boolean value)

    • Sets or releases TPNOREPLY.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPNOREPLY will be set. If FALSE, TPNOREPLY will be released.

  • public void setTPNOTIME(boolean value)

    • Sets or releases TPNOTIME.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPNOTIME will be set. If FALSE, TPNOTIME will be released.

  • public void setTPNOTRAN(boolean value)

    • Sets or releases TPNOTRAN.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPNOTRAN will be set. If FALSE, TPNOTRAN will be released.

  • public void setTPRETRY(boolean value)

    • Sets or releases TPRETRY.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPRETRY will be set. If FALSE, TPRETRY will be released.

  • public void setTPRQS(boolean value)

    • Sets or releases TPRQS.

    • Parameter

      Parameter Description

      value

      If set to TRUE, TPRQS will be set. If FALSE, TPRQS will be released.

3.2. WebtBuffer

Manages user data exchanged between WebT and a Tmax server. This class is used as a return value of a TP method (tpcall, tpgetrply) in a WebtRemoteService and as a parameter of a handleEvent in a WebtEventHandler. User data needed to call tpcall and tpacall methods are stored in WebtBuffer.

WebtBuffer is an abstract class, so a user cannot directly create one. To obtain a WebtBuffer for inputting data from the tpcall and tpacall methods, the WebtRemoteService.createStringBuffer, WebtRemoteService.createCarrayBuffer, and WebtRemoteService.createFieldBuffer methods can be used.

Constructor

Creates a WebtBuffer object.

The following describes the WebtBuffer class constructor:

  • Prototype

    public WebtBuffer()
Field

The following is a list of fields in a WebtBuffer class:

  • static int BT_CARRAY

    • CARRAY buffer type. Used when a return value of a getBufferType() method is BT_CARRAY.

  • static int BT_FIELD

    • FIELD buffer type. Used when a return value of a getBufferType method is BT_FIELD.

  • static int BT_STRING

    • STRING buffer type. Used when a return value of a getBufferType method is BT_STRING.

For more information about buffer types, refer to "Tmax Administration Guide".

Method

The following is a list of methods in a WebtBuffer class:

  • public static WebtBuffer createCarrayBuffer()

    • Creates a WebtBuffer object with the BT_CARRAY buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public static WebtBuffer createCarrayBuffer(String charset)

    • Creates a WebtBuffer object with the BT_CARRAY buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public static WebtBuffer createFieldBuffer()

    • Creates a WebtBuffer object with the BT_FIELD buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public static WebtBuffer createFieldBuffer(String charset)

    • Creates a WebtBuffer object with the BT_FIELD buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public static WebtBuffer createStringBuffer()

    • Creates a WebtBuffer object with the BT_STRING buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public static WebtBuffer createStringBuffer(String charset)

    • Creates a WebtBuffer object with the BT_STRING buffer type.

    • The character set used is the return value of the WebtSystem.getDefaultCharset method.

  • public String getBufferTypeString()

    • Returns a string that corresponds to the buffer type.

  • public int getBufferType()

    • Returns the buffer type.

  • public int getCallDescriptor()

    • Returns the call descriptor of the WebtBuffer. A call descriptor is the value returned by the WebtRemoteService.tpacall() method and is used as a parameter for the tpgetrply() method. A value greater than or equal to 0 indicates a valid descriptor.

  • public int getDataLength()

    • Returns the length of the data when converted to a byte stream.

  • public String getDefaultCharset()

    • Returns the default character set to be used by a buffer. If NULL is returned, the system default system character set will be used.

  • public String getServiceName()

    • Returns the currently specified service name.

  • public String getString()

    • If the buffer type is BT_STRING or BT_CARRAY, the content from the beginning of the data up to (but not including) the first 0x00 byte is converted to a string and returned. If no 0x00 byte is found in the data, the entire byte array is converted.

      The character set returned by the getDefaultCharset() method is used for encoding.

    • Exception

      Exception Description

      WebtBufferException

      The return value of the getBufferType method is neither BT_STRING nor BT_CARRAY, or the return value of the getDefaultCharset method is a character set that is not supported by the system.

  • public int getUserReturnCode()

    • Returns a value that was specified as urcode when a tpreturn method was executed in a Tmax service routine.

  • public void setDefaultCharset(String charset)

    • Specifies a character set to be used in a buffer. To apply the character set, it must be specified before starting the buffer. If not specified, the return value of a WebtRemoteService.getDefaultCharset method will be used.

  • public void setString(String val)

    • Sets data to request a service from Tmax.

    • This method can be used only when the buffer type is a BT_STRING or BT_CARRAY. Otherwise, a WebtBufferException (tperrno = TPEINVAL) will be thrown. 0x00 will be added to the end of the data converted into a byte array. For character set conversion, the return value of the getDefaultCharacterSet method is used.

    • Parameter

      Parameter Description

      val

      Content to set for the buffer.

    • Exception

      Exception Description

      WebtBufferException

      The return value of a getBufferType method is neither BT_STRING nor BT_CARRAY, or the return value of a getDefaultCharacterSet method is a character set that is not supported by the system.

Example

The following is an example of using WebtBuffer to receive a Tmax service. The buffer type is BT_STRING.

WebtConnection connection = null;

try {
    connection = new WebtConnection("localhost", 8888);

    WebtRemoteService service = new WebtRemoteService("TEST", connection);
    WebtBuffer request = service.createStringBuffer();
    request.setString("test string");

    WebtAttribute attr = new WebtAttribute();
    attr.setTPNOTIME();
    WebtBuffer response = service.tpcall(request,attr);
    System.out.println("response : " + response.getString());
}

catch (WebtIOException ioe) {
    System.out.println("webt connection closed");
    ioe.printStackTrace();
}

catch (WebtServiceFailException sfe) {
    System.out.println("server returns TP_FAIL");
}

catch (WebtServiceException se) {
    System.out.println("service fail. tperrno = " + se.getTPErrorMessage());
    se.printStackTrace();
}

finally {
    connection.close();
}

3.3. WebtCarrayBuffer / WebtStringBuffer

Objects inherited from WebtBuffer. They are declared to have the CARRAY or STRING type data.

Constructor

Creates a WebtCarrayBuffer and WebtStringBuffer object.

The following is description about WebtCarrayBuffer/WebtStringBuffer constructors:

  • WebtCarrayBuffer

    • Prototype

      WebtCarrayBuffer()
  • WebtStringBuffer

    • Prototype

      WebtStringBuffer()
Method

The following is a list of methods of the WebtCarrayBuffer and WebtStringBuffer classes:

  • public void clear()

    • Deletes all internal WebtField objects.

  • public byte[ ] getBytes()

    • Returns all data from the beginning to the end, when the buffer type is BT_CARRAY or BT_STRING. Functions the same as getBytes(false).

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_CARRAY nor BT_STRING.

  • public byte[ ] getBytes(boolean clone)

    • Returns all data from the beginning to the end, when the buffer type is BT_CARRAY.

    • Parameter

      Parameter Description

      clone

      If set to TRUE, a new byte array with copied content will be returned.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is not BT_CARRAY.

  • public byte[ ] getBytes(int offset, int length)

    • If the buffer type is set to either BT_STRING or BT_CARRAY, the data starting from the position specified by the offset parameter and spanning the length specified by the length parameter will be returned as a byte array.

    • Parameter

      Parameter Description

      offset

      Starting position to retrieve from the buffer.

      length

      The length of the data to read.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

  • public String getString(int offset, int length)

    • If the buffer type is set to either BT_STRING or BT_CARRAY, the data starting from the position specified by the offset parameter and spanning the length specified by the length parameter will be returned as a string.

    • Parameter

      Parameter Description

      offset

      Starting position to retrieve from the buffer.

      length

      The length of the data to read.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

  • public String getString(String charset)

    • If the buffer type is BT_STRING or BT_CARRAY, the content from the beginning of the data up to (but not including) the first 0x00 byte is converted to a string and returned. If no 0x00 byte is found in the data, the entire byte array is converted.

    • Parameter

      Parameter Description

      charset

      Used to convert the byte array into a string. The value returned by the WebtBuffer.getDefaultCharset method is used.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

  • public void setBytes(byte[ ] val)

    • Sets data to request a service from Tmax.

    • Can be used only when the buffer type is BT_CARRAY. Otherwise, a WebtBufferException(tperrno = TPEINVAL) will be thrown.

    • Parameter

      Parameter Description

      val

      Content to set in the buffer.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is not BT_CARRAY.

  • public void setBytes(byte[ ] val, boolean clone)

    • Sets data to request a service from Tmax.

    • Can be used only when the buffer type is BT_CARRAY. Otherwise, a WebtBufferException(tperrno = TPEINVAL) will be thrown.

    • Parameter

      Parameter Description

      clone

      An option to copy content.

      If set to TRUE, a byte array with the same value as val will be created internally, and the content will be copied.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is not BT_CARRAY.

  • public int setBytes(byte[ ] value, int off, int len)

    • Copies and stores the content in 'value' starting from 'off', and returns the length of the input data.

    • Can be used when the buffer type is either BT_STRING or BT_CARRAY. Otherwise, a WebtBufferException (tperrno = TPEINVAL) will be thrown.

    • Parameter

      Parameter Description

      value

      Data to store.

      off

      Starting position to retrieve.

      len

      The length of the data to copy

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

  • public int setString(int offset, String value)

    • Copies and stores the content in 'value' starting from 'offset', and returns the length of the input data.

    • Can be used when the buffer type is either BT_STRING or BT_CARRAY. Otherwise, a WebtBufferException (tperrno = TPEINVAL) will be thrown.

    • Parameter

      Parameter Description

      offset

      Starting position to retrieve.

      value

      Data to store.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

  • public void setString(String value, String charset)

    • Sets user data.

    • Can be used when the buffer type is either BT_STRING or BT_CARRAY. Otherwise, a WebtBufferException (tperrno = TPEINVAL) will be thrown. 0x00 is added to the end of the data converted into a byte array.

    • Parameter

      Parameter Description

      value

      Content to set in the buffer.

      charset

      Character set to be used to convert the value into a byte array.

      If NULL, the value returned by the getDefaultCharacterSet method is used.

    • Exception

      Exception Description

      WebtBufferException

      The buffer type is neither BT_STRING nor BT_CARRAY, or the character set is not supported by the system.

4. Service Call Classes

4.1. WebtRemoteService

The WebtRemoteService class provides an API that is used to receive Tmax services by using a WebtConnection class and its children classes, and to manage service names and attributes needed to call the Tmax services. For information about how to use the class, refer to WebtBuffer.

Constructor

Creates a WebtRemoteService object.

The following describes the WebtRemoteService class constructor:

  • Prototype

    WebtRemoteService(String svcname, WebtConnection con)
  • Parameter

    Parameter Description

    svcname

    The name of a service to request from Tmax.

    con

    A WebtConnection object where information about Tmax connections and attributes is set.

Method

The following is a list of methods of the WebtRemoteService class:

  • public void clear()

    • Initializes a default service name and a WebtConnection object to NULL. It also initializes a default character set to the return value of a WebtSystem.getDefaultCharset method.

  • public WebtBuffer createCarrayBuffer([int size])

    • Creates a WebtBuffer object with the BT_CARRAY buffer type.

  • public WebtFieldBuffer createFieldBuffer([int size|WebtFDLKeyTable table])

    • Creates a WebtBuffer object with the BT_FIELD buffer type.

    • Parameter

      Parameter Description

      table

      A FDL key table instance.

  • public WebtBuffer createStringBuffer([int size])

    • Creates a WebtBuffer object with the BT_STRING buffer type.

  • public WebtConnection getConnection()

    • Returns a WebtConnection object used to call a TP method(tpcall, tpgetrply).

  • public String getServiceName()

    • Returns the default service name.

  • public void setDefaultCharset(String charset)

    • Sets the character set to apply to all WebtBuffer objects created by a WebtRemoteService object.

    • This must be set before calling the createStringBuffer, createCarrayBuffer, and createFieldBuffer methods, so that the value specified in the WebtBuffer object can apply.

    • Parameter

      Parameter Description

      charset

      The character set to be used.

  • public String getDefaultCharset()

    • Returns the character set to apply to all WebtBuffer objects created through a WebtRemoteService object.

  • public void setServiceName(String svcname)

    • Sets the default service name.

  • public int tpacall([String svcname,] WebtBuffer tx [,WebtAttribute attr] [,WebtMessageHandler])

    • Sends a tpacall service request to a Tmax server.

    • Parameter

      Parameter Description

      svcname

      A service name.

      tx

      A buffer used to send a service request.

      attr

      An attribute to apply when calling a method.

    • Exception

      Exception Description

      WebtServiceFailException

      The Tmax service returned TPFAIL.

      WebtTXException

      A transaction error occurred.

      WebtServiceException

      A Tmax service error occurred.

      WebtIOException

      A network-related Tmax service error occurred.

  • public WebtBuffer tpcall([String svcname,] WebtBuffer tx [,WebtAttribute attr])

    • Uses a tpcall to send a service request to a Tmax server.

    • Parameter

      Parameter Description

      svcname

      A service name.

      tx

      A buffer used to send a service request.

      attr

      An attribute to apply when calling a method.

    • Exception

      Exception Description

      WebtServiceFailException

      The Tmax service returned TPFAIL.

      WebtTXException

      A transaction error occurred.

      WebtServiceException

      A Tmax service error occurred.

      WebtIOException

      A network-related Tmax service error occurred.

  • public int tpacallsvg(int svgno|String nodename, [String svcName,] WebtBuffer txBuffer [,WebtAttribute attribute])

    • Used to call a service in a specific server group. In a multi-server-group environment where server groups are bound as COUSINs, this method allows specifying a service within a particular server group and sending the service request asynchronously. It functions similarly to tpacall(), but with the added ability to target a specific server group.

    • Parameter

      Parameter Description

      svgno

      The number of the server group where the service is included. It can be retrieved using the tpgetsvglist method. If set to -1, it functions the same as the tpcall method.

      nodeName

      A node name.

      svcName

      A service name.

      txBuffer

      A buffer used to send a service request

      attribute

      An attribute to apply when calling a method.

  • public WebtBuffer tpcallsvg(int svgno|String nodename, [String svcName,] WebtBuffer txBuffer [,WebtAttribute attribute])

    • Used to call a service in a specific server group. In a multi-server-group environment where server groups are bound as COUSINs, this method allows specifying a service within a particular server group and sending the service request asynchronously. It functions similarly to tpacall(), but with the added ability to target a specific server group.

      When calling to a server process (spr) that has not been started, a tpgetreply method will return a TPENOENT exception and the header-type must be set to 'extendedV4'. (Old versions headers are not supported).

    • Parameter

      Parameter Description

      svgno

      The number of the server group where the service is included. It can be retrieved using the tpgetsvglist() API. If set to -1, it functions the same as the tpcall method. The name given when a WebtRemoteService object is created is used as the service name.

      nodeName

      A node name.

      svcName

      A service name.

      txBuffer

      A buffer used to send a service request

      attribute

      An attribute to apply when calling a method.

  • public int tpgetsprlist([String svcName], int svgno, int[] index, WebtAttribute attribute)

    • Used to retrieve the server process index of a service in a specific server group. This is used to call a service at the server process level.

    • Parameter

      Parameter Description

      svcName

      A service name. If not specified, the service name set in WebtRemoteService will be used.

      svgno

      The number of the server group where the service is included. It can be retrieved using the tpgetsvglist method.

      index

      An int array used to retrieve the minimum and maximum server process index values. The array must have at least two elements. If the method executes successfully, the starting index will be stored in index[0], and the ending index will be stored in index[1].

      attribute

      An attribute to apply when calling a method.

  • public int tpspracall([String svcName], int spri, WebtBuffer txBuffer, WebtAttribute attribute)

    • Used to call a service on a specific server process. The valid range of server process numbers should be obtained using the tpgetsprlist method. All other functionality is similar to tpacall, including receiving a response via the tpgetrply method.

      When calling to a server process (spr) that has not been started, a tpgetreply method will return a TPENOENT exception and the header-type must be set to 'extendedV4' (Old versions headers are not supported).

    • Parameter

      Parameter Description

      svcName

      A service name. If not specified, the service name set in WebtRemoteService will be used.

      spri

      A server process index. It can be retrieved using the tpgetsprlist method.

      txBuffer

      A buffer used to send a service request.

      attribute

      An attribute to apply when calling a method. The current version ignores the attribute setting.

  • public void tpcancel(int cd)

    • Cancels a cd which is a call identifier returned by a tpacall method. Services related to global transactions cannot be canceled. If a service response is successfully canceled, responses received through the cd will also be ignored. If the tpacall method was called by using a WebtTPAListner, the errorHandle method will be called.

    • Parameter

      Parameter Description

      cd

      Call descriptor. This is the return value of tpacall().

    • Exception

      Exception Description

      WebtServiceException

      When an error occurs, a WebtServiceException is thrown. The error number (errono) varies depending on the situation: If a transaction was in progress at the time of the error, errono is WebtException.TPETRAN. If there is no cd value, errono is also set to WebtException.TPEBADDESC.

  • public WebtBuffer tpgetrply(int cd [,WebtAttribute attr])

    • Receives a response from a tpacall(). It functions similarly to int tpgetrply(int *cd, char **rbuf, long *rlen, long flags).

    • Parameter

      Parameter Description

      cd

      Call descriptor. This is the return value of tpacall().

      attr

      An attribute to apply when calling a method. For information about attributes to apply to an attr, refer to "Tmax Application Development Guide".

    • Exception

      Exception Description

      java.lang.IllegalStateException

      Occurs when a tpgetrply() is called when a callback for an acall reply has been registered by a WebtEventHandler.

  • public int[ ] tpgetsvglist([[[String nodename,] String svcName,] WebtAttribute attribute])

    • Provides information about the server group where the specified service is included, and the other server groups that are set as COUSIN with this server group.

    • Parameter

      Parameter Description

      nodeName

      A node name.

      svcName

      A service name.

      attribute

      Sets TOPNOFLAGS. Currently not supported.

4.2. WebtRQService

Inherited from a WebtRemoteService. This class is used to utilize a service that manages a Reliable Queue (RQ).

Constructor

Creates a WebtRQService object to obtain a Tmax RQ service.

The following describes the WebtRQService class constructor.

  • Prototype

    public WebtRQService(String qname,
                         String svcname,
                         WebtConnection con)
  • Parameter

    Parameter Description

    qname

    Specifies the name of a Tmax RQ (Request Queue) to use as the default for tpend and tpdeq method calls. The name must match the one defined in the Tmax configuration file and must not be NULL.

    svcname

    Specifies the name of a Tmax service to use as the default for penq and tpdeq method calls. The name must match the one defined in the Tmax configuration file, or be set to NULL.

    con

    A WebtConnection object used to get a service. Must not be NULL.

  • Exception

    Exception Description

    java.lang.IllegalArgumentException

    con is NULL.

Field

The following is a list of fields of the WebtRQService class:

  • public static final String RQ_ANY_QUEUE

    • By setting a RQ_ANY_QUEUE, and using a RQ service, statistical information of Request Queues, Reply Queues, and Fail Queues can be received when calling WebtRQService.tpqstat and WebtRQService.tpqsvcstat methods.

  • public static final String RQ_FAIL_QUEUE

    • By setting a RQ_FAIL_QUEUE, and using a RQ service, statistical information of Fail Queues can be received when calling WebtRQService.tpqstat and WebtRQService.tpqsvcstat methods.

  • public static final String RQ_REQ_QUEUE

    • By setting a RQ_REQ_QUEUE, and using a RQ service, statistical information of Request Queues can be received when calling WebtRQService.tpqstat and WebtRQService.tpqsvcstat methods.

  • public static final String RQ_RPLY_QUEUE

    • By setting a RQ_RPLY_QUEUE, and using a RQ service, statistical information of Reply Queues can be received when calling WebtRQService.tpqstat and WebtRQService.tpqsvcstat methods.

  • public static final int TPERR

    • When the WebtRQService.tpenq method fails, this value is returned after the message is sent to the Fail Queue.

    • The return type can be checked using the WebtRQService.checkError method, and the error code can be retrieved using the WebtBuffer.getUserReturnCode method.

  • public static final int TPFAIL

    • This value is returned by the WebtRQService.tpenq method if the specified service name is provided and that service calls tpreturn with TPFAIL as its first parameter.

    • The return type can be checked using the WebtRQService.checkError method, and the error code can be retrieved using the WebtBuffer.getUserReturnCode method.

  • public static final int TPREQ

    • This value is returned by the WebtRQService.tpenq method when the second parameter is set to NULL instead of a service name, and the service is successfully provided.

    • The return type can be checked using the WebtRQService.checkError method, and the error code can be retrieved using the WebtBuffer.getUserReturnCode method.

  • public static final int TPSUCCESS

    • This value is returned by the WebtRQService.tpenq method if the specified service name is provided and that service calls tpreturn with TPSUCCESS as its first parameter.

    • The return type can be checked using the WebtRQService.checkError method, and the error code can be retrieved using the WebtBuffer.getUserReturnCode method.

Method

The following is a list of methods of a WebtRQService class:

  • public static int checkError(WebtBuffer rqbuf)

    • Retrieves detailed information about data stored in the RQ. The service name can be obtained using the rqbuf.getServiceName method, and the error code can be retrieved using the rqbuf.getUserReturnCode method.

  • public String getQueueName()

    • Returns the specified default RQ name.

  • public void setQueueName(String qname)

    • Resets the RQ name used as the default value when calling the tpenq() and tpdeq() methods.

    • Parameter

      Parameter Description

      qname

      The new default RQ name to set.

    • Exception

      Exception Description

      java.lang.IllegalArgumentException

      qname is NULL.

  • public WebtBuffer tpdeq(String qname, String svcname, WebtAttribute attr)

    • Retrieves data stored in the RQ. Once read, the data is removed from the RQ and cannot be read again. This method calls the tpdeq() service.

    • Parameter

      Parameter Description

      qname

      The name of the RQ to store data. The name must match the one defined in the Tmax configuration file.

      svcname

      The name of the service to call. It must match the name defined in the Tmax configuration file. The Reply Queue retrieves data sequentially for requests with the same service name.

      attr

      The attribute to apply when calling the method.

      The following are the valid values for this parameter.

      • WebtAttribute.TPRQS : Set this value to receive data from the Reply Queue.

      • WebtAttribute.TPFUNC : Set this value together with WebtAttribute.TPRQS to receive data stored in the Reply Queue. The data is recorded only, without calling the service.

      • WebtAttribute.TPNOFLAGS : Set this value to send the result value to the client buffer. TPNOFLAGS must also be set to receive the result value via tpdeq.

    • Exception

      Exception Description

      WebtServiceException

      qname is NULL or the queue is empty.

      WebtServiceFailException

      The service did not return a valid response.

      WebtIOException

      A network error occurred.

      WebtTXException

      A transaction error occurred.

  • public int tpenq(String qname, String svcname, WebtBuffer tx, WebtAttribute attr)

    • Retrieves data stored in the RQ. Once read, the data is removed from the RQ and cannot be read again. This method calls the tpenq() service.

    • Parameter

      Parameter Description

      qname

      The name of the RQ to store data. The name must match the one defined in the Tmax configuration file.

      svcname

      The name of the service to call. It must match the name defined in the Tmax configuration file. The Reply Queue retrieves data sequentially for requests with the same service name.

      tx

      The data to send when calling the service. Set a variable that will retrieve the data from the RQ.

      attr

      The attribute to apply when calling the method.

      The following are the valid values for this parameter.

      • WebtAttribute.TPRQS : Set this value to receive data from the Reply Queue.

      • WebtAttribute.TPFUNC : Set this value together with WebtAttribute.TPRQS to receive data stored in the Reply Queue. The data is recorded only, without calling the service

      • WebtAttribute.TPNOFLAGS : Set this value to send the result value to the client buffer. TPNOFLAGS must also be set to receive the result value via tpdeq.

    • Exception

      Exception Description

      WebtServiceException

      qname is NULL or the queue is empty.

      WebtServiceFailException

      The service did not return a valid response.

      WebtIOException

      A network error occurred.

      WebtTXException

      A transaction error occurred.

  • int tpenq(WebtBuffer tx [,WebtAttribute attr])

    • Stores data received from a service call in the RQ. The data is managed and read in the order it arrives. This method calls the tpenq service.

    • Parameter

      Parameter Description

      svcname

      The name of the service to call. It must match the name defined in the Tmax configuration file.

      tx

      The data to send when calling the service.

      attr

      The attribute to apply when calling the method.

      The following are the valid values for this parameter.

      • WebtAttribute.TPRQS : Stores the request data in the Request Queue, and after the service is executed, stores the result in the Reply Queue.

      • WebtAttribute.TPNOREPLY : Executes the service without storing the result in the Reply Queue.

      • WebtAttribute.TPFUNC : Stores the sent data directly in the Reply Queue without invoking the service.

      • WebtAttribute.TPNOFLAGS : Stores the service result directly in the client buffer, regardless of the service outcome.

    • Exception

      Exception Description

      WebtServiceException

      The service did not return a valid response.

      WebtIOException

      A network error occurred.

      WebtTXException

      A transaction error occurred.

  • public int tpqstat(String qname, String qtype)

    • Retrieves statistical results for the data stored in the queues. If qname is NULL, the getQueueName method is used to determine the queue name.

    • Parameter

      Parameter Description

      qname

      The name of the RQ from which to receive statistical values. It must match the name defined in the Tmax configuration file.

      qtype

      The following are the valid values for this parameter.

      • RQ_ANY_QUEUE : Calculates statistics of the Request Queue, Reply Queue, and Fail Queue.

      • RQ_FAIL_QUEUE : Calculates statistics of the Fail Queue.

      • RQ_REQ_QUEUE : Calculates statistics of the Request Queue.

      • RQ_RPLY_QUEUE : Calculates statistics of the Reply Queue.

    • Exception

      Exception Description

      WebtServiceException

      The qname is NULL, or the qtype is not a valid name.

      WebtIOException

      A network error occurred.

  • int tpqsvcstat(String qname, String svcname, String qtype)

    • Retrieves statistical results for the data stored in the queues by service name. If qname is NULL, the getQueueName method is used to determine the queue name.

    • Parameter

      Parameter Description

      qname

      The name of the RQ from which to receive statistical values. It must match the name defined in the Tmax configuration file.

      svcname

      The name of the service.

      qtype

      The following are the valid values for this parameter.

      • WebtRQService.RQ_ANY_QUEUE : Calculates statistics of the Request Queue, Reply Queue, and Fail Queue.

      • WebtRQService.RQ_FAIL_QUEUE : Calculates statistics of the Fail Queue.

      • WebtRQService.RQ_REQ_QUEUE : Calculates statistics of the Request Queue.

      • WebtRQService.RQ_RPLY_QUEUE : Calculates statistics of the Reply Queue.

    • Exception

      Exception Description

      WebtServiceException

      The qname is NULL, or the qtype is not a valid name.

      WebtIOException

      A network error occurred.

4.3. WebtDialogueService

Inherited from WebtRemotedService. It provides an interactive service (conversation mode service).

Constructor

Creates a WebtDialogueService object.

The following describes the WebtDialogueService class constructor:

  • Prototype

    public WebtDialogueService(String svcname,
                               WebtConnection con)
  • Parameter

    Parameter Description

    svcname

    The name of the service to request from Tmax.

    con

    A WebtConnection object where information about Tmax connections and attributes are set.

  • Exception

    Exception Description

    java.lang.IllegalArgumentException

    The svcname or con is NULL.

Method

The following is a list of methods of the WebtDialogueService class:

  • public boolean isClosed()

    • Returns true or false depending on whether the session is closed.

  • public boolean isReceiveNext()

    • Returns true or false depending on whether the tprecv operation can be performed.

    • Exception

      Exception Description

      WebtServiceException

      The isReceiveNext method was called before a tpconnect was established.

  • public boolean isSendNext()

    • Returns true or false depending on whether the tpsend operation can be performed.

    • Exception

      Exception Description

      WebtServiceException

      The isSendNext method was called before a tpconnect was established.

  • DialogueQueue tpconnect([WebtBuffer sndbuf,] [WebtAttribute attr,] boolean recvNext)

    • Sets a connection for interactive (conversational) mode services. The owner responsible for managing the conversation must be specified when establishing the connection.

    • Parameter

      Parameter Description

      sndbuf

      The message to send to the server during tpconnect.

      attr

      An attribute to apply to the send buffer. Only those defined in WebtAttribute are valid.

      recvNext

      • TRUE : After tpconnect is established, connection control is passed to the other party, and this side only receives messages.

      • FALSE : After tpconnect is established, this side keeps connection control and executes tpsend. The other party can only receive messages.

    • Exception

      Exception Description

      WebtServiceException

      The service did not return a valid response.

      WebtIOException

      A network error occurred.

      WebtTXException

      A transaction error occurred.

  • public void tpdiscon()

    • The party that holds connection control after tpconnect can immediately terminate the connection in an interactive service.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      The service did not return a valid response.

  • WebtBuffer tprecv([WebtAttribute attr])

    • The party that holds connection control passes control to the other party and switches to receive mode, where it only receives messages.

    • Parameter

      Parameter Description

      attr

      An attribute to apply to the receive buffer. Only those defined in WebtAttribute are valid.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      The queue is not set or the service did not return a valid response within the timeout period.

      WebtDialogueException

      The interactive service is not available for service.

  • void tpsend(WebtBuffer tx, [WebtAttribute attr,] boolean recvNext)

    • Sends messages for interactive services.

    • Parameter

      Parameter Description

      tx

      The message buffer.

      attr

      A user attribute. Only those defined in WebtAttribute are valid.

      recvNext

      Option to switch to receive mode after sending a message.

      • TRUE : Switches to receive mode.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      The queue is not set or the service did not return a valid response within the timeout period.

      WebtDialogueException

      The interactive service is not available for service.

5. Field Data Classes

5.1. WebtFieldElement

The WebtFieldElement interface represents the data of a field key within a WebtField. The WebtField manages field data as WebtFieldElement objects, with each field holding a single WebtFieldElement instance.

Since WebtFieldElement is an interface, users cannot directly instantiate it. When field data is received from a Tmax server, WebT creates WebtFieldElement objects and adds them to a WebtField. To create and add a WebtFieldElement object manually, users can use the WebtField.add or WebtField.insert methods.

Method

The following is a list of methods of the WebtFieldElement class:

  • byte[ ] bytesValue()

    • Converts a field data element into a byte[ ] array, and returns it.

    • According to the field type, converts field data as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Return the originally stored data as a byte[] array. However, for FB_STRING, which ends with a '\0' when received from the Tmax server, the returned array excludes the trailing '\0'.

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Return stringValue().getBytes().

    • Exception

      Exception Description

      WebtBufferException

      The field data is NULL.

  • byte byteValue()

    • Converts a field data element into a byte value, and returns it.

    • According to the field type, converts field data as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Same as bytesValue[0].

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Return the originally stored data as a byte type value.

    • Exception

      Exception Description

      WebtBufferException

      The field data is NULL.

  • double doubleValue()

    • Converts a field data element into a double type, and returns it.

    • If the original data is a value, the field data is converted and returned according to its field type.

    • The field data is converted and returned as follows.

      • FB_CHAR, FB_CARRAY, FB_STRING : Return the same result as Double.valueOf(stringValue()).doubleValue().

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Return stringValue().getBytes().

    • Exception

      Exception Description

      WebtBufferException

      If the field type of a WebtFieldElement is FB_STRING, FB_CHAR, or FB_CARRAY and the value is numeric, a java.io.NumberFormatException or java.io.UnsupportedEncodingException may be thrown. These exceptions will be wrapped in a WebtBufferException. Additionally, if the field data is NULL, a WebtBufferException will also be thrown.

  • float floatValue()

    • Converts a data element into a float type, and returns it.

    • If the original data is a value, the field data is converted and returned according to its field type, as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Returns the same result as Float.valueOf(stringValue()).floatValue().

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Returns the same result as (new Double(value)).floatValue().

    • Exception

      Exception Description

      WebtBufferException

      If the field type of a WebtFieldElement is FB_STRING, FB_CHAR, or FB_CARRAY and the value is numeric, a java.io.NumberFormatException or java.io.UnsupportedEncodingException may be thrown. These exceptions will be wrapped in a WebtBufferException. Additionally, if the field data is NULL, a WebtBufferException will also be thrown.

  • WebtField getField()

    • Returns a reference to the WebtField object that contains this WebtFieldElement.

  • int intValue()

    • Converts a data element into a int type, and returns it.

    • If the original data is a value, the field data is converted and returned according to its field type, as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Returns the same result as Integer.valueOf(stringValue()).intValue().

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Returns the same result as (new Double(value)).intValue().

    • Exception

      Exception Description

      WebtBufferException

      If the field type of a WebtFieldElement is FB_STRING, FB_CHAR, or FB_CARRAY and the value is numeric, a java.io.NumberFormatException or java.io.UnsupportedEncodingException may be thrown. These exceptions will be wrapped in a WebtBufferException. Additionally, if the field data is NULL, a WebtBufferException will also be thrown.

  • int longValue()

    • Converts a data element into a long type, and returns it.

    • If the original data is a value, the field data is converted and returned according to its field type, as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Returns the same result as Integer.valueOf(stringValue()).intValue().

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Returns the same result as (new Double(value)).intValue().

    • Exception

      Exception Description

      WebtBufferException

      If the field type of a WebtFieldElement is FB_STRING, FB_CHAR, or FB_CARRAY and the value is numeric, a java.io.NumberFormatException or java.io.UnsupportedEncodingException may be thrown. These exceptions will be wrapped in a WebtBufferException. Additionally, if the field data is NULL, a WebtBufferException will also be thrown.

  • int shortValue()

    • Converts a data element into a short type, and returns it.

    • If the original data is a value, the field data is converted and returned according to its field type, as follows:

      • FB_CHAR, FB_CARRAY, FB_STRING : Returns the same result as Integer.valueOf(stringValue()).shortValue().

      • FB_SHORT, FB_INT, FB_LONG, FB_FLOAT, FB_DOUBLE : Returns the same result as (new Double(value)).shortValue().

    • Exception

      Exception Description

      WebtBufferException

      If the field type of a WebtFieldElement is FB_STRING, FB_CHAR, or FB_CARRAY and the value is numeric, a java.io.NumberFormatException or java.io.UnsupportedEncodingException may be thrown. These exceptions will be wrapped in a WebtBufferException. Additionally, if the field data is NULL, a WebtBufferException will also be thrown.

  • int sstringValue([String charset])

    • Converts a data element into a string, and returns it. Returns the same result as stringValue(getField().getDefaultCharset()).

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

5.2. WebtFDLKeyTable

If the buffer type used to call a Tmax service is WebtBuffer.BT_FIELD, a field key will be used. As in other Tmax clients, the field key in WebT can be used in the following two ways:

Type Description

int

The name of a field key defined in the field definition file is used as a constant of type int.

String

The name of a field key defined in the field definition file is represented as a string.

An fdl file(extension: .fdl), which is generated by compiling a field definition file (extension: .f) using the fdlc utility, must be loaded using the WebtFDLKeyTable class. To use an fdl file in WebT, the WebtSystem.createDefaultFieldKeyTable(String) method must be called.

Constructor

Creates a WebtFDLKeyTable object.

The following describes the WebtFDLKeyTable class constructor:

  • Prototype

    WebtFDLKeyTable()
Method

The following is a list of methods of the WebtFDLKeyTable class:

  • public int getKey(String keyString)

    • Returns the field key name as an int constant.

    • Parameter

      Parameter Description

      keyString

      Field key name.

  • public String getKeyName(int fldkey)

    • Converts an int type constant field key name to a string type and returns it.

    • Parameter

      Parameter Description

      fldkey

      Int type constant.

  • public int getType(String keyString)

    • Returns the field key type.

    • Parameter

      Parameter Description

      keyString

      Field key name.

    • If the field key is invalid, -1 is returned. If the field key is valid, one of the following is returned:

      • FieldAccess.FB_CHAR

      • FieldAccess.FB_SHORT

      • FieldAccess.FB_INT

      • FieldAccess.FB_LONG

      • FieldAccess.FB_FLOAT

      • FieldAccess.FB_DOUBLE

      • FieldAccess.FB_STRING

      • FieldAccess.FB_CARRAY

  • public void loadFDLKeys(String filepath)

    • Loads a field key from the fdl file.

    • Parameter

      Parameter Description

      filepath

      The location of the fdl file.

    • Exception

      Exception Description

      java.io.IOException

      An error occurred while reading the file.

  • public static int makeFDLKey(int type, int no)

    • Creates and returns an int type constant field key when the user defines a field type and field number in the application.

    • Parameter

      Parameter Description

      type

      Sets one of the following:

      • FieldAccess.FB_CHAR

      • FieldAccess.FB_SHORT

      • FieldAccess.FB_INT

      • FieldAccess.FB_LONG

      • FieldAccess.FB_FLOAT

      • FieldAccess.FB_DOUBLE

      • FieldAccess.FB_STRING

      • FieldAccess.FB_CARRAY

      no

      Field number.

  • public int size()

    • Returns the number of currently loaded field keys.

5.3. WebtFieldSet

The WebtFieldSet class is a utility class that simplifies handling field data elements when the buffer type is WebtBuffer.BT_FIELD.

Constructor

Creates a WebtFieldSet object with a given WebtBuffer.

The following is the WebtFieldSet class constructor:

  • Prototype

    public WebtFieldSet(WebtBuffer buffer)
  • Parameter

    Parameter Description

    buffer

    A WebtBuffer object of the WebtBuffer.BT_FIELD type

  • Exception

    Exception Description

    java.lang.IllegalArgumentException

    The buffer is NULL.

    WebtBufferException

    The buffer type is not BT_FIELD.

Method

The following is a list of methods of the WebtFieldSet class:

  • public void add(int key|String key , byte[ ] value|double value |long value|String value [,String charset])

    • Adds field data using the field key value or the field key name matching the specified key.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      value

      Field data to add.

      charset

      Character set to use.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public int count(int key)

    • Returns the number of elements of field data that has the same field key value as the specified key.

    • Parameter

      Parameter Description

      key

      Field key value.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public WebtFieldElement get(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public byte getByte(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a byte. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public byte[ ] getBytes(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a byte[] array. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public Double getDouble(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a double type. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public Float getFloat(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a float type. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public Integer getInt(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in an integer. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public Long getLong(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a long type. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public Short getShort(int key|String key[, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a short type. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public String getString(int key|String key[, String charset] [, int index])

    • Returns the data associated with the field key value or key name matching the specified key in a string. If an index is specified, the data at that index position is returned.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      charset

      Character set to use.

      index

      The position of the field data element.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public java.util.Vector getFieldKeyNames()

    • Searches for a list of field key names (as strings) from the field key names list created by WebtSystem.createDefaultFieldKeyTable, and returns the matching list.

  • public void insert(int key|String key, byte[ ] value/ double value/ long value/ String value[,String charset], int index)

    • Inserts field data with a field key value or field key name matching the specified key. For string-type data, the character set can be specified.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      value

      Field data to insert.

      charset

      Character set to use.

      index

      Position to insert the field data.

    • Exception

      Exception Description

      WebtBufferException

      No WebtField object that matches the specified key is found.

  • public void remove(int key|String key[, int index])

    • Removes the field data element with the field key value or key name matching the specified key.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

      index

      Position of the field data element to remove.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public void removeAll(int key|String key)

    • Removes all field data elements with the field key value or key name matching the specified key.

    • Parameter

      Parameter Description

      key

      Field key value or field key name.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

Example

The following example shows how to use WebtFieldSet.

WebtConnection connection = new WebtConnection("localhost", 8888);
WebtRemoteService service = new WebtRemoteService("FIELDSET_TEST", connection);
// Create a WebtFieldSet object with the BT_FIELD type WebtBuffer.
WebtFieldSet sndset = new WebtFieldSet(service.createFieldBuffer());

// Add a field data element to WebtBuffer with WebtFieldSet.
sndset.add("STRING1", "hello!");
// Invoke tpcall
WebtBuffer rcvbuf = service.tpcall(sndset.getFieldBuffer());

// Create a WebtFieldSet object with WebtBuffer received from Tmax.
// The buffer type of rcvbuf must be BT_FIELD.
WebtFieldSet rcvset = new WebtFieldSet(rcvbuf);

// Get field data whose field type received from Tmax server is INT1.
int value1 = rcvset.getInt("INT1").intValue();

// Convert and get the second field data whose field type received from Tmax server is INT1
// as a string.
String value2 = rcvset.getString("INT1");
...

5.4. WebtField

WebtField is an abstract class that manages multiple data elements (WebtFieldElement), each corresponding to field keys and their values used in a field-type buffer.

To get an WebtField object for a certain field key, the BufferAccess.createField(int), BufferAccess.createField(String), BufferAccess.getField(int), or BufferAccess.getField(String) methods must be used. The buffer type of WebtBuffer must be WebtBuffer.BT_FIELD.

Constructor

Creates a WebtField object.

The following describes the WebtField constructor class:

  • Prototype

    WebtField()
Method

The following is a list of methods of the WebtField class:

  • public void add(<any type> value)

    • Converts a value to a field key type and adds it. If the value is NULL, it will be ignored and not added.

    • Parameter

      Parameter Description

      value

      Data to add as a field key type.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public void insert(<any type> value)

    • Converts a value to a field key type and inserts it. If the value is NULL, it will be ignored and not inserted.

    • Parameter

      Parameter Description

      value

      Data to insert as a field key type.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public WebtFieldElement get()

    • Deletes the first data and return it.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public WebtFieldElement remove()

    • Removes the 0th value in the specified field type buffer.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • Object[ ] getAll()

    • Returns all data elements in WebtFieldElement[ ].

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public String getDefaultCharset()

    • Returns a character set that was used to convert data in a WebtField object into a string type, or string type data into a byte[ ].

  • public java.util.Enumeration getFieldEnumeration()

    • Returns all data elements as an enumeration type of a WebtFieldElement.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public int getFieldKey()

    • Returns the field key value of a WebtField object.

  • public int getFieldType()

    • Returns the field key type of a WebtField object.

  • public java.util.Vector getFieldVector()

    • Returns all data elements as a vector type of a WebtFieldElement.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public boolean isNumericType()

    • Checks if the field key of a WebtField object is a numeric type.

  • public void removeAll()

    • Deletes all data.

  • public void replace(<any type> value, int index)

    • Replaces the value at the specified index with the given value converted to the specified field type. If the value is NULL, it is ignored.

    • Parameter

      Parameter Description

      value

      Data to replace. If the data type is not Byte, Short, Integer, Long, Float, Double, or String, then replace(value.toString(), index) is executed.

      index

      Position of the field data element to be replaced.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public void setDefaultCharset(String charset)

    • Sets the character set used to convert data in the WebtField object from a string to a byte[] array and vice versa. If not explicitly set, the character set specified by WebtRemoteService is used.

    • Parameter

      Parameter Description

      charset

      Character set to use.

  • public int size()

    • Returns the number of stored data.

  • public java.lang.String toString()

    • Displays the content of a field as a string that the user can read. It functions similarly to fbprint( ) provided by Tmax.

Example

The following example shows how to use the WebtField class:

WebtConnection connection = new WebtConnection("localhost", 8888);
WebtRemoteService service = new WebtRemoteService("TEST", connection);
WebtBuffer fieldBuf = service.createFieldBuffer();

// Create a WebtField object whose field key value is INT1.
WebtField field1 = fieldBuf.createField(INT1);

// Create a WebtField object whose field key name is "INT2".
WebtField field2 = fieldBuf.createField("INT2");

// Add data to the created WebtField object.
field1.add("1");
field1.add((int)2);
field1.add(123.45);...

// Get the added data from the WebtField object, in order.
int data1 = field1.get().intValue(); // == 1
int data2 = field1.get().intValue(); // == 2
int data3 = field1.get().intValue(); // == 123
...

When adding or inserting new field data with the WebtField.add or WebtField.insert methods, the actual value of the added or inserted data may vary by the field key type and data type. For information about applied rules in such cases, refer to the WebtField.add and WebtField.insert methods. To access field data received from a Tmax server, use the WebtFieldElement method. For more information about data conversion while using the method, refer to WebtFieldElement.

5.5. WebtFieldBuffer

A subclass of WebtBuffer that contains data of the WebtField type.

Constructor

Creates a WebtFieldBuffer object.

The following describes the WebtFieldBuffer class constructor:

  • Prototype

    WebtFieldBuffer()
Method

The following is a list of methods of the WebtFieldBuffer class:

  • public void clear()

    • Deletes all WebtField objects.

  • public WebtField createField(int fldkey|String fldkeyName)

    • Creates a WebtField object whose field key value is fldkey, and returns it. If there is another WebtField object whose field key value is the same as the value of fldkey, the object will be returned.

    • To create a WebtField object by entering a field key name using fldkeyName, a field key table must first be loaded by using WebtSystem.createDefaultFieldKeyTable(String).

    • Parameter

      Parameter Description

      fldkey

      Field key value for a WebtField object to create.

      fldkeyName

      Field key name of a WebtField object to create.

    • Exception

      Exception Description

      WebtBufferException

      The field key is not valid or not found in the field key table.

  • public WebtField getField(int fldkey|String fldkeyName)

    • Returns a WebtField object with the specified field key value (fldKey) or field key name (fldKeyName). If no such object exists, NULL is returned.

    • Exception

      Exception Description

      WebtBufferException

      The field key is not valid or not found in the field key table.

  • public java.util.Vector getFieldKeyNames()

    • Returns a list of field keys in strings. The field keys are retrieved from the field key table generated by WebtSystem.createDefaultFieldKeyTable(String).

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public java.util.Vector getFields()

    • Returns a vector of WebtField objects, sorted in the order in which they were created.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public WebtField removeField(int fldkey)

    • Removes the WebtField object whose field key value matches the specified fldkey. Returns NULL if no matching WebtField object is found.

    • Exception

      Exception Description

      WebtBufferException

      An error occurred while using the buffer that receives Tmax services (WebtBuffer).

  • public WebtField removeField(String fldkeyName)

    • Removes the WebtField object whose field key name matches the specified fldkeyName. Returns NULL if no matching WebtField object is found.

    • Exception

      Exception Description

      WebtBufferException

      The field key name is not valid or not found in the field key table.

6. Event Message Processing Classes

6.1. WebtEventConnecion

WebtEventConnection is a WebtConnection used to handle event messages(tppost, tpnotify, tpsendtocli, and tpbroadcast) sent from a Tmax server or other clients.

To handle unsolicited messages from the Tmax server or other clients, it is necessary to use WebtEventConnection to connect to the Tmax server. It is also required to implement a WebtEventHandler that defines a callback method to process event messages, and to register an event handler by using the setEventHandler method of the WebtEventHandler.

Constructor

Creates a WebtEventConnection object.

The following describes the WebtEventConnection class constructors:

  • Constructor 1

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort)
    • Parameter

      Parameter Description

      hostAddr

      Creates a WebtEventConnection object used to connect to a Tmax server with the specified hostPort.

      hostPort

      The port number of a main Tmax server.

  • Constructor 2

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort,
                                 boolean doConnect)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates the WebtEventConnection object set to connect to the Tmax server at hostAddr:hostPort.

      hostPort

      The port number of the main Tmax server.

      doConnect

      • TRUE : Attempts to connect to the Tmax server by creating the WebtEventConnection object.

      • FALSE : Does not attempt to the Tmax server while creating the WebtEventConnection.

  • Constructor 3

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort,
                                 boolean doConnect,
                                 int conntimeout)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates a WebtEventConnection object set to connect to the Tmax server with hostPort.

      hostPort

      The port number of the main Tmax server.

      doConnect

      • TRUE : Attempts to connect to the Tmax server by creating the WebtEventConnection object. If connection is not set within the timeout period, an exception (tperrno = TPETIME) is thrown.

      • FALSE : Does not attempt to the Tmax server while creating the WebtEventConnection.

      conntimeout

      The timeout period for connection setting. (Unit: seconds)

  • Constructor 4

    • Prototype

      public WebtEventConnection(String hostAddr,
                                int hostPort,
                                int conntimeout)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates a WebtEventConnection object set to connect to the Tmax server at hostAddr:hostPort. If connection is not set within the timeout period, an exception (tperrno = TPETIME) is thrown.

      hostPort

      The port number of the main Tmax server.

      conntimeout

      The timeout period for connection setting. (Unit: seconds)

  • Constructor 5

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort,
                                 String backupAddr,
                                 int backupPort)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates a WebtEventConnection object set to connect to the Tmax server at hostPort. If the connection fails, it reattempts the connection using backupAddr:backupPort.

      hostPort

      The port number of the main Tmax server.

      backupAddr

      The IP address of a backup Tmax server.

      backupPort

      The port number of a backup Tmax server.

  • Constructor 6

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort,
                                 String backupAddr,
                                 int backupPort,
                                 boolean doConnect,
                                 int conntimeout)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates a WebtEventConnection object set to connect to the Tmax server at hostPort. If the connection to hostAddr:hostPort fails, it reattempts the connection using backupAddr:backupPort.

      If doConnect is set to FALSE, it does not attempt to connect to the server.

      If connection is not set within the timeout period, an exception (tperrno = TPETIME) is thrown.

      hostPort

      The port number of a main Tmax server.

      backupAddr

      The IP address of a backup Tmax server.

      backupPort

      The port number of a backup Tmax server.

      doConnect

      If set to TRUE, it attempts to connect to the Tmax server by creating a WebtEventConnection object.

      conntimeout

      The timeout period for connection setting. (Unit: seconds)

  • Constructor 7

    • Prototype

      public WebtEventConnection(String hostAddr,
                                 int hostPort,
                                 String username,
                                 String userpwd,
                                 String domainname,
                                 String domainpwd)
    • Parameter

      Parameter Description

      hostAddr

      The IP address of the main Tmax server. Creates a WebtEventConnection object set to connect to the Tmax server at hostPort. The authentication information provided as a parameter during connection configuration is used to perform the authentication process.

      The connection is successfully established if the provided information matches the username, userpwd, domainname, and domainpwd values configured on the Tmax server.

      username

      User name for the authentication account.

      userpwd

      User password.

      domainname

      Client name.

      domainpwd

      Security password for system access.

  • Exception

    Exception Description

    WebtIOException

    A network error occurred while initiating the connection. As a result, the connection to hostAddr:hostPort and backupAddr:backupPort failed, or the connection could not be established within the timeout period.

    WebtServiceException

    An interrupt occurred while executing socket connection.

Method

The following is a list of methods of the WebtEventConnection class:

  • public boolean close()

    • Closes a socket connection to Tmax. If the connection is managed by the connection pool, the connection will not be closed, and it will be returned to the pool for reuse.

  • public void setEventHandler(WebtEventHandler event [,int qlen])

    • Registers a handler to process event messages.

    • Parameter

      Parameter Description

      event

      A handler to process incoming event messages.

      qlen

      The size of the internal queue that will store event messages. (Default value: 2)

      If there are no available slots in the queue, the oldest messages will be discarded.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      The queue size is 0, or an interrupt occurred while executing socket connection.

  • public void setEventMask(int mask)

    • Selects a message from event messages transmitted by tpbroadcast(), tppost(), tpsendtocli(), and tpnotify().

    • Parameter

      Parameter Description

      mask

      A value combining WebtEventMask.EVENT_BROADCAST, WebtEventMask.EVENT_POST, WebtEventMask.EVENT_SENDTOCLI, and WebtEventMask.EVENT_NOTIFY using the OR ( | ) operator.

      To receive and pass a message, mask must be on. If this function is not performed, the default value is WebtEventMask.EVENT_NONE(0) and no message will be returned. If WebtEventMask.EVENT_ALL is set, all event messages will be returned.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      An incorrect parameter was provided.

  • void tpsubscribe(String eventName [,WebtAttribute attr])

    • Subscribes to a post group to receive tppost() messages.

    • Parameter

      Parameter Description

      eventName

      Name of the post group to receive tppost() messages.

      attr

      Attribute to apply to perform a tpsubscribe(). Currently, no meaningful flags are defined.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      The eventName is too long, or an interrupt occurred.

  • void tpunsubscribe(String eventName [,WebtAttribute attr])

    • Withdraws from a registered post group to stop receiving tppost messages.

    • Parameter

      Parameter Description

      eventName

      Name of the post group from which to withdraw.

      attr

      Attribute to apply to perform a tpunsubscribe. Currently, no meaningful flags are defined.

    • Exception

      Exception Description

      WebtIOException

      A network error occurred.

      WebtServiceException

      An interrupt occurred.

Example

The following is an example of using an event handler to receive tppost messages:

import tmax.webt.*;

public class EventSample implements WebtEventHandler {
    private WebtEventConnection connection;
    public EventSample(WebtEventConnection connection) {
          this.connection = connection;

        // Set a mask to receive tpbroadcast events only.
        connection.setEventMask(WebtEventConnection.EVENT_POST);

        // Register an event handler.
        connection.setEventHandler(this);

        // Subscribe to the event.
        connection.tpsubscribe("posttest");
    }

    public void destroy() {
        connection.tpunsubscribe("posttest");
        connection.close();
    }

    // WebtEventHandler function. When an event message is received, this method is called back.
    public void handleEvent(int type, WebtBuffer buf, int len, int flags) {
         System.out.println("event received. type = " + type + ",
                             buffer type = " + buf.getBufferType());
         System.out.println("event msg : " + buf.getString());
    }

    // WebtEventHandler method. If WebT encounters an exception while processing an event,
    // this method is called back. If WebtIOException is thrown, the connection to Tmax server
    // might be disconnected, and so try to reconnect.
    public void handleError(WebtException e) {
          System.err.println("event error occured");
          e.printStackTrace();
          if (e instanceof WebtIOException) {
              if (e.getTPError() == WebtException.TPECLOSE) {
                  connection.close();
                  connection.connect();
             }
         }
   }
}

6.2. WebtEventHandler

WebtEventHandler is an interface used to process unsolicited messages received from a Tmax server. To receive unsolicited messages, this interface should be implemented. Unsolicited messages include tpsendtocli, tpbroadcast, tpnotify, and tppost acall_reply.

Field
  • static final int ACALLREPLY_TYPE

    • Data received as a response to a tpacall.

  • static final int BROADCAST_TYPE

    • Data transmitted from a tpbroadcast.

  • static final int NOTIFY_TYPE

    • Data transmitted from a tpnotify.

  • static final int POST_TYPE

    • Data transmitted from a tppost.

  • static final int SENDTOCLI_TYPE

    • Data transmitted from a tpsendtocli.

Method

The following is a list of methods of the WebtEventHandler class:

  • void handleError(WebtException e)

    • If an error—typically a network-related one—occurs while handling an unsolicited message, the handleError method is invoked.

    • Parameter

      Parameter Description

      e

      Exception object.

  • void handleEvent(int type, WebtBuffer buf, int len, int flags)

    • When receiving an unsolicited message selected by WebtEventConnection.setEventMask(int), this handleEvent method is invoked.

    • Parameter

      Parameter Description

      type

      One of the following: POST_TYPE, BROADCAST_TYPE, NOTIFY_TYPE, SENDTOCLI_TYPE, ACALLREPLY_TYPE.

      buf

      WebtBuffer containing the content of the unsolicited message.

      len

      Length of the unsolicited message.

      flags

      Flags value set on the unsolicited message.

7. Other Classes

7.1. WebtTransaction

The WebtTransaction class provides APIs for processing multiple services as a single unit of work and managing exceptions that occur during execution.

Constructor

Creates a WebtTransaction object.

The following describes the WebTransaction class constructor:

  • Prototype

    public WebtTransaction(WebtConnection conn)
  • Parameter

    Parameter Description

    conn

    WebtConnection object for transaction.

Method

The following is a list of methods of the WebtTransaction class:

  • public int begin()

    • Begins a global transaction. It performs the same function as an int tx_begin( ), which is a TX function.

    • Exception

      Exception Description

      WebtTXException

      A transaction is already in progress.

  • public int commit()

    • Commits a global transaction. It performs the same function as an int tx_commit(), which is a TX function.

    • Exception

      Exception Description

      WebtTXException

      The transaction may not have started, a network error may have occurred, or a transaction-related error may have been returned by the Tmax server.

  • public int rollback()

    • Rolls back a global transaction. It performs the same function as int tx_rollback(), which is a TX function.

    • Exception

      Exception Description

      WebtTXException

      The transaction may not have started (using tx_begin), a network error may have occurred, or a transaction-related error may have been returned by the Tmax server.

  • public int getBlockTimeout()

    • Returns the timeout value to apply when calling commit and rollback methods.

  • int getTimeout()

    • Returns the timeout value for transactions.

  • public boolean isChained()

    • Returns TRUE/FALSE depending on whether chain control has been obtained.

      Return Value Description

      TRUE

      TX_CHAINED is set.

      FALSE

      TX_UNCHAINED is set.

  • public void setBlockTimeout(int timeout)

    • Sets the timeout value to apply when calling commit and rollback methods.

    • Parameter

      Parameter Description

      timeout

      Timeout period. (Unit: milliseconds)

  • public void setChained(boolean value)

    • Performs a chain control.

    • Parameter

      Parameter Description

      value

      Chain control value.

      • TRUE : Performs the same function as a int tx_set_transaction_control(TX_CHAINED), which is a TX method.

      • FALSE : Performs the same function as a int tx_set_transaction_control(TX_UNCHAINED), which is a TX method.

  • public void setTimeout(int timeout)

    • Sets the timeout for transactions. If the timeout period is not explicitly specified using the setTimeout function, the value defined with TXTIME in the Tmax configuration file will be used.

    • Parameter

      Parameter Description

      timeout

      Timeout period. (Unit: seconds)

For more information about TX functions, refer to "Tmax Application Development Guide".

7.2. WebtSystem

The WebtSystem class manages system information such as the WebT system versions, character sets, and field key tables.

Constructor

Creates a WebtSystem object.

The following describes the WebtSystem class constructor:

  • Prototype

    public WebtSystem()
Method

The following is a list of WebtSystem class methods:

  • public static void createDefaultFieldKeyTable(String fdlfile)

    • Creates a field key table.

    • Parameter

      Parameter Description

      fdlfile

      Path to the fdl file.

    • Exception

      Exception Description

      java.io.IOException

      The fdl file cannot be found or an error occurred while reading the file.

  • public static String getDefaultCharset()

    • Returns the default character set of the WebT system.

  • public static WebtFDLKeyTable getDefaultFieldKeyTable()

    • Returns the default field key table.

  • public static void main(String[ ] argv)

    • Prints the WebT version information to standard output when executing WebtSystem.

  • public static void setDefaultCharset(String charset)

    • Sets the default character set to use in WebT.

    • If no character set is specified when creating a WebtService or WebtRemoteService object, the value specified using the setDefaultCharset method is used by default.

    • Parameter

      Parameter Description

      charset

      Default character set.

  • public static String version()

    • Returns the WebT version.