https://projects.eclipse.org/projects/ee4j.jersey/jersey-server: Jersey core server implementation (Eclipse Foundation) 
/*
 * Copyright (c) 2013, 2019 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package org.glassfish.jersey.server;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.ws.rs.core.Configuration;


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
/**
 * Meta-annotation that provides a facility for creating bindings between an {@link Uri &#64;Uri}-injectable
 * {@link javax.ws.rs.client.WebTarget WebTarget} instances and clients (and their configurations) that are used to create
 * the injected web target instances.
 * <p>
 * Jersey refers to client instance configured using custom bound configurations as <em>managed clients</em>. 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:
 * <pre>
 * &#64;ClientBinding
 * public &#64;interface <b>MyClient</b> { }
 * </pre>
 * This defines new {@code @MyClient} binding annotation which will be configured using a default {@link #configClass()
 * configuration class}, will {@link #inheritServerProviders() inherit all server-side providers} as well as will use a
 * default {@link #baseUri() base URI} to resolve relative {@link Uri &#64;Uri} web target URI values.
 * </p>
 * <p>
 * Once a custom client binding annotation is defined, it can be used when {@link Uri injecting} new
 * {@code 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:
 * <pre>
 * &#64;Path("foo")
 * public class ManagedClientResource {
 *   &#64;Uri("bar") <b>&#64;MyClient</b>
 *   private WebTarget targetBar;
 *
 *   &#64;GET
 *   &#64;Path("bar")
 *   public String getBar() {
 *     return targetBar.request(MediaType.TEXT_PLAIN).get(String.class);
 *   }
 *
 *   &#64;GET
 *   &#64;Path("baz")
 *   public Response getBaz(&#64;Uri("baz") <b>&#64;MyClient</b> WebTarget targetBaz) {
 *     return targetB.request(MediaType.TEXT_PLAIN).get();
 *   }
 * }
 * </pre>
 * </p>
 * <p>
 * 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 {@link Configuration}
 * implementation class and link it with the binding annotation:
 * <pre>
 * public class <b>MyClientConfig</b> implements Configuration {
 *   ... // configure provide
 * }
 *
 * &#64;ClientBinding(configClass = <b>MyClientConfig</b>.class)
 * public &#64;interface <b>MyClient</b> { }
 * </pre>
 * Note that the easiest way how to provide a custom client-side {@code Configuration} implementation in Jersey is to extend
 * the {@link org.glassfish.jersey.client.ClientConfig} class that provides reusable implementation of JAX-RS
 * {@link Configuration} as well as {@link javax.ws.rs.core.Configurable Configurable} APIs.
 * </p>
 * <p>
 * In case a managed client needs special properties, these properties can also be provided via custom {@code 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
 * <tt><em>&lt;client.binding.annotation.FQN&gt;</em>.property.</tt> prefix. This can be either done programmatically,
 * for example:
 * <pre>
 * MyResourceConfig.property(
 *     "my.package.MyClient.property.<b>custom-client-property</b>", "custom-value");
 * </pre>
 * </p>
 * <p>
 * Or declaratively via {@code web.xml}:
 * <pre>
 * &lt;init-param&gt;
 *     &lt;param-name&gt;my.package.MyClient.property.<b>custom-client-property</b>&lt;/param-name&gt;
 *     &lt;param-value&gt;custom-value&lt;/param-value&gt;
 * &lt;/init-param&gt;
 * </pre>
 * Properties defined this way can be accessed from the proper managed client instances using the custom property names:
 * <pre>
 * Object value = customTarget.getConfiguration().getProperty("<b>custom-client-property</b>");
 * </pre>
 * 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.
 * </p>
 *
 * @author Marek Potociar
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
@Documented
public @interface ClientBinding {
    
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>





/**
     * 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.
     * <p>
     * Hard-coded value of this property may be overridden at deploy-time by providing a new value for a
     * <tt><em>&lt;client.binding.annotation.FQN&gt;</em>.configClass</tt> property.
     * </p>
     * <p>
     * For example:
     * <pre>
     * MyResourceConfig.property(
     *     "my.package.MyClient.configClass",
     *     "my.package.MyClientConfig");
     * </pre>
     * </p>
     * <p>
     * Or declaratively via {@code web.xml}:
     * <pre>
     * &lt;init-param&gt;
     *     &lt;param-name&gt;my.package.MyClient.configClass&lt;/param-name&gt;
     *     &lt;param-value&gt;my.package.MyClientConfig&lt;/param-value&gt;
     * &lt;/init-param&gt;
     * </pre>
     * </p>
     */
    public Class<? extends Configuration> configClass() default Configuration.class;

    
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>





/**
     * Determine whether providers present in the server-side configuration should be inherited by the bound client
     * configuration ({@code true}) or not ({@code false}). By default the server-side providers are inherited, i.e.
     * the annotation property defaults to {@code true}.
     * <p>
     * Hard-coded value of this property may be overridden at deploy-time by providing a new value for a
     * <tt><em>&lt;client.binding.annotation.FQN&gt;</em>.inheritServerProviders</tt> property.
     * </p>
     * <p>
     * For example:
     * <pre>
     * MyResourceConfig.property(
     *     "my.package.MyClient.inheritServerProviders", false);
     * </pre>
     * </p>
     * <p>
     * Or declaratively via {@code web.xml}:
     * <pre>
     * &lt;init-param&gt;
     *     &lt;param-name&gt;my.package.MyClient.inheritServerProviders&lt;/param-name&gt;
     *     &lt;param-value&gt;false&lt;/param-value&gt;
     * &lt;/init-param&gt;
     * </pre>
     * </p>
     */
    public boolean inheritServerProviders() default true;

    
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>





/**
     * Define a custom base URI for managed {@link javax.ws.rs.client.WebTarget WebTarget} instances injected using
     * {@link Uri &#64;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.
     * <p>
     * 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.
     * </p>
     * <p>
     * Hard-coded value of this property may be overridden at deploy-time by providing a new value for a
     * <tt><em>&lt;client.binding.annotation.FQN&gt;</em>.baseUri</tt> property.
     * </p>
     * <p>
     * For example:
     * <pre>
     * MyResourceConfig.property(
     *     "my.package.MyClient.baseUri", "http://jersey.java.net/examples/");
     * </pre>
     * </p>
     * <p>
     * Or declaratively via {@code web.xml}:
     * <pre>
     * &lt;init-param&gt;
     *     &lt;param-name&gt;my.package.MyClient.baseUri&lt;/param-name&gt;
     *     &lt;param-value&gt;http://jersey.java.net/examples/&lt;/param-value&gt;
     * &lt;/init-param&gt;
     * </pre>
     * </p>
     */
    public String baseUri() default "";
}