Managed JAX-RS Client

Common use-case in web-application development is aggregating data from multiple resources, combining them together and returning them to the used as XML/JSON or as a web page. In Java world these (external) resources can be approached via standardized Clients from JAX-RS 2.0. Jersey 2 application can use so-called managed client mechanism that brings a convenient way to create JAX-RS clients and web targets for such resources.

In this article I’ll demonstrate the concepts on a simple application that displays ratings of movies obtained from different sources:

You can try the application at (deployed on Heroku)
for example:

and browse the code

Injecting WebTarget via @Uri

Injecting a resource target pointing at a resource identified by the resolved URI can be done via new annotation @Uri. The annotation can be placed on WebTarget that represents

  • a method parameter, i.e. FormResource:
  •  a class field for example in resources or providers (filters, interceptors, ..), i.e. RatingsResource:
  • or a bean property.

As you probably noticed the value of @Uri can be either absolute or relative URI. The relative ones are resolved into absolute URIs in the context of application (context path) or in a context of enclosing resource class. Web target from the first example (internal/greeting/{greeting}) is pointing at an internal resource (present in the same application) but web target from the second example (movie/{id}) is not relative to our application as you’ll see in the next section.

Provided URIs can also contain template parameters (internal/greeting/{greeting}, r={format}&t={search}) which are resolved automatically (internal/greeting/{greeting}), if they are represented as path params (see @Path):

The greeting parameter is used on the front page in the header (it’s enough to set it, i.e. jersey-managed-jaxrs-client/Greetings, Commander, you don’t need to resolve it by hand).

or you can resolve them manually (r={format}&t={search}):


By default, injected clients are configured with features and providers from the configuration of an application (i.e. MyApplication) that are also applicable to clients. In our case only JacksonFeature would be taken into consideration.

In case this is not enough for you need to take a look at @ClientBinding.


Meta-annotation that provides a facility for creating bindings between an @Uri-injectable web target instances and clients (and their configurations) that are used to create the injected web target instances.

So, basically, the first step is to create a custom client-binding annotation and put @ClientBinding on top of it, i.e. CsfdClient:

Second step is to annotate WebTarget with custom client-binding annotation along with @Uri, i.e. RatingsResource:

Notice that one client (created for @CsfdClient) is used to create two WebTarget instances that are used separately.

Third step is to use the injected web target.

Custom client-binding annotation can be configured programmatically (see CsfdClient) via parameters of @ClientBinding which are:

  • baseUri – base URI which is used to absolutize relative URI provided in @Uri (this is the reason why csfdMovie / csfdSearch web targets aren’t pointing at internal resource).
  • inheritServerProviders – determines whether server providers ought to be registered in the client (and web targets) as well.
  • configClass – configuration class to configure client (and web targets), in our case it’s ManagedClientConfig (that extends ClientConfig) where we’re registering LoggingFilter and JacksonFeature.


Parameters of @ClientBinding for particular client-binding annotation can be set declaratively in web.xml via init-param-eters. You need to remember to prefix parameter name with fully-qualified name of custom client-binding annotation:

The last highlighted init-parameter ( shows special way how to define a property for the newly created client. In this case we can obtain value of the property from configuration of our web target and set the format of entities received from imdbMovie:


Besides the example I’ve been using in this article there are few others available in the Jersey workspace:

Further reading

Running Jersey 2 Applications on Heroku