javax.ws.rs.client
Interface Configuration

All Superinterfaces:

Configurable

public interface Configuration
extends Configurable

Represents inheritable configuration of the main client-side JAX-RS components, such as Client, WebTarget, Invocation Builder or Invocation.

Configuration is inherited from a parent component to a child component. When creating new resource targets using a Client instance, the configuration of the Client instance is inherited by the child target instances being created. Similarly, when creating new Invocation.Builder invocation builders or derived resource targets using a parent target instance, the configuration of the parent target is inherited by the child instances being created.

The inherited configuration on a child instance reflects the state of the parent configuration at the time of the child instance creation. Once the child instance is created its configuration is detached from the parent configuration. This means that any subsequent changes in the parent configuration do not affect the configuration of previously created child instances.

Once the child instance is created, it's configuration can be further customized using the provided set of instance configuration mutator methods. A change made in the configuration of a child instance does not affect the configuration of its parent, for example:

 Client client = ClientFactory.newClient();
 client.configuration().setProperty("FOO_PROPERTY", "FOO_VALUE");

 // inherits the configured "FOO_PROPERTY" from the client instance
 WebTarget resourceTarget = client.target("http://examples.jaxrs.com/");

 // does not modify the client instance configuration
 resourceTarget.configuration().register(new BarFeature());
 

For a discussion on registering providers or narrowing down the scope of the contracts registered for each provider, see configurable context documentation.

Since:

2.0

Author:

Marek Potociar

Method Summary

Configuration	register(java.lang.Class<?> providerClass) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
Configuration	register(java.lang.Class<?> providerClass, int bindingPriority) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
<T> Configuration	register(java.lang.Class<T> providerClass, java.lang.Class<? super T>... contracts) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
<T> Configuration	register(java.lang.Class<T> providerClass, int bindingPriority, java.lang.Class<? super T>... contracts) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
Configuration	register(java.lang.Object provider) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
<T> Configuration	register(java.lang.Object provider, java.lang.Class<? super T>... contracts) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
Configuration	register(java.lang.Object provider, int bindingPriority) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
<T> Configuration	register(java.lang.Object provider, int bindingPriority, java.lang.Class<? super T>... contracts) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
Configuration	setProperties(java.util.Map<java.lang.String,?> properties) Set new configuration properties replacing all previously set properties.
Configuration	setProperty(java.lang.String name, java.lang.Object value) Set the new configuration property, if already set, the existing value of the property will be updated.
Configuration	updateFrom(Configurable configuration) Replace the existing configuration state with the configuration state of the externally provided configuration.

Methods inherited from interface javax.ws.rs.core.Configurable

getFeatures, getProperties, getProperty, getProviderClasses, getProviderInstances

Method Detail

setProperties

Configuration setProperties(java.util.Map<java.lang.String,?> properties)

Description copied from interface: Configurable

Set new configuration properties replacing all previously set properties.

Specified by:

setProperties in interface Configurable

Parameters:

properties - new set of configuration properties. The content of the map will replace any existing properties set on the configurable instance.

Returns:

the updated configurable instance.

setProperty

Configuration setProperty(java.lang.String name,
                          java.lang.Object value)

Description copied from interface: Configurable

Set the new configuration property, if already set, the existing value of the property will be updated. Setting a null value into a property effectively removes the property from the property bag.

Specified by:

setProperty in interface Configurable

Parameters:

name - property name.

value - (new) property value. null value removes the property with the given name.

Returns:

the updated configurable instance.

updateFrom

Configuration updateFrom(Configurable configuration)

Replace the existing configuration state with the configuration state of the externally provided configuration.

Parameters:

configuration - configuration to be used to update the instance.

Returns:

the updated configuration.

register

Configuration register(java.lang.Class<?> providerClass)

Description copied from interface: Configurable

Register a provider or a feature class to be instantiated and used in the scope of the configured instance. The registered provider class is registered as a provider of all the recognized JAX-RS or implementation-specific extension contracts.

As opposed to the providers registered by the provider instances, providers registered using this method are instantiated and properly injected by the JAX-RS implementation provider. In case of a conflict between a registered provider instance and instantiated registered provider class, the registered provider instance takes precedence and the registered provider class will not be instantiated in such case.

In case the registered class represents a feature, this Configurable context instantiates the feature and invokes the Feature.configure(javax.ws.rs.core.Configurable) method and lets the feature update the configurable context. If the invocation of Feature.configure(javax.ws.rs.core.Configurable) returns true the feature is added to the collection of enabled features, otherwise the feature instance is discarded.

Specified by:

register in interface Configurable

Parameters:

providerClass - provider class to be instantiated and used in the scope of the configured instance.

Returns:

the updated configurable instance.

register

Configuration register(java.lang.Class<?> providerClass,
                       int bindingPriority)

Description copied from interface: Configurable

Register a provider or a feature class to be instantiated and used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Class) except that any provider binding priority specified on the provider class using @BindingPriority annotation is overridden with the supplied bindingPriority value.

Note that in case the binding priority cannot be applied to a particular provider contract registered for the provider class, the supplied bindingPriority value is ignored.

Specified by:

register in interface Configurable

Parameters:

providerClass - provider class to be instantiated and used in the scope of the configured instance.

bindingPriority - the overriding binding priority for the registered contract(s).

Returns:

the updated configurable instance.

register

<T> Configuration register(java.lang.Class<T> providerClass,
                           java.lang.Class<? super T>... contracts)

Description copied from interface: Configurable

Register a provider or a feature class to be instantiated and used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Class) except the provider class is only registered as a provider of the listed contracts. Note that in case the Feature interface is not listed explicitly, the provider class is not recognized as a JAX-RS feature.

Specified by:

register in interface Configurable

Parameters:

providerClass - provider class to be instantiated and used in the scope of the configured instance.

contracts - the specific set of contracts implemented by the provider class for which the provider should be registered. If omitted, the provider class will be registered as a provider of all recognized contracts implemented by the provider class.

Returns:

the updated configurable instance.

register

<T> Configuration register(java.lang.Class<T> providerClass,
                           int bindingPriority,
                           java.lang.Class<? super T>... contracts)

Description copied from interface: Configurable

Register a provider or a feature class to be instantiated and used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Class, Class[]) except that any provider binding priority specified on the provider class using @BindingPriority annotation is overridden with the supplied bindingPriority value.

Note that in case the binding priority cannot be applied to a particular provider contract registered for the provider class, the supplied bindingPriority value is ignored.

Specified by:

register in interface Configurable

Parameters:

providerClass - provider class to be instantiated and used in the scope of the configured instance.

bindingPriority - the overriding binding priority for the registered contract(s).

contracts - the specific set of contracts implemented by the provider class for which the provider should be registered. If omitted, the provider class will be registered as a provider of all recognized contracts implemented by the provider class.

Returns:

the updated configurable instance.

register

Configuration register(java.lang.Object provider)

Description copied from interface: Configurable

Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance. The registered provider is registered as a provider of all the recognized JAX-RS or implementation-specific extension contracts.

As opposed to the providers registered by the provider classes, provider instances registered using this method are used "as is, i.e. are not managed or injected by the JAX-RS implementation provider. In case of a conflict between a registered provider instance and instantiated registered provider class, the registered provider instance takes precedence and the registered provider class will not be instantiated in such case.

In case the registered class represents a feature, this Configurable context instantiates the feature and invokes the Feature.configure(javax.ws.rs.core.Configurable) method and lets the feature update the configurable context. If the invocation of Feature.configure(javax.ws.rs.core.Configurable) returns true the feature is added to the collection of enabled features, otherwise the feature instance is discarded.

Specified by:

register in interface Configurable

Parameters:

provider - a provider instance to be registered in the scope of the configured instance.

Returns:

the updated configurable instance.

register

Configuration register(java.lang.Object provider,
                       int bindingPriority)

Description copied from interface: Configurable

Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Object) except that any provider binding priority specified on the provider using @BindingPriority annotation is overridden with the supplied bindingPriority value.

Note that in case the binding priority cannot be applied to a particular provider contract registered for the provider, the supplied bindingPriority value is ignored.

Specified by:

register in interface Configurable

Parameters:

provider - provider class to be instantiated and used in the scope of the configured instance.

bindingPriority - the overriding binding priority for the registered contract(s).

Returns:

the updated configurable instance.

register

<T> Configuration register(java.lang.Object provider,
                           java.lang.Class<? super T>... contracts)

Description copied from interface: Configurable

Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Object) except the provider is only registered as a provider of the listed contracts. Note that in case the Feature interface is not listed explicitly, the provider is not recognized as a JAX-RS feature.

Specified by:

register in interface Configurable

Parameters:

provider - a provider instance to be registered in the scope of the configured instance.

contracts - the specific set of contracts implemented by the provider class for which the provider should be registered. If omitted, the provider class will be registered as a provider of all recognized contracts implemented by the provider class.

Returns:

the updated configurable instance.

register

<T> Configuration register(java.lang.Object provider,
                           int bindingPriority,
                           java.lang.Class<? super T>... contracts)

Description copied from interface: Configurable

Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.

This registration method provides same functionality as Configurable.register(Object, Class[]) except that any provider binding priority specified on the provider using @BindingPriority annotation is overridden with the supplied bindingPriority value.

Note that in case the binding priority cannot be applied to a particular provider contract registered for the provider, the supplied bindingPriority value is ignored.

Specified by:

register in interface Configurable

Parameters:

provider - a provider instance to be registered in the scope of the configured instance.

bindingPriority - the overriding binding priority for the registered contract(s).

contracts - the specific set of contracts implemented by the provider class for which the provider should be registered. If omitted, the provider class will be registered as a provider of all recognized contracts implemented by the provider class.

Returns:

the updated configurable instance.