| /* |
| * 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 {@link Uri @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> |
| * @ClientBinding |
| * public @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 @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> |
| * @Path("foo") |
| * public class ManagedClientResource { |
| * @Uri("bar") <b>@MyClient</b> |
| * 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") <b>@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 |
| * } |
| * |
| * @ClientBinding(configClass = <b>MyClientConfig</b>.class) |
| * public @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><client.binding.annotation.FQN></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> |
| * <init-param> |
| * <param-name>my.package.MyClient.property.<b>custom-client-property</b></param-name> |
| * <param-value>custom-value</param-value> |
| * </init-param> |
| * </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. |
| * <p> |
| * Hard-coded value of this property may be overridden at deploy-time by providing a new value for a |
| * <tt><em><client.binding.annotation.FQN></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> |
| * <init-param> |
| * <param-name>my.package.MyClient.configClass</param-name> |
| * <param-value>my.package.MyClientConfig</param-value> |
| * </init-param> |
| * </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 ({@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><client.binding.annotation.FQN></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> |
| * <init-param> |
| * <param-name>my.package.MyClient.inheritServerProviders</param-name> |
| * <param-value>false</param-value> |
| * </init-param> |
| * </pre> |
| * </p> |
| */ |
| public boolean inheritServerProviders() default true; |
| |
| /** |
| * Define a custom base URI for managed {@link javax.ws.rs.client.WebTarget WebTarget} instances injected using |
| * {@link Uri @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><client.binding.annotation.FQN></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> |
| * <init-param> |
| * <param-name>my.package.MyClient.baseUri</param-name> |
| * <param-value>http://jersey.java.net/examples/</param-value> |
| * </init-param> |
| * </pre> |
| * </p> |
| */ |
| public String baseUri() default ""; |
| } |
