javax.ws.rs.core
Interface Configurable

All Known Subinterfaces:

Configuration

All Known Implementing Classes:

ClientConfiguration, ResteasyProviderFactory, ThreadLocalResteasyProviderFactory

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

Collection<Feature>	getEnabledFeatures() Get the immutable set of features that have been successfully configured within the current configurable context.
Set<Class<?>>	getFeatureClasses() Get the immutable set of registered feature classes to be instantiated, injected and Feature.configure(Configurable) configured} in the scope of the configured instance.
Set<Object>	getFeatureInstances() Get the immutable set of registered feature instances to be Feature.configure(Configurable) configured} in the scope of the configured instance.
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 (excluding pure feature providers).
Set<Object>	getProviderInstances() Get the immutable set of registered provider instances to be utilized by the configured instance (excluding pure feature providers).
Configurable	register(Class<?> providerClass) Register a provider or a feature class to be instantiated and used in the scope of the configured instance.
Configurable	register(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(Class<T> providerClass, 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(Class<T> providerClass, int bindingPriority, 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(Object provider) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
<T> Configurable	register(Object provider, Class<? super T>... contracts) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
Configurable	register(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(Object provider, int bindingPriority, Class<? super T>... contracts) Register a provider or a feature ("singleton") instance to be used in the scope of the configured instance.
Configurable	setProperties(Map<String,?> properties) Set new configuration properties replacing all previously set properties.
Configurable	setProperty(String name, Object value) Set the new configuration property, if already set, the existing value of the property will be updated.

Method Detail

getProperties

Map<String,Object> getProperties()

Get the immutable bag of configuration properties.

Returns:

the immutable view of configuration properties.

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.

setProperties

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

getEnabledFeatures

Collection<Feature> getEnabledFeatures()

Get the immutable set of features that have been successfully configured within the current configurable context.

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

Note that a registered features may not be immediately available in the collection of enabled features returned this method. Implementations MAY decide to defer the feature instantiation and/or configuration to a later point in time, yet the order in which features have been registered MUST be preserved during the feature configuration phase. This method is expected to provide up-to-date information only when invoked from a feature configuration method or once the configured instance has been fully initialized.

Returns:

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

getFeatureClasses

Set<Class<?>> getFeatureClasses()

Get the immutable set of registered feature classes to be instantiated, injected and Feature.configure(Configurable) configured} in the scope of the configured instance.

Returns:

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

See Also:

getFeatureInstances()

getFeatureInstances

Set<Object> getFeatureInstances()

Get the immutable set of registered feature instances to be Feature.configure(Configurable) configured} in the scope of the configured instance.

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

Returns:

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

See Also:

getFeatureClasses()

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 (excluding pure feature providers).

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 (excluding pure feature providers).

When the configured instance is initialized the set of provider instances will be combined with 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(Class<?> providerClass)

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

As opposed to the instances registered via register(Object) method, classes registered using this method are instantiated and properly injected by the JAX-RS implementation provider. In case of a conflict between a registered feature and/or provider instance and instantiated registered class, the registered instance takes precedence and the registered 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 configurable instance.

register

Configurable register(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 is not applicable to any particular provider contract registered for the provider class, the supplied bindingPriority value will be ignored for that contract.

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(Class<T> providerClass,
                          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(Class<T> providerClass,
                          int bindingPriority,
                          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 is not applicable to any particular provider contract registered for the provider class, the supplied bindingPriority value will be ignored for that contract.

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

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

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

Parameters:

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

Returns:

the updated configurable instance.

register

Configurable register(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 is not applicable to any particular provider contract registered for the provider, the supplied bindingPriority value will be ignored for that contract.

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(Object provider,
                          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(Object provider,
                          int bindingPriority,
                          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 is not applicable to any particular provider contract registered for the provider, the supplied bindingPriority value will be ignored for that contract.

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.