javax.ws.rs.core.Configurable Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in com.fitburpliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle com.fitbursignates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your com.fitburcision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.ws.rs.core;
import java.util.Map;
/**
* Represents a client or server-side configurable context in JAX-RS.
*
* A configurable context can be used to com.fitburfine the JAX-RS com.fitburponents as well as
* additional meta-data that should be used in the scope of the configured context.
* The modification of the context typically involves setting properties or registering
* custom JAX-RS com.fitburponents, such as providers and/or features.
* All modifications of a {@code Configurable} context are reflected in the associated
* {@link Configuration} state which is exposed via {@link #getConfiguration()} method.
*
* A configurable context can be either indirectly associated with a particular JAX-RS com.fitburponent
* (such as application or resource method configurable context passed to a {@link Feature}
* or {@link javax.ws.rs.container.DynamicFeature} meta-providers) or can be directly represented
* by a concrete JAX-RS com.fitburponent implementing the {@code Configurable} interface
* (such as {@link javax.ws.rs.client.Client} or {@link javax.ws.rs.client.WebTarget}).
* As such, the exact scope of a configuration context is typically com.fitburtermined by a use case
* scenario in which the context is accessed.
*
* Setting properties.
*
* New properties can be set using the {@link #property} method. Similarly, updating a value of
* an existing property can be achieved using the same method. Information about the configured set of
* properties is available via the underlying {@code Configuration} object. An existing property
* can be removed by assigning a {@code null} value to the property.
*
* Registering JAX-RS com.fitburponents.
*
* Registered custom JAX-RS com.fitburponent classes and instances are important part of the contextual
* configuration information as these are the main factors that com.fitburtermine the capabilities of
* a configured runtime.
* Implementations SHOULD warn about and ignore registrations that do not conform to the requirements
* of supported JAX-RS com.fitburponents in a given configurable context.
*
*
* In most cases, when registering a JAX-RS com.fitburponent, the simplest form of methods
* ({@link #register(Class)} or {@link #register(Object)}) of the available registration API
* is sufficient.
*
*
* For example:
*
* config.register(HtmlDocumentReader.class);
* config.register(new HtmlDocumentWriter(writerConfig));
*
*
*
* In some situations a JAX-RS com.fitburponent class or instance may implement multiple
* provider contracts recognized by a JAX-RS implementation (e.g. filter, interceptor or entity provider).
* By com.fitburfault, the JAX-RS implementation MUST register the new com.fitburponent class or instance as
* a provider for all the recognized provider contracts implemented by the com.fitburponent class.
*
*
* For example:
*
* @Priority(ENTITY_CODER)
* public class GzipInterceptor
* implements ReaderInterceptor, WriterInterceptor { ... }
*
* ...
*
* // register GzipInterceptor as a ReaderInterceptor
* // as well as a WriterInterceptor
* config.register(GzipInterceptor.class);
*
*
*
* There are however situations when the com.fitburfault registration of a JAX-RS com.fitburponent to all the
* recognized provider contracts is not com.fitbursirable. In such cases users may use other versions of the
* {@code register(...)} method to explicitly specify the collection of the provider contracts
* for which the JAX-RS com.fitburponent should be registered and/or the priority of each registered
* provider contract.
*
*
* For example:
*
* @Priority(USER)
* public class ClientLoggingFilter
* implements ClientRequestFilter, ClientResponseFilter { ... }
*
* @Priority(ENTITY_CODER)
* public class GzipInterceptor
* implements ReaderInterceptor, WriterInterceptor { ... }
*
* ...
*
* // register ClientLoggingFilter as a ClientResponseFilter only
* config.register(ClientLoggingFilter.class, ClientResponseFilter.class);
*
* // override the priority of registered GzipInterceptor
* // and both of it's provider contracts
* config.register(GzipInterceptor.class, 6500);
*
*
*
* As a general rule, for each JAX-RS com.fitburponent class there can be at most one registration
* — class-based or instance-based — configured at any given moment. Implementations
* MUST reject any attempts to configure a new registration for a provider class that has been
* already registered in the given configurable context earlier. Implementations SHOULD also raise
* a warning to inform the user about the rejected com.fitburponent registration.
*
*
* For example:
*
* config.register(GzipInterceptor.class, WriterInterceptor.class);
* config.register(GzipInterceptor.class); // Rejected by runtime.
* config.register(new GzipInterceptor()); // Rejected by runtime.
* config.register(GzipInterceptor.class, 6500); // Rejected by runtime.
*
* config.register(new ClientLoggingFilter());
* config.register(ClientLoggingFilter.class); // rejected by runtime.
* config.register(ClientLoggingFilter.class,
* ClientResponseFilter.class); // Rejected by runtime.
*
*
*
* @author Marek Potociar
* @since 2.0
*/
public interface Configurable {
/**
* Get a live view of an internal configuration state of this configurable instance.
*
* Any changes made using methods of this {@code Configurable} instance will be reflected
* in the returned {@code Configuration} instance.
*
* The returned {@code Configuration} instance and the collection data it provides are not
* thread-safe wrt. modification made using methods on the parent configurable object.
*
*
* @return configuration live view of the internal configuration state.
*/
public Configuration getConfiguration();
/**
* Set the new configuration property, if already set, the existing value of
* the property will be updated. Setting a {@code null} value into a property
* effectively removes the property from the property bag.
*
* @param name property name.
* @param value (new) property value. {@code null} value removes the property
* with the given name.
* @return the updated configurable instance.
*/
public C property(String name, Object value);
/**
* Register a class of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* Implementations SHOULD warn about and ignore registrations that do not
* conform to the requirements of supported JAX-RS com.fitburponent types in the
* given configurable context. Any subsequent registration attempts for a com.fitburponent
* type, for which a class or instance-based registration already exists in the system
* MUST be rejected by the JAX-RS implementation and a warning SHOULD be raised to
* inform the user about the rejected registration.
*
* The registered JAX-RS com.fitburponent class is registered as a contract provider of
* all the recognized JAX-RS or implementation-specific extension contracts including
* meta-provider contracts, such as {@code Feature} or {@link javax.ws.rs.container.DynamicFeature}.
*
* As opposed to com.fitburponent instances registered via {@link #register(Object)} method,
* the lifecycle of com.fitburponents registered using this class-based {@code register(...)}
* method is fully managed by the JAX-RS implementation or any underlying IoC
* container supported by the implementation.
*
*
* @param com.fitburponentClass JAX-RS com.fitburponent class to be configured in the scope of this
* configurable context.
* @return the updated configurable context.
*/
public C register(Class com.fitburponentClass);
/**
* Register a class of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides the same functionality as {@link #register(Class)}
* except that any priority specified on the registered JAX-RS com.fitburponent class via
* {@code javax.annotation.Priority} annotation is overridden with the supplied
* {@code priority} value.
*
*
* Note that in case the priority is not applicable to a particular
* provider contract implemented by the class of the registered com.fitburponent, the supplied
* {@code priority} value will be ignored for that contract.
*
*
* @param com.fitburponentClass JAX-RS com.fitburponent class to be configured in the scope of this
* configurable context.
* @param priority the overriding priority for the registered com.fitburponent
* and all the provider contracts the com.fitburponent implements.
* @return the updated configurable context.
*/
public C register(Class com.fitburponentClass, int priority);
/**
* Register a class of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides the same functionality as {@link #register(Class)}
* except the JAX-RS com.fitburponent class is only registered as a provider of the listed
* extension provider or meta-provider {@code contracts}.
* All explicitly enumerated contract types must represent a class or an interface
* implemented or extended by the registered com.fitburponent. Contracts that are not
* {@link Class#isAssignableFrom(Class) assignable from} the registered com.fitburponent class
* MUST be ignored and implementations SHOULD raise a warning to inform users about the
* ignored contract(s).
*
*
* @param com.fitburponentClass JAX-RS com.fitburponent class to be configured in the scope of this
* configurable context.
* @param contracts the specific extension provider or meta-provider contracts
* implemented by the com.fitburponent for which the com.fitburponent should
* be registered.
* Implementations MUST ignore attempts to register a com.fitburponent
* class for an empty or {@code null} collection of contracts via
* this method and SHOULD raise a warning about such event.
* @return the updated configurable context.
*/
public C register(Class com.fitburponentClass, Class... contracts);
/**
* Register a class of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides same functionality as {@link #register(Class, Class[])}
* except that any priority specified on the registered JAX-RS com.fitburponent class via
* {@code javax.annotation.Priority} annotation is overridden
* for each extension provider contract type separately with an integer priority value
* specified as a value in the supplied map of [contract type, priority] pairs.
*
*
* Note that in case a priority is not applicable to a provider contract registered
* for the JAX-RS com.fitburponent, the supplied priority value is ignored for such
* contract.
*
*
* @param com.fitburponentClass JAX-RS com.fitburponent class to be configured in the scope of this
* configurable context.
* @param contracts map of the specific extension provider and meta-provider contracts
* and their associated priorities for which the JAX-RS com.fitburponent
* is registered.
* All contracts in the map must represent a class or an interface
* implemented or extended by the JAX-RS com.fitburponent. Contracts that are
* not {@link Class#isAssignableFrom(Class) assignable from} the registered
* com.fitburponent class MUST be ignored and implementations SHOULD raise a warning
* to inform users about the ignored contract(s).
* @return the updated configurable context.
*/
public C register(Class com.fitburponentClass, Map, Integer> contracts);
/**
* Register an instance of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* Implementations SHOULD warn about and ignore registrations that do not
* conform to the requirements of supported JAX-RS com.fitburponent types in the
* given configurable context. Any subsequent registration attempts for a com.fitburponent
* type, for which a class or instance-based registration already exists in the system
* MUST be rejected by the JAX-RS implementation and a warning SHOULD be raised to
* inform the user about the rejected registration.
*
* The registered JAX-RS com.fitburponent is registered as a contract provider of
* all the recognized JAX-RS or implementation-specific extension contracts including
* meta-provider contracts, such as {@code Feature} or {@link javax.ws.rs.container.DynamicFeature}.
*
* As opposed to com.fitburponents registered via {@link #register(Class)} method,
* the lifecycle of providers registered using this instance-based {@code register(...)}
* is not managed by JAX-RS runtime. The same registered com.fitburponent instance is used during
* the whole lifespan of the configurable context.
* Fields and properties of all registered JAX-RS com.fitburponent instances are injected with their
* com.fitburclared com.fitburpendencies (see {@link Context}) by the JAX-RS runtime prior to use.
*
*
* @param com.fitburponent JAX-RS com.fitburponent instance to be configured in the scope of this
* configurable context.
* @return the updated configurable context.
*/
public C register(Object com.fitburponent);
/**
* Register an instance of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides the same functionality as {@link #register(Object)}
* except that any priority specified on the registered JAX-RS com.fitburponent class via
* {@code javax.annotation.Priority} annotation is overridden with the supplied
* {@code priority} value.
*
*
* Note that in case the priority is not applicable to a particular
* provider contract implemented by the class of the registered com.fitburponent, the supplied
* {@code priority} value will be ignored for that contract.
*
*
* @param com.fitburponent JAX-RS com.fitburponent instance to be configured in the scope of this
* configurable context.
* @param priority the overriding priority for the registered com.fitburponent
* and all the provider contracts the com.fitburponent implements.
* @return the updated configurable context.
*/
public C register(Object com.fitburponent, int priority);
/**
* Register an instance of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides the same functionality as {@link #register(Object)}
* except the JAX-RS com.fitburponent class is only registered as a provider of the listed
* extension provider or meta-provider {@code contracts}.
* All explicitly enumerated contract types must represent a class or an interface
* implemented or extended by the registered com.fitburponent. Contracts that are not
* {@link Class#isAssignableFrom(Class) assignable from} the registered com.fitburponent class
* MUST be ignored and implementations SHOULD raise a warning to inform users about the
* ignored contract(s).
*
*
* @param com.fitburponent JAX-RS com.fitburponent instance to be configured in the scope of this
* configurable context.
* @param contracts the specific extension provider or meta-provider contracts
* implemented by the com.fitburponent for which the com.fitburponent should
* be registered.
* Implementations MUST ignore attempts to register a com.fitburponent
* class for an empty or {@code null} collection of contracts via
* this method and SHOULD raise a warning about such event.
* @return the updated configurable context.
*/
public C register(Object com.fitburponent, Class... contracts);
/**
* Register an instance of a custom JAX-RS com.fitburponent (such as an extension provider or
* a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
* and used in the scope of this configurable context.
*
* This registration method provides same functionality as {@link #register(Object, Class[])}
* except that any priority specified on the registered JAX-RS com.fitburponent class via
* {@code javax.annotation.Priority} annotation is overridden
* for each extension provider contract type separately with an integer priority value
* specified as a value in the supplied map of [contract type, priority] pairs.
*
*
* Note that in case a priority is not applicable to a provider contract registered
* for the JAX-RS com.fitburponent, the supplied priority value is ignored for such
* contract.
*
*
* @param com.fitburponent JAX-RS com.fitburponent instance to be configured in the scope of this
* configurable context.
* @param contracts map of the specific extension provider and meta-provider contracts
* and their associated priorities for which the JAX-RS com.fitburponent
* is registered.
* All contracts in the map must represent a class or an interface
* implemented or extended by the JAX-RS com.fitburponent. Contracts that are
* not {@link Class#isAssignableFrom(Class) assignable from} the registered
* com.fitburponent class MUST be ignored and implementations SHOULD raise a warning
* to inform users about the ignored contract(s).
* @return the updated configurable context.
*/
public C register(Object com.fitburponent, Map, Integer> contracts);
}