Red Hat Summit15.12. RESTEasy Asynchronous Job Service
15.12.1. About the RESTEasy Asynchronous Job Service
The RESTEasy Asynchronous Job Service is designed to add asynchronous behavior to the HTTP protocol. While HTTP is a synchronous protocol it does have a faint idea of asynchronous invocations. The HTTP 1.1 response code 202, "Accepted" means that the server has received and accepted the response for processing, but the processing has not yet been completed. The Asynchronous Job Service builds around this.
To enable the service, refer to: Section 15.12.2, “Enable the Asynchronous Job Service”. For examples of how the service works, refer to Section 15.12.3, “Configure Asynchronous Jobs for RESTEasy”.
15.12.2. Enable the Asynchronous Job Service
Procedure 15.7. Modify the web.xml file
- Enable the asynchronous job service in the
web.xmlfile:<context-param> <param-name>resteasy.async.job.service.enabled</param-name> <param-value>true</param-value> </context-param>
Result
The asynchronous job service has been enabled. For configuration options, refer to: Section 15.12.4, “Asynchronous Job Service Configuration Parameters”.
15.12.3. Configure Asynchronous Jobs for RESTEasy
Summary
This topic covers examples of the query parameters for asynchronous jobs with RESTEasy.
Warning
Role based security does not work with the Asynchronous Job Service, as it cannot be implemented portably. If the Asynchronous Job Service is used, application security must be done through XML declarations in the
web.xml file instead.
Important
While GET, DELETE, and PUT methods can be invoked asynchronously, this breaks the HTTP 1.1 contract of these methods. While these invocations may not change the state of the resource if invoked more than once, they do change the state of the server as new Job entries with each invocation.
Example 15.21. The Asynch Parameter
The
asynch query parameter is used to run invocations in the background. A 202 Accepted response is returned, as well as a Location header with a URL pointing to where the response of the background method is located.
POST http://example.com/myservice?asynch=true
The example above will return a 202 Accepted response. It will also return a Location header with a URL pointing to where the response of the background method is located. An example of the location header is shown below:
HTTP/1.1 202 Accepted Location: http://example.com/asynch/jobs/3332334
The URI will take the form of:
/asynch/jobs/{job-id}?wait={millisconds}|nowait=true
GET, POST and DELETE operations can be performed on this URL.
- GET returns the JAX-RS resource method invoked as a response if the job was completed. If the job has not been completed, this GET will return a 202 Accepted response code. Invoking GET does not remove the job, so it can be called multiple times.
- POST does a read of the job response and removes the job if it has been completed.
- DELETE is called to manually clean up the job queue.
Note
When the Job queue is full, it will evict the earliest job from memory automatically, without needing to call DELETE.
Example 15.22. Wait / Nowait
The GET and POST operations allow for the maximum wait time to be defined, using the
wait and nowait query parameters. If the wait parameter is not specified, the operation will default to nowait=true, and will not wait at all if the job is not complete. The wait parameter is defined in milliseconds.
POST http://example.com/asynch/jobs/122?wait=3000
Example 15.23. The Oneway Parameter
RESTEasy supports fire and forget jobs, using the
oneway query parameter.
POST http://example.com/myservice?oneway=true
The example above will return a 202 Accepted response, but no job will be created.
15.12.4. Asynchronous Job Service Configuration Parameters
Summary
The table below details the configurable context-params for the Asynchronous Job Service. These parameters can be configured in the web.xml file.
| Parameter | Description |
|---|---|
| resteasy.async.job.service.max.job.results | Number of job results that can be held in the memory at any one time. Default value is 100. |
| resteasy.async.job.service.max.wait | Maximum wait time on a job when a client is querying for it. Default value is 300000. |
| resteasy.async.job.service.thread.pool.size | Thread pool size of the background threads that run the job. Default value is 100. |
| resteasy.async.job.service.base.path | Sets the base path for the job URIs. Default value is /asynch/jobs |
Example 15.24. Example Asynchronous Jobs Configuration
<web-app>
<context-param>
<param-name>resteasy.async.job.service.enabled</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>resteasy.async.job.service.max.job.results</param-name>
<param-value>100</param-value>
</context-param>
<context-param>
<param-name>resteasy.async.job.service.max.wait</param-name>
<param-value>300000</param-value>
</context-param>
<context-param>
<param-name>resteasy.async.job.service.thread.pool.size</param-name>
<param-value>100</param-value>
</context-param>
<context-param>
<param-name>resteasy.async.job.service.base.path</param-name>
<param-value>/asynch/jobs</param-value>
</context-param>
<listener>
<listener-class>
org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
</listener-class>
</listener>
<servlet>
<servlet-name>Resteasy</servlet-name>
<servlet-class>
org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Resteasy</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
