com.wm.app.b2b.client

Class TContext

java.lang.Object

com.wm.app.b2b.client.BaseContext

com.wm.app.b2b.client.TContext

All Implemented Interfaces:

Codable

public class TContext
extends BaseContext
implements Codable

This class extends BaseContext. You use the members of this class to build clients that invoke services on a webMethods Integration Server via the guaranteed-delivery facility. This facility ensures that a request reaches the Integration Server, it is processed once and only once, and its results are returned to the client, despite any transient errors that may occur on the network or the server.

You may chain transactions to build a sequence in which each transaction waits until the preceding transaction executes.

Requests submitted through TContext are handled by an intermediary called the "Job Manager." The Job Manager is a process that submits requests to the server on behalf of a client (there is a single Job Manager that handles the requests for all TContext objects running within the same process). If a request cannot be delivered because the network or server is down, the Job Manager automatically resubmits the request until it is successfully delivered to the server or the request's time-to-live (TTL) or retry parameters are exceeded. (Transactions are specified with a TTL, after which they expire. A retry-limit may also be specified, in which case the transaction expires after the specified number of retries are attempted or the TTL elapses, whichever comes first.)

The Job Manager handles service job invocations via background threads. It allocates threads from a pool, whose size you can configure via the watt.tx.jobThreads system property.

The Job Manager manages its transactions the job store. The job store is a directory in which the Job Manager maintains a record of its active transactions. A transaction record includes information such as status, input data, connection parameters, and so forth. Transaction records are XML-encoded so they can be easily viewed and understood by an administrator.

Transaction operation results are appended to a job log, which can be specified as a file name, an OutputStream, or a Writer if Unicode support is required.

Individual transactions are referenced by transaction ID (TID). A client must start a transaction and obtain a TID before it can invoke a service through the Job Manager.

With TContext, services can be invoked in two ways: using the invoke method or using the submitTx and retrieveTx methods. invoke is a synchronous method that blocks until the request's results are returned or the request expires. submit and retrieve are methods that allow a client to process requests asynchronously--first, you invoke the service with submitTx and then, at some later point, you pick up its results using retrieveTx.

After a client receives the results of a service, it must end the transaction to clear its transaction record from the job store. Failure to end transactions properly will cause "dead" records to accumulate in the job store, which can, over time, exhaust the storage device.

The following sample shows how you would code a TContext client to process a synchronous transaction:

Note: If you were writing a client to run as a service on a webMethods Integration Server, you WOULD NOT include the TContext.init and TContext.shutdown methods as shown in the following example. These functions are automatically performed by the server, and must not be included in your code.

      TContext tc = null;

      //---Initialization----------------------------------------------------
      //   Initialize TContext and establish connection attributes
      try {
          TContext.init("./jobs", "./tx.log");
          tc = new TContext();
          tc.connect("localhost:5555", null, null);
      } catch (ServiceException e) {
          System.err.println("Error: "+e.getMessage());
          System.exit(-1);
      }

      //---Transaction-------------------------------------------------------
      //   Do work with TContext - get tid, call service, end tid
      try {
          String tid = tc.startTx(3);
          Values out = tc.invokeTx(tid, "wm.server", "ping", new Values());
          System.out.println("out="+out.toString());
          tc.endTx(tid);
      } catch (TXException e) {
          System.err.println("Job Failed: "+e.getMessage());
          System.exit(-1);
      } catch (DeliveryException e) {
          System.err.println("JobMgr Disabled: "+e.getMessage());
          System.exit(-1);
      } catch (AccessException e) {
          System.err.println("Access Denied: "+e.getMessage());
          System.exit(-1);
      } catch (ServiceException e) {
          System.err.println("Error: "+e.getMessage());
          System.exit(-1);
      }

      //---Shutdown----------------------------------------------------------
      //   Release connection and shutdown
      try {
          tc.disconnect();
          TContext.shutdown();
      } catch (ServiceException e) {
          System.err.println("Error: "+e.getMessage());
          System.exit(-1);
      }

The following lists global properties that affect TContext objects and the Job Manager:

Property	Description
watt.tx.logfile	Log file name.
watt.tx.jobdir	Directory for job store.
watt.tx.sweepTime	Background thread processing interval in seconds. Default is 60 seconds.
watt.tx.defaultTTLMins	Default TTL in minutes. Default is 30 minutes.
watt.tx.retryBackOffTime	Backoff interval for job retries in seconds. Default is 60 seconds.
watt.tx.jobThreads	Number of threads available to the Job Manager for processing jobs. Default is 5.

See Also:

BaseContext, Codable

Field Summary

Fields inherited from class com.wm.app.b2b.client.BaseContext

NO_SSL, RPC_BIN, RPC_IDAT, RPC_XML, SSL_128, SSL_40

Constructor Summary

Constructors

Constructor and Description
TContext() Constructs an unconnected TContext and defaults to the binary RPC transport.

Method Summary

Modifier and Type	Method and Description
void	connect(java.lang.String server, java.lang.String user, java.lang.String pass) Defines the connection parameters that the Job Manager will use to submit this TContext object's request to the webMethods Integration Server.
void	disconnect() Resets this TContext object's connection parameters and releases it from the Job Manager.
void	dumpJobs() Prints (to system out) the list of all transaction records in the local job store.
void	endTx(java.lang.String tid) Ends a transaction.
java.lang.String	getChainedTxId(java.lang.String tid) Returns the tid of the transaction to which the specified transaction is chained.
java.lang.String	getRemoteTxId(java.lang.String tid) Returns the remote tid (the tid by which a transaction is referenced on the server) for a specified transaction.
Values	getTxData(java.lang.String tid) Returns the input or output data for the specified transaction.
IData	getTxIData(java.lang.String tid) Returns the input or output data for the specified transaction as an IData object.
java.util.Enumeration	getTxIds() Enumerates the transactions in the job store by transaction ID.
java.lang.String	getTxStatus(java.lang.String tid) Returns the status of a specified transaction as a String.
int	getTxStatusVal(java.lang.String tid) Returns the status of a specified transaction as an int.
static void	init() Initializes the Job Manager using the values specified by the watt.tx.logfile and watt.tx.jobdir properties.
static void	init(java.lang.String jobdir, java.io.OutputStream logstream) Initializes the Job Manager using the specified job store directory (if this value has not already been set with the watt.tx.jobdir property) and OutputStream for logging.
static void	init(java.lang.String jobdir, java.lang.String logfile) Initializes the Job Manager using the specified job store directory and log file, if these values are not values already specified by the watt.tx.logfile and watt.tx.jobdir properties.
static void	init(java.lang.String jobdir, java.io.Writer logWriter) Initializes the Job Manager using the specified job store directory (if this value has not already been set with the watt.tx.jobdir property) and Writer for logging.
IData	invokeTx(java.lang.String tid, java.lang.String ifc, java.lang.String svc, IData data) Calls the specified service through the Job Manager and passes input to that service through an IData object.
Values	invokeTx(java.lang.String tid, java.lang.String ifc, java.lang.String svc, Values data) Calls the specified service through the Job Manager and passes input to that service through a Values object.
static void	resetJobMgr() Restarts the Job Manager if it has become disabled.
static void	resetJobMgr(java.lang.String jobdir, java.lang.String logfile) Restarts the Job Manager with the specified job store directory and log file.
static void	resetJobMgr(java.lang.String jobdir, java.lang.String logfile, java.io.OutputStream logstream) Restarts the Job Manager with the specified job store directory and OutputStream for logging.
static void	resetJobMgr(java.lang.String jobdir, java.lang.String logfile, java.io.Writer logWriter) Restarts the Job Manager with the specified job store directory and Writer for logging.
static void	resetLogFile(java.lang.String logfile) Closes the current job log and opens a new file.
static void	resetLogStream(java.io.OutputStream logstream) Resets the current log stream.
static void	resetLogWriter(java.io.Writer logwriter) Resets the current log writer.
void	restartTx(java.lang.String tid) Restarts a failed transaction.
IData	retrieveIDTx(java.lang.String tid) Gets the results of a service that was invoked with submitTx and returns the results in an IData object.
IData	retrieveIDTx(java.lang.String tid, boolean block) Gets the results of a service that was invoked with submitTx and returns the results in an IData object (blocks or returns as specified if results are not available in the job store).
Values	retrieveTx(java.lang.String tid) Gets the results of a service that was invoked with submitTx and returns the results in a Values object.
Values	retrieveTx(java.lang.String tid, boolean block) Gets the results of a service that was invoked with submitTx and returns the results in a Values object (blocks or returns as specified if results are not available in the job store).
void	setSSLcertificates(java.lang.String privKey, java.lang.String[] certs) Specifies the certificates and keys that will be used to create an SSL connection.
static void	shutdown() Shuts down the Job Manager if there are no active processes using it.
static void	shutdown(boolean force) Shuts down the Job Manager using the specified shut-down behavior.
java.lang.String	startTx() Starts a new transaction with the default time-to-live (TTL) and unlimited retries.
java.lang.String	startTx(long ttl) Starts a new transaction with the specified time-to-live (TTL) value and no retry limit.
java.lang.String	startTx(long ttl, int retries) Starts a new transaction with the specified time-to-live (TTL) and retry values.
java.lang.String	startTx(java.lang.String followTid) Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store.
java.lang.String	startTx(java.lang.String followTid, long ttl) Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store, using the specified time-to-live (TTL) value.
java.lang.String	startTx(java.lang.String followTid, long ttl, int retries) Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store, using the specified time-to-live (TTL) and retry values.
void	submitTx(java.lang.String tid, java.lang.String ifc, java.lang.String svc, IData data) Calls the specified service through the Job Manager and passes input to that service through an IData object.
void	submitTx(java.lang.String tid, java.lang.String ifc, java.lang.String svc, Values data) Calls the specified service through the Job Manager and passes input to that service through a Values object.

Methods inherited from class com.wm.app.b2b.client.BaseContext

getSSLSupport, isClusteredEnv, isConnected, isSecure, isUseJSSE, setAllowRedir, setAuthentication, setFixedUri, setProxy, setRetryServer, setSecure, setSecureProxy, setSSLCertificates, setSSLCertificates, setSSLCertificates, setUseJSSE

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.wm.util.coder.Codable

getValue, getValueKeys, setValue

Constructor Detail

TContext

public TContext()

Constructs an unconnected TContext and defaults to the binary RPC transport.

Method Detail

init

public static void init()
                 throws ServiceException

Initializes the Job Manager using the values specified by the watt.tx.logfile and watt.tx.jobdir properties. This method must be called before constructing any instances of TContext. If init is called more than once, subsequent calls are ignored.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you do not need to call this method. The server itself will initialize the Job Manager at the appropriate times (for example, when the server is started). This is not something that your service needs to do.

Throws:

ServiceException - If the Job Manager cannot be initialized.

init

public static void init(java.lang.String jobdir,
                        java.lang.String logfile)
                 throws ServiceException

Initializes the Job Manager using the specified job store directory and log file, if these values are not values already specified by the watt.tx.logfile and watt.tx.jobdir properties. This method must be called before constructing any instances of TContext. If init is called more than once, subsequent calls are ignored.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you do not need to call this method. The server itself will initialize the Job Manager at the appropriate times (for example, when the server is started). This is not something that your service needs to do.

Parameters:

jobdir - A String specifying the directory in which you want the Job Manager to maintain its job store.

logfile - A String specifying the name of the file in which you want the Job Manager to log guaranteed-delivery transactions.

Throws:

ServiceException - If the Job Manager cannot be initialized.

init

public static void init(java.lang.String jobdir,
                        java.io.Writer logWriter)
                 throws ServiceException

Initializes the Job Manager using the specified job store directory (if this value has not already been set with the watt.tx.jobdir property) and Writer for logging. This method must be called before constructing any instances of TContext. If init is called more than once, subsequent calls are ignored.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you do not need to call this method. The server itself will initialize the Job Manager at the appropriate times (for example, when the server is started). This is not something that your service needs to do.

Parameters:

jobdir - A String specifying the directory in which you want the Job Manager to maintain its job store.

logWriter - The Writer in which you want the Job Manager to log guaranteed-delivery transactions.

Throws:

ServiceException - If the Job Manager cannot be initialized.

init

public static void init(java.lang.String jobdir,
                        java.io.OutputStream logstream)
                 throws ServiceException

Initializes the Job Manager using the specified job store directory (if this value has not already been set with the watt.tx.jobdir property) and OutputStream for logging. This method must be called before constructing any instances of TContext. If init is called more than once, subsequent calls are ignored.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you do not need to call this method. The server itself will initialize the Job Manager at the appropriate times (for example, when the server is started). This is not something that your service needs to do.

Parameters:

jobdir - A String specifying the directory in which you want the Job Manager to maintain its job store.

logstream - The OutputStream in which you want the Job Manager to log guaranteed-delivery transactions.

Throws:

ServiceException - If the Job Manager cannot be initialized.

shutdown

public static void shutdown()

Shuts down the Job Manager if there are no active processes using it. This method will only execute successfully when there are no TContext instances registered with the Job Manager.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you must not call this method. The server itself takes care of shutting down the Job Manager at the appropriate times (for example, when the server is shut down). This is not something that your service should do.

See Also:

shutdown(boolean)

shutdown

public static void shutdown(boolean force)

Shuts down the Job Manager using the specified shut-down behavior.

Note: If your TContext will run as a Java service on a webMethods Integration Server, you must not call this method. The server itself takes care of shutting down the Job Manager at the appropriate times (for example, when the server is shut down). This is not something that your service should do.

Parameters:

force - A boolean specifying whether you want the Job Manager to shut down if instances of TContext are still running against it.

Set force to…	To…
true	Shut down even if instances of TContext are still registered with the Job Manager.
false	Do not shut down if instances of TContext are currently using the Job Manager. Same as shutdown().

See Also:

shutdown()

resetJobMgr

public static void resetJobMgr()
                        throws ServiceException

Restarts the Job Manager if it has become disabled.

This method is not used by ordinary TContext clients. It is provided as a way to restart a Job Manager that has become disabled. You can use this method to restart the Job Manager after correcting the error that caused it to become disabled.

Throws:

ServiceException - If the Job Manager cannot be restarted or because it is already enabled.

resetJobMgr

public static void resetJobMgr(java.lang.String jobdir,
                               java.lang.String logfile)
                        throws ServiceException

Restarts the Job Manager with the specified job store directory and log file.

This method is not used by ordinary TContext clients. It is provided as a way to restart a Job Manager that has become disabled due to some type of failure. You can use this method to restart the Job Manager after correcting the error that caused it to become disabled.

Parameters:

jobdir - A String specifying the directory in which the job store is maintained.

logfile - A String specifying the name of the file in which the Job Manager's log is maintained.

Throws:

ServiceException - If the Job Manager cannot be restarted or because it is already enabled.

resetJobMgr

public static void resetJobMgr(java.lang.String jobdir,
                               java.lang.String logfile,
                               java.io.OutputStream logstream)
                        throws ServiceException

Restarts the Job Manager with the specified job store directory and OutputStream for logging.

This method is not used by ordinary TContext clients. It is provided as a way to restart a Job Manager that has become disabled due to some type of failure. You can use this method to restart the Job Manager after correcting the error that caused it to become disabled.

Parameters:

jobdir - A String specifying the directory in which the job store is maintained.

logfile - This parameter is not used and must be set to null.

logstream - The OutputStream in which the Job Manager logs guaranteed-delivery transactions.

Throws:

ServiceException - If the Job Manager cannot be restarted or because it is already enabled.

resetJobMgr

public static void resetJobMgr(java.lang.String jobdir,
                               java.lang.String logfile,
                               java.io.Writer logWriter)
                        throws ServiceException

Restarts the Job Manager with the specified job store directory and Writer for logging.

This method is not used by ordinary TContext clients. It is provided as a way to restart a Job Manager that has become disabled due to some type of failure. You can use this method to restart the Job Manager after correcting the error that caused it to become disabled.

Parameters:

jobdir - A String specifying the directory in which the job store is maintained.

logfile - This parameter is not used and must be set to null.

logWriter - The Writer in which the Job Manager logs guaranteed-delivery transactions.

Throws:

ServiceException - If the Job Manager cannot be restarted or because it is already enabled.

resetLogFile

public static void resetLogFile(java.lang.String logfile)
                         throws ServiceException

Closes the current job log and opens a new file.

Parameters:

logfile - a String specifying the location of the new job log file.

Throws:

ServiceException - If the job log cannot be reset.

resetLogStream

public static void resetLogStream(java.io.OutputStream logstream)
                           throws ServiceException

Resets the current log stream.

Parameters:

logstream - The OutputStream that will hold the new job log.

Throws:

ServiceException - If the job log cannot be reset.

resetLogWriter

public static void resetLogWriter(java.io.Writer logwriter)
                           throws ServiceException

Resets the current log writer.

Parameters:

logwriter - Output writer for transaction log (in lieu of filename.

Throws:

ServiceException - If the job log cannot be reset.

connect

public void connect(java.lang.String server,
                    java.lang.String user,
                    java.lang.String pass)
             throws ServiceException

Defines the connection parameters that the Job Manager will use to submit this TContext object's request to the webMethods Integration Server. (The parameters established by this method are included as part of a transaction's record in the job store.)

Parameters:

server - A String specifying the server's address in the form hostname:portNumber.

user - A String specifying the user name that is to be used to connect to the Integration Server.

pass - A String specifying the password that is to be used to connect to the Integration Server.

Throws:

ServiceException - If the server name is invalid (for example, null), this TContext object is already connected to a server, or the Job Manager is not initialized.

See Also:

disconnect()

disconnect

public void disconnect()

Resets this TContext object's connection parameters and releases it from the Job Manager.

See Also:

connect(java.lang.String, java.lang.String, java.lang.String)

startTx

public java.lang.String startTx()
                         throws ServiceException

Starts a new transaction with the default time-to-live (TTL) and unlimited retries. You must start a transaction and obtain a transaction ID (tid) before you can invoke a service with the invokeTX or submitTx methods.

Returns:

A String containing the transaction's ID (tid).

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled).

See Also:

startTx(long), startTx(long, int), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

startTx

public java.lang.String startTx(long ttl)
                         throws ServiceException

Starts a new transaction with the specified time-to-live (TTL) value and no retry limit. You must start a transaction and obtain a transaction ID (tid) before you can invoke a service with the invokeTX or submitTx methods.

Parameters:

ttl - A long that specifies this transaction's TTL in minutes. If you specify 0 in ttl, the default TTL is used.

Returns:

A String containing the tid for this transaction.

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled).

See Also:

startTx(long), startTx(long, int), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

startTx

public java.lang.String startTx(long ttl,
                                int retries)
                         throws ServiceException

Starts a new transaction with the specified time-to-live (TTL) and retry values. You must start a transaction and obtain a transaction ID (tid) before you can invoke a service with the invokeTX or submitTx methods.

Parameters:

ttl - A long that specifies this transaction's TTL in minutes. If you set ttl to 0, the default TTL is used.

retries - An int specifying this transaction's maximum retry limit.

Returns:

A String containing the tid for this transaction.

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled).

See Also:

startTx(), startTx(long), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

startTx

public java.lang.String startTx(java.lang.String followTid)
                         throws ServiceException

Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store. When you start a transaction with this method, the Job Manager does not submit this transaction to the server until the transaction to which it is chained is finished (i.e., its status is set to DONE). You use this method to start transactions that need to be processed in order.

Parameters:

followTid - A String specifying the tid upon whose completion this transaction is dependent.

Returns:

A String containing the tid for this transaction.

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled) or the transaction specified in followTid does not exist.

See Also:

startTx(), startTx(long), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

startTx

public java.lang.String startTx(java.lang.String followTid,
                                long ttl)
                         throws ServiceException

Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store, using the specified time-to-live (TTL) value. When you start a transaction with this method, the Job Manager does not submit this transaction to the server until the transaction to which it is chained is finished (i.e., its status is set to DONE). You use this method to start transactions that need to be processed in order.

Parameters:

followTid - A String specifying the tid upon whose completion this transaction is dependent.

ttl - A long that specifies this transaction's TTL in minutes. If you specify 0 in ttl, the default TTL is used.

Returns:

A String containing the tid for this transaction.

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled) or the transaction specified in followTid does not exist.

See Also:

startTx(long), startTx(String), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

startTx

public java.lang.String startTx(java.lang.String followTid,
                                long ttl,
                                int retries)
                         throws ServiceException

Starts a new transaction that is chained to (i.e., dependent on the completion of) a specified transaction in the job store, using the specified time-to-live (TTL) and retry values. When you start a transaction with this method, the Job Manager does not submit this transaction to the server until the transaction to which it is chained is finished (i.e., its status is set to DONE). You use this method to start transactions that need to be processed in order.

Parameters:

followTid - A String specifying the tid upon whose completion this transaction is dependent.

ttl - A long that specifies this transaction's TTL in minutes. If you specify 0 in ttl, the default TTL is used.

retries - An int specifying this transaction's maximum retry limit.

Returns:

A String containing the tid for this transaction.

Throws:

ServiceException - If the transaction cannot be started (for example, if the Job Manager has been disabled) or the transaction specified in followTid does not exist.

See Also:

startTx(String), startTx(String, long), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

invokeTx

public IData invokeTx(java.lang.String tid,
                      java.lang.String ifc,
                      java.lang.String svc,
                      IData data)
               throws ServiceException

Calls the specified service through the Job Manager and passes input to that service through an IData object.

When you invoke a service using this method, the request is processed synchronously--that is, the client blocks until the results of the service are returned. If you want to process the service request asynchronously, use the submitTx and retrieveTx methods instead.

Note: You must establish a connection and start a transaction before calling this method.

Parameters:

tid - A String specifying the transaction under which this request is being submitted. (This is the tid you received when you started the transaction with startTx.)

ifc - A String specifying the name of the folder in which the requested service resides.

svc - A String specifying the name of the service.

data - An IData object containing the input data for the service.

Returns:

An IData object containing the output from the service.

Throws:

ServiceException - If the Job Manager is not initialized or the transaction fails.

See Also:

connect(String, String, String), startTx(String), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(java.lang.String)

invokeTx

public Values invokeTx(java.lang.String tid,
                       java.lang.String ifc,
                       java.lang.String svc,
                       Values data)
                throws ServiceException

Calls the specified service through the Job Manager and passes input to that service through a Values object.

When you invoke a service using this method, the request is processed synchronously--that is, the client blocks until the results of the service are returned. If you want to process the service request asynchronously, use the submitTx and retrieveTx methods instead.

Note: You must establish a connection and start a transaction before calling this method.

Parameters:

tid - A String specifying the transaction under which this request is being submitted. (This is the tid you received when you started the transaction with startTx.)

ifc - A String specifying the name of the folder in which the requested service resides.

svc - A String specifying the name of the service.

data - A Values object containing the input data for the service.

Returns:

A Values object containing the output from the service.

Throws:

ServiceException - If the Job Manager is not initialized or the transaction fails.

See Also:

invokeTx(String, String, String, IData), connect(String, String, String), startTx(String), submitTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData), retrieveTx(String), retrieveIDTx(String)

submitTx

public void submitTx(java.lang.String tid,
                     java.lang.String ifc,
                     java.lang.String svc,
                     IData data)
              throws ServiceException

Calls the specified service through the Job Manager and passes input to that service through an IData object. Unlike invokeTx, this method calls the service asynchronously. That is, it submits the request to the Job Manager and immediately returns to the client. It does not wait to receive the results of the service. To obtain the results from this request, you use the retrieveTx method.

Note: You must establish a connection and start a transaction before calling this method.

Parameters:

tid - A String specifying the transaction under which this request is being submitted. (This is the tid you received when you started the transaction with startTx.)

ifc - A String specifying the name of the folder in which the requested service resides.

svc - A String specifying the name of the service.

data - An IData object containing the input data for the service.

Throws:

ServiceException - If the request is not accepted by the Job Manager (for example, a hardware problem occurs while accessing the job store or the Job Manager is disabled).

See Also:

submitTx(String, String, String, Values), retrieveTx(String), retrieveIDTx(String), connect(String, String, String), startTx(String), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData)

submitTx

public void submitTx(java.lang.String tid,
                     java.lang.String ifc,
                     java.lang.String svc,
                     Values data)
              throws ServiceException

Calls the specified service through the Job Manager and passes input to that service through a Values object. Unlike invokeTx, this method calls the service asynchronously. That is, it submits the request to the Job Manager and immediately returns to the client. It does not wait to receive the results of the service. To obtain the results from this request, you use the retrieveTx method. You must establish a connection with the connect parameter and then start a transaction with one of the startTx parameters before calling this method.

Parameters:

tid - A String specifying the transaction under which this request is being submitted. (This is the tid you received when you started the transaction with startTx.)

ifc - A String specifying the name of the folder in which the requested service resides.

svc - A String specifying the name of the service.

data - A Values object containing the input data for the service.

Throws:

ServiceException - If the request is not accepted by the Job Manager (for example, a hardware problem occurs while accessing the job store or the Job Manager is disabled).

See Also:

submitTx(String, String, String, IData), retrieveTx(String), retrieveIDTx(String), connect(String, String, String), startTx(String), invokeTx(java.lang.String, java.lang.String, java.lang.String, com.wm.data.IData)

retrieveTx

public Values retrieveTx(java.lang.String tid)
                  throws ServiceException

Gets the results of a service that was invoked with submitTx and returns the results in a Values object. If the results of the service have not yet been received by the Job Manager, the method blocks until the Job Manager receives them (that is, the client waits until the results are returned).

Parameters:

tid - A String specifying the transaction whose results you want to obtain.

Returns:

A Values object containing the output from the service.

Throws:

ServiceException - If the transaction fails, the Job Manager is disabled, or the invoked service returned an exception.

retrieveIDTx

public IData retrieveIDTx(java.lang.String tid)
                   throws ServiceException

Gets the results of a service that was invoked with submitTx and returns the results in an IData object. If the results of the service have not yet been received by the Job Manager, the method blocks until the Job Manager receives them (that is, the client waits until the results are returned).

Parameters:

tid - A String specifying the transaction whose results you want to obtain.

Returns:

An IData object containing the output from the service.

Throws:

ServiceException - If the transaction fails, the Job Manager is disabled, or the invoked service returned an exception.

retrieveTx

public Values retrieveTx(java.lang.String tid,
                         boolean block)
                  throws ServiceException

Gets the results of a service that was invoked with submitTx and returns the results in a Values object (blocks or returns as specified if results are not available in the job store).

Parameters:

tid - A String specifying the transaction whose results you want to obtain.

block - A boolean indicating whether you want the method to block or return immediately if the results are not yet available.

Set block to…	To…
true	Block processing until the results are available. When you use this option, the client does not continue until the results are returned.
false	Return if the results are not available.

Returns:

A Values object containing the output from the service or null if block is set to false and the results from the service have not yet been received.

Throws:

ServiceException - If the transaction fails, the Job Manager is disabled, or the invoked service returns an exception.

retrieveIDTx

public IData retrieveIDTx(java.lang.String tid,
                          boolean block)
                   throws ServiceException

Gets the results of a service that was invoked with submitTx and returns the results in an IData object (blocks or returns as specified if results are not available in the job store).

Parameters:

tid - A String specifying the transaction whose results you want to obtain.

block - A boolean indicating whether you want the method to block or return immediately if the results are not yet available.

Set block to…	To…
true	Block processing until the results are available. When you use this option, the client does not continue until the results are returned.
false	Resume processing even if the results are not available.

Returns:

An IData object containing the output from the service or null if block is set to false and the results from the service have not yet been received.

Throws:

ServiceException - If the transaction fails, the Job Manager is disabled, or the invoked service returns an exception.

endTx

public void endTx(java.lang.String tid)
           throws ServiceException

Ends a transaction. This action clears the transaction's record from the job store.

Parameters:

tid - A String specifying the transaction that you want to end.

Throws:

ServiceException - If the specified transaction cannot be ended (for example, the Job Manager is disabled).

restartTx

public void restartTx(java.lang.String tid)
               throws ServiceException

Restarts a failed transaction.

Parameters:

tid - A String specifying the transaction that you want to restart.

Throws:

ServiceException - If the transaction cannot be restarted (for example, if the tid is invalid).

getTxIds

public java.util.Enumeration getTxIds()
                               throws ServiceException

Enumerates the transactions in the job store by transaction ID.

Returns:

An Enumeration containing the transaction IDs in the job store.

Throws:

ServiceException - If the transactions cannot be enumerated (for example, if the Job Manager is disabled).

getTxStatus

public java.lang.String getTxStatus(java.lang.String tid)
                             throws ServiceException

Returns the status of a specified transaction as a String.

Parameters:

tid - A String specifying the transaction whose status you want returned.

Returns:

A String indicating the transaction's status as follows:

Returns…	If…
NEW	The transaction has just been started, but no request has been submitted to it yet. (i.e., the client has been given a tid, but has not issued an invoke or a submit.)
PENDING	The transaction is waiting to be processed by a webMethods Integration Server (i.e., the client has issued an invoke or a submit against the transaction, but the results from the request have not yet been received.)
DONE	The transaction has been processed by a webMethods Integration Server and its results are in the job store.
FAILED	The transaction failed as a result of a heuristic failure or exceeding the TTL or the retry limit.
UNKNOWN	The transaction does not exist in the job store

Throws:

ServiceException - If status cannot be obtained (for example, if the Job Manager is disabled).

See Also:

getTxStatusVal(String)

getTxStatusVal

public int getTxStatusVal(java.lang.String tid)
                   throws ServiceException

Returns the status of a specified transaction as an int.

Parameters:

tid - A String specifying the transaction whose status you want returned.

Returns:

an integer representing the transaction’s status as follows.

Returns…	If…
TXJob.NEW	The transaction has just been started, but no request has been submitted to it yet. (i.e., the client has been given a tid, but has not issued an invoke or a submit.)
TXJob.PENDING	The transaction is waiting to be processed by a webMethods Integration Server (i.e., the client has issued an invoke or a submit against the transaction, but the results from the request have not yet been received.)
TXJob.DONE	The transaction has been processed by a webMethods Integration Server and its results are in the job store.
TXJob.FAILED	The transaction failed as a result of a heuristic failure or exceeding the TTL or the retry limit.
TXJob.UNKNOWN	The transaction does not exist in the job store

Throws:

ServiceException - If status cannot be obtained (for example, if the Job Manager is disabled).

See Also:

getTxStatus(String)

getTxIData

public IData getTxIData(java.lang.String tid)
                 throws ServiceException

Returns the input or output data for the specified transaction as an IData object.

Parameters:

tid - A String specifying the transaction whose data you want to obtain.

Returns:

An IData object containing the transaction's input data (if the transaction has not yet been processed) or output data (if the transaction has been processed and its results returned).

Throws:

ServiceException - If the data cannot be obtained (for example, the specified tid does not exist or the Job Manager is disabled).

getTxData

public Values getTxData(java.lang.String tid)
                 throws ServiceException

Returns the input or output data for the specified transaction.

Parameters:

tid - A String specifying the transaction whose data you want to obtain.

Returns:

A Values object containing the transaction's input data (if the transaction has not yet been processed) or output data (if the transaction has been processed and its results returned).

Throws:

ServiceException - If the data cannot be obtained (for example, the specified tid does not exist or the Job Manager is disabled).

getRemoteTxId

public java.lang.String getRemoteTxId(java.lang.String tid)
                               throws ServiceException

Returns the remote tid (the tid by which a transaction is referenced on the server) for a specified transaction. The remote tid is maintained as part of the transaction record in the local job store.

The remote tid is not used by ordinary TContext clients. However, you might use this method if you were building an application for a webMethods administrator who needed to be able to trace a client-side transaction back to a particular record in the Integration Server's job store.

Parameters:

tid - A String specifying the tid of the transaction whose remote tid you want to obtain.

Returns:

A String containing the remote tid associated with the specified transaction. If the specified transaction does not have a remote tid, getRemotTxId returns null.

Throws:

ServiceException - If the remote tid cannot be obtained (for example, the specified tid does not exist or the Job Manager is disabled).

getChainedTxId

public java.lang.String getChainedTxId(java.lang.String tid)
                                throws ServiceException

Returns the tid of the transaction to which the specified transaction is chained. When one transaction is chained to another, the Job Manager does not submit the chained transaction until the one on which it is dependent is finished (i.e., its status is set to DONE).

Parameters:

tid - A String specifying the tid of the transaction that you want to check.

Returns:

A String containing the tid of the transaction upon whose completion the transaction specified in tid is waiting. If the specified transaction is not chained to another transaction, or it is not currently waiting for another transaction to finish, getChainedTxId returns null.

Throws:

ServiceException - If the tid cannot be obtained (for example, the specified tid does not exist or the Job Manager is disabled).

dumpJobs

public void dumpJobs()
              throws ServiceException

Prints (to system out) the list of all transaction records in the local job store.

Throws:

ServiceException - If the list cannot be produced.

setSSLcertificates

public void setSSLcertificates(java.lang.String privKey,
                               java.lang.String[] certs)

Specifies the certificates and keys that will be used to create an SSL connection. When specifying certificates and key files, you can specify their fully-qualified file names or names that are relative to the webMethods home directory. You cannot change the credentials for a transaction after you start it.

Parameters:

privKey - A String specifying the location of the private key that corresponds to the public key in your certificate.

certs - A String [] specifying the locations of all the certificates in your certificate chain. Your certificate must appear as the first element in this array. For example if you own a certificate that has been signed by XYZ' Authority which in turn was signed by Verisign's Authority, your certificate chain is comprised of three certificates: your certificate, XYZ's certificate, and Verisign's certificate. In certs, these must appear in the following order:

• Your certificate (at index 0)
• XYZ's certificate (at index 1)
• Verisign's certificate (at index 2)