| /* |
| * The contents of this file are subject to the terms |
| * of the Common Development and Distribution License |
| * (the "License"). You may not use this file except |
| * in compliance with the License. |
| * |
| * You can obtain a copy of the license at |
| * http://www.opensource.org/licenses/cddl1.php |
| * See the License for the specific language governing |
| * permissions and limitations under the License. |
| */ |
| |
| /* |
| * Providers.java |
| * |
| * Created on March 5, 2008, 9:00 AM |
| * |
| */ |
| |
| package javax.ws.rs.ext; |
| |
| import java.lang.annotation.Annotation; |
| import java.lang.reflect.Type; |
| import javax.ws.rs.core.MediaType; |
| |
| /** |
| * An injectable interface providing runtime lookup of provider instances. |
| * |
| * @see javax.ws.rs.core.Context |
| * @see MessageBodyReader |
| * @see MessageBodyWriter |
| * @see ContextResolver |
| * @see ExceptionMapper |
| */ |
| public interface Providers { |
| |
| /** |
| * Get a message body reader that matches a set of criteria. The set of |
| * readers is first filtered by comparing the supplied value of |
| * {@code mediaType} with the value of each reader's |
| * {@link javax.ws.rs.Consumes}, ensuring the supplied value of |
| * {@code type} is assignable to the generic type of the reader, and |
| * eliminating those that do not match. |
| * The list of matching readers is then ordered with those with the best |
| * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*) |
| * sorted first. Finally, the |
| * {@link MessageBodyReader#isReadable} |
| * method is called on each reader in order using the supplied criteria and |
| * the first reader that returns {@code true} is selected and returned. |
| * |
| * @param type the class of object that is to be read. |
| * @param mediaType the media type of the data that will be read. |
| * @param genericType the type of object to be produced. E.g. if the |
| * message body is to be converted into a method parameter, this will be |
| * the formal type of the method parameter as returned by |
| * <code>Class.getGenericParameterTypes</code>. |
| * @param annotations an array of the annotations on the declaration of the |
| * artifact that will be initialized with the produced instance. E.g. if the |
| * message body is to be converted into a method parameter, this will be |
| * the annotations on that parameter returned by |
| * <code>Class.getParameterAnnotations</code>. |
| * @return a MessageBodyReader that matches the supplied criteria or null |
| * if none is found. |
| */ |
| <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type, |
| Type genericType, Annotation annotations[], MediaType mediaType); |
| |
| /** |
| * Get a message body writer that matches a set of criteria. The set of |
| * writers is first filtered by comparing the supplied value of |
| * {@code mediaType} with the value of each writer's |
| * {@link javax.ws.rs.Produces}, ensuring the supplied value of |
| * {@code type} is assignable to the generic type of the reader, and |
| * eliminating those that do not match. |
| * The list of matching writers is then ordered with those with the best |
| * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) |
| * sorted first. Finally, the |
| * {@link MessageBodyWriter#isWriteable} |
| * method is called on each writer in order using the supplied criteria and |
| * the first writer that returns {@code true} is selected and returned. |
| * |
| * @param mediaType the media type of the data that will be written. |
| * @param type the class of object that is to be written. |
| * @param genericType the type of object to be written. E.g. if the |
| * message body is to be produced from a field, this will be |
| * the declared type of the field as returned by |
| * <code>Field.getGenericType</code>. |
| * @param annotations an array of the annotations on the declaration of the |
| * artifact that will be written. E.g. if the |
| * message body is to be produced from a field, this will be |
| * the annotations on that field returned by |
| * <code>Field.getDeclaredAnnotations</code>. |
| * @return a MessageBodyReader that matches the supplied criteria or null |
| * if none is found. |
| */ |
| <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type, |
| Type genericType, Annotation annotations[], MediaType mediaType); |
| |
| /** |
| * Get an exception mapping provider for a particular class of exception. |
| * Returns the provider whose generic type is the nearest superclass of |
| * {@code type}. |
| * @param type the class of exception |
| * @return an {@link ExceptionMapper} for the supplied type or null if none |
| * is found. |
| */ |
| <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type); |
| |
| /** |
| * Get a context resolver for a particular type of context and media type. |
| * The set of resolvers is first filtered by comparing the supplied value of |
| * {@code mediaType} with the value of each resolver's |
| * {@link javax.ws.rs.Produces}, ensuring the generic type of the context |
| * resolver is assignable to the supplied value of {@code contextType}, and |
| * eliminating those that do not match. If only one resolver matches the |
| * criteria then it is returned. If more than one resolver matches then the |
| * list of matching resolvers is ordered with those with the best |
| * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) |
| * sorted first. A proxy is returned that delegates calls to |
| * {@link ContextResolver#getContext(java.lang.Class)} to each matching context |
| * resolver in order and returns the first non-null value it obtains or null |
| * if all matching context resolvers return null. |
| * |
| * @param contextType the class of context desired |
| * @param mediaType the media type of data for which a context is required. |
| * @return a matching context resolver instance or null if no matching |
| * context providers are found. |
| */ |
| <T> ContextResolver<T> getContextResolver(Class<T> contextType, |
| MediaType mediaType); |
| } |
