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
`String` `baseUri` Define a custom base URI for managed `WebTarget` instances injected using `@Uri` annotation with a relative web target URI value.
`Class<? extends jakarta.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`).

### Element Detail

#### configClass

    public abstract Class<? extends jakarta.ws.rs.core.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

    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:
  ""