Creating a forwarder application

About this task

The Store service provides methods that help obtain the information that a transaction could not be executed, that facilitate the development of a forwarder application that will get this information from the database, and that later process the pending transactions. The forwarder uses the record marks in the store database entries to determine the current status of a transaction and decide if its entry should be deleted from the database if it has already been executed, or sent on to the host for execution. The following is a description of a common forwarder application flow, based on the marks set by the Store service:
  1. The forwarder requests from the JDBCStore service the first record to be forwarded, using the retrieveFirstRecordForForwarding() method. This method returns the first store database entry with the record mark column (DSERECMK) set to "added" or "updated", and sets that column to a new value, retrievedForForwarding.
  2. The forwarder tries to execute the operation in the host.
    1. Normally, the forwarder application works in synchronous mode: that is, it waits for the host response, and if the operation has been successfully executed, the forwarder deletes the operation entry in the store database by calling the deleteRecords(aSearchCriteria) method. As the forwarder knows which record is processing, the search criterion can easily be set to the primary key of the record to be deleted. If the problems with the host continue, it is the forwarder's responsibility to keep this operation information and retry later. One way of doing that is to work with the autoCommit service option set to false; then, the forwarding application can decide to roll back the changes done to the record when it was retrieved for forwarding, and reset the record mark to its original value. If the forwarder deletes the record, it will also have to commit these changes to the database to make them persistent. The next step is to retrieve the next record to be forwarded by calling the retrieveNextRecordForForwarding() method.
    2. Another option for the forwarder application is to go through all the operations in the STORE table without initially deleting the records. The forwarder will get a STORE table record and mark it as retrievedForForwarding. If that operation is successfully executed, the forwarder commits the database changes. If the host does not respond or there is a host error, the forwarder rolls back these changes, and the record stays with an added or updated record mark. In this scenario, a unique delete will be needed after the forwarding application has completed all pending operations in the database; the forwarder will use the JDBCStore deleteAllRetrievedForForwarding() method.

The two figures below show the described flows for the application used for forwarding. The first case is as follows:

Application flow where the forwarder deletes each operation as soon as it is successfully forwarded

The following flow of events corresponds to the numbers in the diagram above:
  1. If the host responds and the received answer is what the forwarder application is expecting, the forwarder deletes the record from the store database and commits the changes. If the response is not what the forwarder is expecting, it can take the appropriate action before deleting, committing, or rolling back the database changes.
  2. If the host does not respond, the forwarder application can roll back the database changes.
  3. In either case, the forwarder continues with the next pending operation stored in the database.

The second case is as follows:

Application flow where the forwarder deletes all operations only at the end

The following flow of events corresponds to the numbers in the diagram above:
  1. If the host responds and the received answer is what the forwarder application is expecting, the forwarder commits the previous database operation. If the response is not what the forwarder is expecting, it can take the appropriate action before committing or rolling back the database changes.
  2. If the host does not respond, the forwarder application can roll back the database changes.
  3. In either case, the forwarder continues with the next pending operation stored in the database.
  4. At the end, all records marked as retrieved for forwarding are deleted from the database.

See Manual Forwarding and Manual Forwarding implementation for the sample implementations provided. Because these realizations assume that the host is online, an actual implementation will need to include a check for host availability.