Nuances of JAX-RS client side async callback

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

e.g. ClientBuilder.newClient().target(“”).request().async().get

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

Declarative callbacks

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

In case of a server side error (e.g. HTTP 404), the failed method is invoked

What if the generic type if

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…

Further reading


About Abhishek

Loves Go, NoSQL DBs and messaging systems
This entry was posted in Java, Java EE and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s