Chapter 30. Asynchronous Job Service

While HTTP is a synchronous protocol, it is capable of dealing with asynchronous invocations. The HTTP 1.1 response code 202 (Accepted) means that the server has received and accepted the response for processing, but that processing is not yet complete. The RESTEasy Asynchronous Job Service is based on this type of response.

POST http://example.com/myservice?asynch=true

POST http://example.com/myservice?asynch=true

For example, if you make the above post with the asynch query parameter set to true, RESTEasy returns a 202 (Accepted) response code and runs the invocation in the background. It also returns a Location header with a URL pointing to the location of the background method's response.

HTTP/1.1 202 Accepted
Location: http://example.com/asynch/jobs/3332334

HTTP/1.1 202 Accepted
Location: http://example.com/asynch/jobs/3332334

The URI will have the form of:

/asynch/jobs/{job-id}?wait={millisconds}|nowait=true

/asynch/jobs/{job-id}?wait={millisconds}|nowait=true

You can perform GET, POST and DELETE operations on this job URL. GET returns the response of the JAX-RS resource method, if the job has completed. If the job has not completed, this GET returns a response code of 202 (Accepted). Invoking GET does not remove the job, so it can be called multiple times. When RESTEasy's job queue becomes full, it will evict the least recently used job from memory. You can clean the queue manually by calling DELETE on the URI. POST reads the JOB response and removes the JOB when it has completed.

Both GET and POST let you specify a mazimum wait time in milliseconds — a wait query parameter. For example:

POST http://example.com/asynch/jobs/122?wait=3000

POST http://example.com/asynch/jobs/122?wait=3000

If you do not specify a wait parameter, the GET or POST will not wait at all if the job is not complete.