@Retention(value=RUNTIME) @Target(value=ANNOTATION_TYPE) @Documented public @interface ClientBinding
@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.
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 javax.ws.rs.core.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 ). |
public abstract Class<? extends javax.ws.rs.core.Configuration> configClass
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>
public abstract boolean inheritServerProviders
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>
public abstract String baseUri
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>
Copyright © 2007-2021, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.