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 * MessageBodyReader.java
015 *
016 * Created on November 8, 2007, 3:57 PM
017 *
018 */
019
020 package javax.ws.rs.ext;
021
022 import java.io.IOException;
023 import java.io.InputStream;
024 import java.lang.annotation.Annotation;
025 import java.lang.reflect.Type;
026 import javax.ws.rs.WebApplicationException;
027 import javax.ws.rs.core.MediaType;
028 import javax.ws.rs.core.MultivaluedMap;
029
030 /**
031 * Contract for a provider that supports the conversion of a stream to a
032 * Java type. To add a <code>MessageBodyReader</code> implementation, annotate the
033 * implementation class with <code>@Provider</code>.
034 *
035 * A <code>MessageBodyReader</code> implementation may be annotated
036 * with {@link javax.ws.rs.Consumes} to restrict the media types for which it will
037 * be considered suitable.
038 *
039 * @see Provider
040 * @see javax.ws.rs.Consumes
041 */
042 public interface MessageBodyReader<T> {
043
044 /**
045 * Ascertain if the MessageBodyReader can produce an instance of a
046 * particular type. The type parameter gives the
047 * class of the object that should be produced, the genericType parameter
048 * gives the java.lang.reflect.Type of the object that should be produced.
049 * E.g. if the object to be produced is List<String>, the type parameter
050 * will be java.util.List and the genericType parameter will be
051 * java.lang.reflect.ParameterizedType.
052 *
053 * @param type the class of object to be produced.
054 * @param genericType the type of object to be produced. E.g. if the
055 * message body is to be converted into a method parameter, this will be
056 * the formal type of the method parameter as returned by
057 * <code>Method.getGenericParameterTypes</code>.
058 * @param annotations an array of the annotations on the declaration of the
059 * artifact that will be initialized with the produced instance. E.g. if the
060 * message body is to be converted into a method parameter, this will be
061 * the annotations on that parameter returned by
062 * <code>Method.getParameterAnnotations</code>.
063 * @param mediaType the media type of the HTTP entity, if one is not
064 * specified in the request then <code>application/octet-stream</code> is
065 * used.
066 * @return true if the type is supported, otherwise false.
067 */
068 boolean isReadable(Class<?> type, Type genericType,
069 Annotation annotations[], MediaType mediaType);
070
071 /**
072 * Read a type from the {@link InputStream}.
073 *
074 * @return the type that was read from the stream.
075 * @param type the type that is to be read from the entity stream.
076 * @param genericType the type of object to be produced. E.g. if the
077 * message body is to be converted into a method parameter, this will be
078 * the formal type of the method parameter as returned by
079 * <code>Method.getGenericParameterTypes</code>.
080 * @param annotations an array of the annotations on the declaration of the
081 * artifact that will be initialized with the produced instance. E.g. if the
082 * message body is to be converted into a method parameter, this will be
083 * the annotations on that parameter returned by
084 * <code>Method.getParameterAnnotations</code>.
085 * @param mediaType the media type of the HTTP entity.
086 * @param httpHeaders the read-only HTTP headers associated with HTTP entity.
087 * @param entityStream the {@link InputStream} of the HTTP entity. The
088 * caller is responsible for ensuring that the input stream ends when the
089 * entity has been consumed. The implementation should not close the input stream.
090 * @throws java.io.IOException if an IO error arises
091 * @throws javax.ws.rs.WebApplicationException if a specific
092 * HTTP error response needs to be produced. Only effective if thrown prior
093 * to the response being committed.
094 */
095 T readFrom(Class<T> type, Type genericType,
096 Annotation annotations[], MediaType mediaType,
097 MultivaluedMap<String, String> httpHeaders,
098 InputStream entityStream) throws IOException, WebApplicationException;
099
100 }