Annotation Type ClientBinding
-
@Retention(RUNTIME) @Target(ANNOTATION_TYPE) @Documented public @interface ClientBinding
Meta-annotation that provides a facility for creating bindings between an@Uri
-injectableWebTarget
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 defaultconfiguration class
, willinherit all server-side providers
as well as will use a defaultbase URI
to resolve relative@Uri
web target URI values.Once a custom client binding annotation is defined, it can be used when
injecting
newWebTarget
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-sideConfiguration
implementation in Jersey is to extend theClientConfig
class that provides reusable implementation of JAX-RSConfiguration
as well asConfigurable
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 Description String
baseUri
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
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:
- jakarta.ws.rs.core.Configuration.class
-
-
-
inheritServerProviders
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 totrue
.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
String baseUri
Define a custom base URI for managedWebTarget
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:
- ""
-
-