Going async with JAX-RS
JAX-RS provides client side asynchronous behavior to complement its server side counterpart. It’s powered by the AysncInvoker interface – the best part if that you do not need to get hold of it explicitly. The fluent JAX-RS client API makes it available by including the async() call in your builder calls
Like every other asynchronous offering, the JAX-RS client API offers you a couple of options to manage async calls
- DIY (do-it-yourself) – get back a Future instance and work with it to track the result
- Declarative callbacks – let the API know what you want it to do in case of a success or failure
A callback is required to implement the InvocationCallback interface. It defines two methods
- completed: gets called when an invocation successfully finishes. The result response is passed as a parameter to the callback method.
- failed: it is invoked in case of a failure
Here is an example
There is more to failure scenarios than meets the eye
The invocation of the failed method happens only in case of a failure – no doubts there. But there is a caveat – the criteria is based on the generic entity type (Java class type to be specific) of the response from the server.
Here is an example for the normal scenario
When the response type is anything other than javax.ws.rs.Response
In case of a server side error (e.g. HTTP 404), the failed method is invoked
What if the generic type if javax.ws.rs.Response?
In such scenario, the completed method is invoked – that’s the catch! You can always investigate the actual HTTP response by calling the getStatus method (as demonstrated in the below example)
At the outset, it might look odd ….
but think about it – you were expecting a response from the service and you did get one (it does not matter if it was success/failure). From the framework’s perspective, only if the API call to the endpoint failed to go through i.e. there was a client side error during invocation, should the failed method should be called. This is an important distinction/caveat which one should make a note of…
- Check out the JAX-RS 2.0 specification doc
- My eBook: REST assured with JAX-RS
- JAX-RS 2.0 article in the Java Magazine