Asynchronous Requests

Asynchronous requests

Asynchronous requests

Since version 1.0.1 EverRest supports asynchronous requests. Request to any resources may be launched in asynchronous mode simple by adding query parameter async=true to URL. After such request (if it's success) client get response with status 202 and URL where client may monitor result of request. URL provided in Location header and in the entity of response to asynchronous request. Let's try to use asynchronous request with EverRest samples. Go to the everrest/everrest-samples/book-service project and run it by command: mvn jetty:run. For next steps we assumes using unix like OS and installed curl. If you are under windows check file running.xml in folder with book-service sample. You can use web browser also. After start server open new console window and type: curl -X GET -i http://localhost:8080/book-service/books?async=true. Here is output:

HTTP/1.1 202 Accepted
Content-Type: text/plain
Location: http://localhost:8080/book-service/async/1
Transfer-Encoding: chunked
Server: Jetty(6.1.10)

http://localhost:8080/book-service/async/1

Get result of asynchronous request

Once client got such URL it may periodically check URL to get result of asynchronous request. Once request is done client get result of request with corresponded status. If request are still in progress then client get 202 response again. Try to get result of asynchronous request, type next: curl -X GET http://localhost:8080/book-service/async/1. Here is output:

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.10)

[{"id":"101","author":"Vincent Massol","title":"JUnit in Action","price":19.37,"pages":386}]

Discard asynchronous request

Client may decide to stop asynchronous request. To do that it must make DELETE request to specified URL. For example run one more asynchronous request and then remove it without checking result.

• Send asynchronous request: curl -X GET http://localhost:8080/book-service/books?async=true
• Discard it: curl -i -X DELETE http://localhost:8080/book-service/async/2
• Check it: curl -i -X GET http://localhost:8080/book-service/async/2. As result you will see:

HTTP/1.1 404 Not Found
Content-Type: text/plain
JAXRS-Body-Provided: Error-Message
Transfer-Encoding: chunked
Server: Jetty(6.1.10)

Job 2 not found.

Get list of asynchronous tasks

Since version 1.0.3 it is possible to get list of asynchronous tasks which currently in progress. To do so need to send GET request to URL (relative) /async. Here is example with book-service project:

• Run few task asynchronously: curl -X GET http://localhost:8080/book-service/books?async=true. Repeat this few times.
• Get list of asynchronous tasks. It is possible to get list of tasks in two formats: application/json (default) and text/plain. Format may be set by Accept header. Try with plain/text: curl -X GET -H 'accept:text/plain' http://localhost:8080/book-service/async. Here is output:

USER                          ID        STAT      PATH
null                          1         done      /book-service/books
null                          2         done      /book-service/books
null                          3         done      /book-service/books
null                          4         done      /book-service/books
null                          5         done      /book-service/books

Configuration

Configuration of asynchronous feature may be done by specified context parameters in web.xml file.

**Parameter name**	**Default value**	**Description**
org.everrest.asynchronous	true	Enable or disable asynchronous feature. If this parameter is `false` then other parameters for asynchronous feature has not any sense.
org.everrest.asynchronous.pool.size	10	How many asynchronous request may be processed at the same time. Other requests will wait in the queue.
org.everrest.asynchronous.queue.size	100	Size of queue. If asynchronous request can't be processed after consuming it will be added in queue. If both pool and queue are full then asynchronous request will be discarded immediately .
org.everrest.asynchronous.cache.size	512	Size of cache for waiting, running and ended request. **NOTE** request may be the discarded and removed from pool (even if it is not done yet) if maximum number of requests in cache reached.
org.everrest.asynchronous.job.timeout	60	Timeout in minutes for request. If after timeout request is not done or client did not come yet to get result of request it MAY be discarded. In this case a result of request will be lost.