javax.ws.rs.core
Interface Configurable

All Known Subinterfaces:

Configuration

public interface Configurable

A configurable JAX-RS runtime context. The exact scope of the configurable context is typically determined by a use case scenario in which the configurable context is accessed.

A configurable context may be used to retrieve or updated configuration of the bound run-time component. The modification of the context typically involves setting properties or registering new providers and/or features.

Registering providers and/or features.

In some situations a provider class or instance may implement multiple contracts recognized by a JAX-RS implementation (e.g. filter, interceptor or entity provider). By default, the JAX-RS implementation will register the provider as a provider for all the recognized implemented contracts. For example:

 public class MyProvider
         implements ReaderInterceptor, WriterInterceptor { ... }

 ...

 // register MyProvider as a ReaderInterceptor
 // as well as a WriterInterceptor
 configuration.register(MyProvider.class);
 

However there are some situations when the default registration to all the recognized contracts is not desirable. In such case the users may use a version of the register(...) method that allows to explicitly list the contracts for which the provider class should be registered, effectively limiting the scope of the provider. For example:

 public class ClientLoggingFilter
         implements ClientRequestFilter, ClientResponseFilter { ... }

 ...

 ClientLoggingFilter loggingFilter = ...;
 // register loggingFilter as a ClientResponseFilter only
 configuration.register(loggingFilter, ClientResponseFilter.class);
 

Since:

2.0

Author:

Marek Potociar

Method Summary

java.util.Collection<Feature>	getFeatures() Get the immutable set of configured 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 (excluding features).
java.util.Set<java.lang.Object>	getProviderInstances() Get the immutable set of registered provider instances to be utilized by the configured instance (excluding features).
Configurable	register(java.lang.Class<?> providerClass) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
Configurable	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> Configurable	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> Configurable	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.
Configurable	register(java.lang.Object provider) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
<T> Configurable	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.
Configurable	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> Configurable	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.
Configurable	setProperties(java.util.Map<java.lang.String,?> properties) Set new configuration properties replacing all previously set properties.
Configurable	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.

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.

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.

setProperties

Configurable setProperties(java.util.Map<java.lang.String,?> 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 configurable instance.

setProperty

Configurable 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 configurable instance.

getFeatures

java.util.Collection<Feature> getFeatures()

Get the immutable set of configured features.

The returned set contains the features that have already been successfully configured in this configuration context.

Returns:

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

See Also:

Feature.configure(Configurable)

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 (excluding features).

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 (excluding features).

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

register

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

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.

Parameters:

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

Returns:

the updated configurable instance.

register

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

This registration method provides same functionality as 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.

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

This registration method provides same functionality as 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.

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

This registration method provides same functionality as 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.

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

Configurable register(java.lang.Object provider)

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.

Parameters:

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

Returns:

the updated configurable instance.

register

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

This registration method provides same functionality as 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.

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

This registration method provides same functionality as 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.

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

This registration method provides same functionality as 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.

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.