javax.ws.rs.client
Interface Configuration

public interface Configuration

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().enable(new BarFeature());
 

Since:

2.0

Author:

Marek Potociar

Method Summary

java.util.Collection<Feature>	getFeatures() Get the immutable set of enabled features.
java.util.Map<java.lang.String,java.lang.Object>	getProperties() Get the immutable bag of configuration properties.
java.lang.Object	getProperty(java.lang.String name) Get the value for the property with a given name.
java.util.Set<java.lang.Class<?>>	getProviderClasses() Get the immutable set of registered provider classes to be instantiated, injected and utilized in the scope of the configured instance.
java.util.Set<java.lang.Object>	getProviderInstances() Get the immutable set of registered provider instances to be utilized by the configured instance.
Configuration	register(java.lang.Class<?> providerClass) Register a feature or a provider class to be instantiated and used in the scope of the configured instance.
Configuration	register(java.lang.Object provider) Register a feature or a provider ("singleton") instance to be used in the scope of the configured instance.
Configuration	setProperties(java.util.Map<java.lang.String,? extends java.lang.Object> 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	update(Configuration configuration) Replace the existing configuration state with the configuration state of the externally provided configuration.

Method Detail

getProperties

java.util.Map<java.lang.String,java.lang.Object> getProperties()

Get the immutable bag of configuration properties.

Returns:

the immutable view of configuration properties.

See Also:

Configuration

getProperty

java.lang.Object getProperty(java.lang.String name)

Get the value for the property with a given name.

Parameters:

name - property name.

Returns:

the property value for the specified property name or null if the property with such name is not configured.

See Also:

Configuration

getFeatures

java.util.Collection<Feature> getFeatures()

Get the immutable set of enabled features.

Returns:

the enabled feature set. The returned value shall never be null.

getProviderClasses

java.util.Set<java.lang.Class<?>> getProviderClasses()

Get the immutable set of registered provider classes to be instantiated, injected and utilized in the scope of the configured instance.

A provider class is a Java class with a Provider annotation declared on the class that implements a specific service interface.

Returns:

the immutable set of registered provider classes. The returned value shall never be null.

See Also:

getProviderInstances()

getProviderInstances

java.util.Set<java.lang.Object> getProviderInstances()

Get the immutable set of registered provider instances to be utilized by the configured instance.

When the configured instance is initialized the set of provider instances will be combined and take precedence over the instantiated registered provider classes.

Returns:

the immutable set of registered provider instances. The returned value shall never be null.

See Also:

getProviderClasses()

update

Configuration update(Configuration 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)

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

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 provider is a client-side feature, this Configuration object instantiates the feature and invokes the Feature.onEnable(javax.ws.rs.client.Configuration) method and lets the feature update it's internal configuration state. If the invocation of Feature.onEnable(javax.ws.rs.client.Configuration) returns true the feature is added to the collection of enabled features, otherwise the feature instance is discarded.

Parameters:

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

Returns:

the updated configuration.

See Also:

getProviderClasses()

register

Configuration register(java.lang.Object provider)

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

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 provider is a client-side feature, this Configuration object invokes the Feature.onEnable(javax.ws.rs.client.Configuration) method and lets the feature update it's internal configuration state. If the invocation of Feature.onEnable(javax.ws.rs.client.Configuration) returns true the feature is added to the collection of enabled features, otherwise the feature instance is discarded.

Parameters:

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

Returns:

the updated configuration.

See Also:

getProviderInstances()

setProperties

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

Set new configuration properties replacing all previously set properties.

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 configuration.

See Also:

Configuration

setProperty

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. Setting a null value into a property effectively removes the property from the property bag.

Parameters:

name - property name.

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

Returns:

the updated configuration.

See Also:

Configuration