javax.ws.rs.client
Interface Configuration

public interface Configuration

Represents inheritable configuration of the main client-side JAX-RS components, such as Client, Target, 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
   Target resourceTarget = client.target("http://examples.jaxrs.com/");

   // does not modify the client instance configuration
   target.configuration().enable(new BarFeature());
 

Since:

2.0

Author:

Marek Potociar

Method Summary

Configuration	disable(Class<? extends Feature> feature) Disable a feature for the configurable instance using a feature class.
Configuration	enable(Feature feature) Enable a feature.
Set<Feature>	getFeatures() Get the immutable set of enabled features.
Map<String,Object>	getProperties() Get the immutable bag of configuration properties.
Object	getProperty(String name) Get the value for the property with a given name.
Set<Class<?>>	getProviderClasses() Get the immutable set of registered provider classes to be instantiated, injected and utilized in the scope of the configured instance.
Set<Object>	getProviderInstances() Get the immutable set of registered provider instances to be utilized by the configured instance.
boolean	isEnabled(Class<? extends Feature> feature) Determine if a certain feature is enabled or not.
Configuration	register(Class<?> providerClass) Register a provider class to be instantiated and used in the scope of the configured instance.
Configuration	register(Object provider) Register a provider ("singleton") instance to be used in the scope of the configured instance.
Configuration	setProperties(Map<String,? extends Object> properties) Set new configuration properties replacing all previously set properties.
Configuration	setProperty(String name, 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

Map<String,Object> getProperties()

Get the immutable bag of configuration properties.

Returns:

the immutable view of configuration properties.

See Also:

Configuration

getProperty

Object getProperty(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

Set<Feature> getFeatures()

Get the immutable set of enabled features.

Returns:

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

isEnabled

boolean isEnabled(Class<? extends Feature> feature)

Determine if a certain feature is enabled or not.

Parameters:

feature - the feature class.

Returns:

true if the feature is enabled, otherwise false.

See Also:

Configuration

getProviderClasses

Set<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

Set<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(Class<?> providerClass)

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

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(Object provider)

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

Parameters:

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

Returns:

the updated configuration.

See Also:

getProviderInstances()

enable

Configuration enable(Feature feature)
                     throws IllegalStateException

Enable a feature.

The Configuration instance invokes the Feature.onEnable(javax.ws.rs.client.Configuration) method and lets the feature update it's internal configuration state.

An attempt to enable an already enabled feature results in an IllegalStateException being raised.

Parameters:

feature - instance of the feature to be enabled.

Returns:

the updated configuration.

Throws:

IllegalStateException - in case the feature has already been enabled.

See Also:

Configuration

disable

Configuration disable(Class<? extends Feature> feature)
                      throws IllegalStateException

Disable a feature for the configurable instance using a feature class.

An attempt to disable a feature that is not enabled results in an IllegalStateException being raised.

Parameters:

feature - class of the feature to be disabled.

Returns:

the updated configuration.

Throws:

IllegalStateException - in case no such feature is enabled at present.

See Also:

Configuration

setProperties

Configuration setProperties(Map<String,? extends 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(String name,
                          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