Overview of Guaranteed Delivery
Overview
This chapter explains what guaranteed delivery is, how to indicate that you want to use guaranteed delivery services from a client application (an Integration Server or standalone Java program) or from another service, how to customize Job Managers to manage guaranteed delivery transactions, what determines how long transactions remain active, and how errors are handled.
What Is Guaranteed Delivery?
Guaranteed delivery is a facility of webMethods Integration Server that ensures guaranteed, one-time execution of services. It protects transactional requests from transient failures that might occur on the network, in the client, or on the server.
A transient failure is a failure that can correct itself within a specified period of time. If a request cannot be delivered to the server due to a transient failure, the request is resubmitted. If the problem corrected itself, the request is successfully delivered on a subsequent attempt. You can determine what constitutes a transient error by specifying a time-to-live (TTL) period for a guaranteed delivery transaction and, optionally, the number of times a transaction should be retried. If you do not specify the TTL or retry value, the configured defaults are used.
You can use guaranteed delivery when you invoke a service from a client or from within another service.
Indicating You Want to Use Guaranteed Delivery
To invoke services using guaranteed delivery from either a client application or another service use the class watt.client.TContext (TContext) that is part of the Client API. Similar to the standard class watt.client.Context (Context), you use TContext to request that webMethods Integration Server execute a service. However, the server performs guaranteed delivery functions when a client application or service requests services through TContext.
How Transactions Are Managed
Guaranteed delivery transactions are managed by Job Managers. For client applications, the Job Manager runs on the client. For services, the Job Manager runs on the server.
The Job Managers manage all guaranteed delivery transactions that a process creates using TContext. The Job Managers maintain a job store of the guaranteed delivery transactions. The job store contains a record for each transaction. In addition, the Job Managers maintain a log that tracks the progress of all transaction operations.
The Job Manager handles the invocation of the service using background threads, which the Job Manager allocates from a configurable pool of threads. The Job Manager sends the service requests to a webMethods Integration Server and accepts the results on behalf of the client applications or services that use TContext. If the Job Manager does not receive a result for a transaction in its job store, it resubmits that request to execute the service. It continues to resubmit requests until it either receives a result or the transaction expires.
Customizing the Job Manager
You can customize how the Job Manager manages guaranteed delivery transactions programmatically or through system properties. To specify programmatically, your client application must specify the setting with the parameters of TContext methods. To specify through system parameters, specify the setting on the Java command line.
-
Location of the
client transaction log. Specify the file in which the Job Manager
maintains its log of all the guaranteed delivery transaction operations for
clients that are standalone Java programs.
Tcontext Method: Specify using a parameter with the init method. System Property: Use the –Dwatt.tx.logfile =filename option. If a parameter is supplied to the TContext.init method and watt.tx.logfile is set, the value in watt.tx.logfile is used. If neither is set, the default is .\tx.log. -
Submission
interval for the Job Store. Specify the number of seconds between sweeps
of the job store. The Job Manager sweeps the job store to submit transactions
to a
webMethods Integration Server.
TContext Method: Cannot specify using a TContext method. System Property: Use the -Dwatt.tx.sweepTime=seconds option.The default is: 60 seconds
-
Time to Retry Interval. Specify the number of seconds
to wait after a service request failure before the Job Manager resubmits the
request to
webMethods Integration Server.
TContext Method: Cannot specify using a TContext method. System Property: Use the -Dwatt.tx.retryBackoffTime=seconds option.The default is: 60 seconds
-
Number of Client
Threads in Thread Pool. Specify the number of threads you want to make
available in a thread pool to service pending requests.
TContext Method: Cannot specify using a TContext method. System Property: Use the -Dwatt.tx.jobThreads.The default is: 5 threads
Identifying Transactions
It is the responsibility of the client application or service to obtain a transaction ID (tid) for each guaranteed delivery request and to specify the transaction ID with each subsequent request for the transaction.
The client application or service obtains the transaction ID from webMethods Integration Server using the startTx( ) method, which is used to start a guaranteed delivery transaction. See Creating a Java Client that Uses Guaranteed Delivery and Creating a Flow Service that Uses Guaranteed Delivery for additional instructions and sample code.
Specifying How Long Transactions Are Active
A guaranteed delivery transaction has two attributes that determine how long it stays active: the time-to-live (TTL) and the retry limit. The TTL specifies the number of minutes that a transaction is to remain active. The retry limit specifies the maximum number of times that the Job Manager is to resubmit a request. A transaction becomes inactive when the TTL or the retry limit (if specified) is reached, whichever comes first. When a transaction becomes inactive, it remains in the job store, but the Job Manager no longer attempts to submit the request.
The client application or service sets the TTL (and optionally, the retry limit) with the startTx () method, which it uses to start a guaranteed delivery transaction. See Creating a Java Client that Uses Guaranteed Delivery and Creating a Flow Service that Uses Guaranteed Delivery for additional instructions and sample code.
These values determine the degree of tolerance the client application or service has towards transient network and server errors that occur at run time. Specifically, they determine the length of the outage that the client application or service considers transient. An outage that exceeds these limits will be deemed unrecoverable by the Job Manager and will cause the Job Manager to return an error for the request.
Handling Failures
If a non-transient error prevents your client application or service from receiving the results from a service request, your application will receive an error message.
Records remain in the job store for a transaction until the client application or service explicitly ends the transaction. To avoid exhausting the job store, a client application or service must make sure to complete all the transactions it starts, or a site must establish administrative procedures to address failed jobs.
- AccessException. The client application or service either supplied invalid credentials or is denied access to the requested service.
- ServiceException. The service encountered an execution error.
-
DeliveryException. The Job Manager failed and became
disabled. An administrator should be notified to correct this problem. For
client applications, code your client application to notify an administrator
when this type of error occurs. After the problem is corrected, re-enable the
Job Manager using the TContext.resetJobMgr( ) method.
For services, guaranteed delivery notifies the administrator identified by the watt.server.txMail configuration setting. After the problem is corrected, re-enable the Job Manager by executing the pub.tx:resetOutbound service.
- IllegalRequestException. The client application or service made an invalid request; for example, supplied an invalid transaction ID (tid) or other invalid parameter.
-
TXException. A
failure occurred with the transaction. The transaction timed out, hit the retry
limit, or encountered a heuristic error. Typically, this type of error
indicates that the transaction became inactive either because the time-to-live
(TTL) value elapsed or the retry limit was met. To distinguish between these
two errors, use the isExceededRetries( ) method.
Heuristic errors will only occur if you altered the default configuration of webMethods Integration Server to fail PENDING requests when webMethods Integration Server is restarted after a failure. Use the isHeuristicFailure( ) method to determine if a heuristic error occurred.Note: A heuristic error does not guarantee that your transaction was not executed, only that its results could not be returned. Keep this in mind if you are processing transactions that must be executed once and only once (for example, an application that enters purchase orders or pays invoices). You might also need to implement additional mechanisms in your client application or service to ensure that a transaction does not get posted twice.