javax.ws.rs.ext

## Interface MessageBodyReader<T>

- Type Parameters:
    `T` - Java type supported by the provider
  All Known Implementing Classes:
    AbstractEntityProvider, AbstractJAXBProvider, AtomEntryProvider, AtomFeedProvider, ByteArrayProvider, CollectionProvider, DataSourceProvider, DefaultTextPlain, DocumentProvider, EnvelopedReader, FastInfosetCollectionProvider, FastinfoSetElementProvider, FastInfosetMapProvider, FastinfoSetXmlRootElementProvider, FastinfoSetXmlSeeAlsoProvider, FastinfoSetXmlTypeProvider, FileProvider, FormUrlEncodedProvider, IIOImageProvider, InputStreamProvider, com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider, com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider, org.codehaus.jackson.jaxrs.JacksonJsonProvider, JAXBElementProvider, JAXBXmlRootElementProvider, JAXBXmlSeeAlsoProvider, JAXBXmlTypeProvider, JaxrsFormProvider, JettisonElementProvider, JettisonXmlRootElementProvider, JettisonXmlSeeAlsoProvider, JettisonXmlTypeProvider, JsonArrayProvider, JsonCollectionProvider, JsonMapProvider, JsonObjectProvider, JsonStructureProvider, ListMultipartReader, MapMultipartFormDataReader, MapProvider, MimeMultipartProvider, MultipartFormAnnotationReader, MultipartFormDataReader, MultipartReader, MultipartRelatedReader, MultipartSignedReader, PKCS7SignatureReader, com.fasterxml.jackson.jaxrs.base.ProviderBase, ReaderProvider, ResteasyJackson2Provider, ResteasyJacksonProvider, SerializableProvider, ServerFormUrlEncodedProvider, SourceProvider, StringBeanEntityProvider, StringTextStar, XopWithMultipartRelatedJAXBProvider, XopWithMultipartRelatedReader, YamlProvider

      public interface MessageBodyReader<T>

  Contract for a provider that supports the conversion of a stream to a Java type. A `MessageBodyReader` implementation may be annotated with `Consumes` to restrict the media types for which it will be considered suitable.

  Providers implementing `MessageBodyReader` contract must be either programmatically registered in a JAX-RS runtime or must be annotated with `@Provider` annotation to be automatically discovered by the JAX-RS runtime during a provider scanning phase.

  Since:
    1.0
  Author:
    Paul Sandoz, Marc Hadley
  See Also:
    `Provider`, `Consumes`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType)` Ascertain if the MessageBodyReader can produce an instance of a particular type.
    `T` | `readFrom(Class<T> type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap<String,String> httpHeaders, InputStream entityStream)` Read a type from the `InputStream`.

- - ### Method Detail

    - #### isReadable

          boolean isReadable(Class<?> type,
                           Type genericType,
                           Annotation[] annotations,
                           MediaType mediaType)

      Ascertain if the MessageBodyReader can produce an instance of a particular type. The `type` parameter gives the class of the instance that should be produced, the `genericType` parameter gives the `java.lang.reflect.Type` of the instance that should be produced. E.g. if the instance to be produced is `List<String>`, the `type` parameter will be `java.util.List` and the `genericType` parameter will be `java.lang.reflect.ParameterizedType`.
      Parameters:
        `type` - the class of instance to be produced.
        `genericType` - the type of instance 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 `Method.getGenericParameterTypes`.
        `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 `Method.getParameterAnnotations`.
        `mediaType` - the media type of the HTTP entity, if one is not specified in the request then `application/octet-stream` is used.
      Returns:
        `true` if the type is supported, otherwise `false`.

    - #### readFrom

          T readFrom(Class<T> type,
                   Type genericType,
                   Annotation[] annotations,
                   MediaType mediaType,
                   MultivaluedMap<String,String> httpHeaders,
                   InputStream entityStream)
                     throws IOException,
                            WebApplicationException

      Read a type from the `InputStream`.

      In case the entity input stream is empty, the reader is expected to either return a Java representation of a zero-length entity or throw a `NoContentException` in case no zero-length entity representation is defined for the supported Java type. A `NoContentException`, if thrown by a message body reader while reading a server request entity, is automatically translated by JAX-RS server runtime into a `BadRequestException` wrapping the original `NoContentException` and rethrown for a standard processing by the registered `exception mappers`.

      Parameters:
        `type` - the type that is to be read from the entity stream.
        `genericType` - the type of instance 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 `Method.getGenericParameterTypes`.
        `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 `Method.getParameterAnnotations`.
        `mediaType` - the media type of the HTTP entity.
        `httpHeaders` - the read-only HTTP headers associated with HTTP entity.
        `entityStream` - the `InputStream` of the HTTP entity. The caller is responsible for ensuring that the input stream ends when the entity has been consumed. The implementation should not close the input stream.
      Returns:
        the type that was read from the stream. In case the entity input stream is empty, the reader is expected to either return an instance representing a zero-length entity or throw a `NoContentException` in case no zero-length entity representation is defined for the supported Java type.
      Throws:
        `IOException` - if an IO error arises. In case the entity input stream is empty and the reader is not able to produce a Java representation for a zero-length entity, `NoContentException` is expected to be thrown.
        `WebApplicationException` - if a specific HTTP error response needs to be produced. Only effective if thrown prior to the response being committed.

Copyright © 2014. All Rights Reserved.