org.glassfish.jersey.server

Annotation Type ClientBinding

@Retention(value=RUNTIME)
 @Target(value=ANNOTATION_TYPE)
 @Documented
public @interface ClientBinding

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

Jersey refers to client instance configured using custom bound configurations as managed clients. As a first step, when using a managed client in a server-side JAX-RS/Jersey application, a custom client binding annotation has to be defined:

 @ClientBinding
 public @interface MyClient { }
 

This defines new @MyClient binding annotation which will be configured using a default configuration class, will inherit all server-side providers as well as will use a default base URI to resolve relative @Uri web target URI values.

Once a custom client binding annotation is defined, it can be used when injecting new WebTarget instances created by a managed client. To complete a binding between a manged client and an injected web target instance, put the custom client binding annotation into the definition of an injected web target field or parameter. For example:

 @Path("foo")
 public class ManagedClientResource {
   @Uri("bar") @MyClient
   private WebTarget targetBar;

   @GET
   @Path("bar")
   public String getBar() {
     return targetBar.request(MediaType.TEXT_PLAIN).get(String.class);
   }

   @GET
   @Path("baz")
   public Response getBaz(@Uri("baz") @MyClient WebTarget targetBaz) {
     return targetB.request(MediaType.TEXT_PLAIN).get();
   }
 }
 

Often managed clients may require a more complex configuration, including specifying custom provider classes and instances and setting custom properties. In such case it may be more convenient to provide a custom Configuration implementation class and link it with the binding annotation:

 public class MyClientConfig implements Configuration {
   ... // configure provide
 }

 @ClientBinding(configClass = MyClientConfig.class)
 public @interface MyClient { }
 

Note that the easiest way how to provide a custom client-side Configuration implementation in Jersey is to extend the ClientConfig class that provides reusable implementation of JAX-RS Configuration as well as Configurable APIs.

In case a managed client needs special properties, these properties can also be provided via custom Configuration implementation class. Another way how to pass custom properties to a managed client configuration is to define the managed client properties in the server configuration using a special <client.binding.annotation.FQN>.property. prefix. This can be either done programmatically, for example:

 MyResourceConfig.property(
     "my.package.MyClient.property.custom-client-property", "custom-value");
 

Or declaratively via web.xml:

 <init-param>
     <param-name>my.package.MyClient.property.custom-client-property</param-name>
     <param-value>custom-value</param-value>
 </init-param>
 

Properties defined this way can be accessed from the proper managed client instances using the custom property names:

 Object value = customTarget.getConfiguration().getProperty("custom-client-property");
 

Note that the technique of defining managed client properties via server-side configuration described above can be also used to override the default property values defined programmatically in a custom configuration implementation class.

Author:

Marek Potociar

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	baseUri Define a custom base URI for managed WebTarget instances injected using @Uri annotation with a relative web target URI value.
Class<? extends Configuration>	configClass Define a configuration implementation class to be instantiated and used to configure bound web targets.
boolean	inheritServerProviders Determine whether providers present in the server-side configuration should be inherited by the bound client configuration (true) or not (false).

Element Detail

configClass

public abstract Class<? extends Configuration> configClass

Define a configuration implementation class to be instantiated and used to configure bound web targets. If not set, a default client-side configuration implementation class will be used.

Hard-coded value of this property may be overridden at deploy-time by providing a new value for a <client.binding.annotation.FQN>.configClass property.

For example:

 MyResourceConfig.property(
     "my.package.MyClient.configClass",
     "my.package.MyClientConfig");
 

Or declaratively via web.xml:

 <init-param>
     <param-name>my.package.MyClient.configClass</param-name>
     <param-value>my.package.MyClientConfig</param-value>
 </init-param>
 

Default:

javax.ws.rs.core.Configuration.class

inheritServerProviders

public abstract boolean inheritServerProviders

Determine whether providers present in the server-side configuration should be inherited by the bound client configuration (true) or not (false). By default the server-side providers are inherited, i.e. the annotation property defaults to true.

Hard-coded value of this property may be overridden at deploy-time by providing a new value for a <client.binding.annotation.FQN>.inheritServerProviders property.

For example:

 MyResourceConfig.property(
     "my.package.MyClient.inheritServerProviders", false);
 

Or declaratively via web.xml:

 <init-param>
     <param-name>my.package.MyClient.inheritServerProviders</param-name>
     <param-value>false</param-value>
 </init-param>
 

Default:

true

baseUri

public abstract String baseUri

Define a custom base URI for managed WebTarget instances injected using @Uri annotation with a relative web target URI value. By default, the base URI is empty indicating that the current application base URI should be used.

Using a custom context root is useful in cases where the absolute URI of the target endpoint(s) is expected to change on may vary over time. An typical scenarios include transition of the application from a test to production environment, etc.

Hard-coded value of this property may be overridden at deploy-time by providing a new value for a <client.binding.annotation.FQN>.baseUri property.

For example:

 MyResourceConfig.property(
     "my.package.MyClient.baseUri", "http://jersey.java.net/examples/");
 

Or declaratively via web.xml:

 <init-param>
     <param-name>my.package.MyClient.baseUri</param-name>
     <param-value>http://jersey.java.net/examples/</param-value>
 </init-param>
 

Default:

""