Asynchronous Requests

Requests are processed either synchronously or asynchronously, depending on the activities that are being executed. While synchronous requests do not return until completed, asynchronous requests continue processing after the response document has been returned to the client. Activities that do not produce output such as output streams or delivery activities are processed asynchronously. The client cannot control this behaviour - it is managed by the data service resource.

For further background reading refer to the Perform Document documentation.

In this tutorial we will concentrate on the request monitoring and polling features of the DataService. Delivery activities are discussed in more detail in Asynchronous Delivery.

Most of the code excerpts featured on this page are shown in the following example file: AsynchronousRequests.java

Processing an Asynchronous Request

In this example, we will construct a request that stores some data in a DataStore and then opens an output stream that waits for data to be pulled.

Add some data to a DataStore activity.

DataStore store = new DataStore();
store.addItem("one");
store.addItem("two");
store.addItem("three");

Construct a DTOutputStream and connect it to the output of the DataStore activity above.
```
DTOutputStream output = new DTOutputStream(store.getOutput());
```

Finally, add both activities to a new request

ActivityRequest request = new ActivityRequest();
request.add(store);
request.add(output);

... and make sure that this request creates a new session when it is processed.
```
request.setSessionRequirements(new JoinNewSession());
```

When executed the method will return as soon as the response has been received. The response usually indicates that the the request has started processing.

Response response = service.perform(request);

The session ID can be retrieved from the response and should be stored for further monitoring the status of the request.

Session session = response.getSession();

Monitoring the Request Status

All requests processed by a data service resource are joined to a session and any session can only be joined by one request at a time. A client can monitor the progress of the current request in a session. The DataService interface provides a getStatus method for this purpose which returns an object describing the processing status of the request that is currently joined to that session.

RequestStatus status = service.getStatus(session.getSessionID());

The same information is provided by the getStatus method on the Session interface.

RequestStatus status = session.getStatus();

The request status is one of the following constants:

RequestStatus.UNSTARTED - The request has yet to be started
RequestStatus.INITIALISING - The request is initialising
RequestStatus.PROCESSING - The request is currently processing
RequestStatus.COMPLETED - The request has completed successfully
RequestStatus.ERROR - The request has resulted in an error
RequestStatus.TERMINATED - The request has been terminated
RequestStatus.TIMEDOUT - The request has timed out

Utility methods on the RequestStatus class allow the client to check

whether the current request has completed successfully
```
status.isFinished();
```
whether it is not yet started, initialising or processing:
```
status.isUnstarted();
```
or whether the request resulted in an error, has been terminated or timed out:
```
status.isStopped();
```

Polling the Request Status

The DataService interface provides various poll methods that can be used to wait until an asynchronous request has completed. The example below polls the data service resource every 100 milliseconds until the request completes.

service.pollUntilRequestCompleted(session.getSessionID(), 100);

You can also specify a timeout so that the method either returns when the request completed or the given time period has run out. For example, the following code polls the data service resource every 1000 milliseconds for up to one minute (60,000 milliseconds).

service.pollUntilRequestCompleted(session.getSessionID(), 1000, 60000);

Conclusion

This page provided a brief introduction to asynchronous requests and the request monitoring tools available in the client toolkit.