001 /*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License"). You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * http://www.opensource.org/licenses/cddl1.php
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 */
012
013 /*
014 * Providers.java
015 *
016 * Created on March 5, 2008, 9:00 AM
017 *
018 */
019
020 package javax.ws.rs.ext;
021
022 import java.lang.annotation.Annotation;
023 import java.lang.reflect.Type;
024 import javax.ws.rs.core.MediaType;
025
026 /**
027 * An injectable interface providing runtime lookup of provider instances.
028 *
029 * @see javax.ws.rs.core.Context
030 * @see MessageBodyReader
031 * @see MessageBodyWriter
032 * @see ContextResolver
033 * @see ExceptionMapper
034 */
035 public interface Providers {
036
037 /**
038 * Get a message body reader that matches a set of criteria. The set of
039 * readers is first filtered by comparing the supplied value of
040 * {@code mediaType} with the value of each reader's
041 * {@link javax.ws.rs.Consumes}, ensuring the supplied value of
042 * {@code type} is assignable to the generic type of the reader, and
043 * eliminating those that do not match.
044 * The list of matching readers is then ordered with those with the best
045 * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*)
046 * sorted first. Finally, the
047 * {@link MessageBodyReader#isReadable}
048 * method is called on each reader in order using the supplied criteria and
049 * the first reader that returns {@code true} is selected and returned.
050 *
051 * @param type the class of object that is to be read.
052 * @param genericType the type of object to be produced. E.g. if the
053 * message body is to be converted into a method parameter, this will be
054 * the formal type of the method parameter as returned by
055 * <code>Class.getGenericParameterTypes</code>.
056 * @param annotations an array of the annotations on the declaration of the
057 * artifact that will be initialized with the produced instance. E.g. if the
058 * message body is to be converted into a method parameter, this will be
059 * the annotations on that parameter returned by
060 * <code>Class.getParameterAnnotations</code>.
061 * @param mediaType the media type of the data that will be read.
062 * @return a MessageBodyReader that matches the supplied criteria or null
063 * if none is found.
064 */
065 <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type,
066 Type genericType, Annotation annotations[], MediaType mediaType);
067
068 /**
069 * Get a message body writer that matches a set of criteria. The set of
070 * writers is first filtered by comparing the supplied value of
071 * {@code mediaType} with the value of each writer's
072 * {@link javax.ws.rs.Produces}, ensuring the supplied value of
073 * {@code type} is assignable to the generic type of the reader, and
074 * eliminating those that do not match.
075 * The list of matching writers is then ordered with those with the best
076 * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
077 * sorted first. Finally, the
078 * {@link MessageBodyWriter#isWriteable}
079 * method is called on each writer in order using the supplied criteria and
080 * the first writer that returns {@code true} is selected and returned.
081 *
082 * @param type the class of object that is to be written.
083 * @param genericType the type of object to be written. E.g. if the
084 * message body is to be produced from a field, this will be
085 * the declared type of the field as returned by
086 * <code>Field.getGenericType</code>.
087 * @param annotations an array of the annotations on the declaration of the
088 * artifact that will be written. E.g. if the
089 * message body is to be produced from a field, this will be
090 * the annotations on that field returned by
091 * <code>Field.getDeclaredAnnotations</code>.
092 * @param mediaType the media type of the data that will be written.
093 * @return a MessageBodyReader that matches the supplied criteria or null
094 * if none is found.
095 */
096 <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type,
097 Type genericType, Annotation annotations[], MediaType mediaType);
098
099 /**
100 * Get an exception mapping provider for a particular class of exception.
101 * Returns the provider whose generic type is the nearest superclass of
102 * {@code type}.
103 * @param type the class of exception
104 * @return an {@link ExceptionMapper} for the supplied type or null if none
105 * is found.
106 */
107 <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type);
108
109 /**
110 * Get a context resolver for a particular type of context and media type.
111 * The set of resolvers is first filtered by comparing the supplied value of
112 * {@code mediaType} with the value of each resolver's
113 * {@link javax.ws.rs.Produces}, ensuring the generic type of the context
114 * resolver is assignable to the supplied value of {@code contextType}, and
115 * eliminating those that do not match. If only one resolver matches the
116 * criteria then it is returned. If more than one resolver matches then the
117 * list of matching resolvers is ordered with those with the best
118 * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
119 * sorted first. A proxy is returned that delegates calls to
120 * {@link ContextResolver#getContext(java.lang.Class)} to each matching context
121 * resolver in order and returns the first non-null value it obtains or null
122 * if all matching context resolvers return null.
123 *
124 * @param contextType the class of context desired
125 * @param mediaType the media type of data for which a context is required.
126 * @return a matching context resolver instance or null if no matching
127 * context providers are found.
128 */
129 <T> ContextResolver<T> getContextResolver(Class<T> contextType,
130 MediaType mediaType);
131 }