spec/chapters/providers.tex

\chapter{Providers}

The \jaxrs\ runtime is extended using application-supplied provider classes. A provider is annotated with \Provider\ and implements one or more interfaces defined by \jaxrs.

\section{Entity Providers}
\label{entity_providers}

Entity providers supply mapping services between representations and their associated Java types. Entity providers come in two flavors: \MsgRead\ and \MsgWrite\ described below.

\subsection{Message Body Reader}
\label{message_body_reader}

The \MsgRead\ interface defines the contract between the \jaxrs\ runtime and components that provide mapping services from representations to a corresponding Java type. A class wishing to provide such a service implements the \MsgRead\ interface and is annotated with \Provider.

The following describes the logical\footnote{Implementations are free to optimize their processing provided the results are equivalent to those that would be obtained if these steps are followed.} steps taken by a \jaxrs\ implementation when mapping a request entity body to a Java method parameter:

\begin{enumerate}
\item Identify the Java type of the parameter whose value will be mapped from the entity body. Section \ref{mapping_requests_to_java_methods} describes how the Java method is chosen.
\item Select the set of \MsgRead\ classes that support the media type of the request, see section \ref{declaring_provider_capabilities}.
\item Iterate through the selected \MsgRead\ classes and, utilizing the \code{isReadable} method of each, choose a \MsgRead\ provider that supports the desired Java type.
\item Use the \code{readFrom} method of the chosen \MsgRead\ to map the entity body to the desired Java type.
\end{enumerate}

\subsection{Message Body Writer}
\label{message_body_writer}

The \MsgWrite\ interface defines the contract between the \jaxrs\ runtime and components that provide mapping services from a Java type to a representation. A class wishing to provide such a service implements the \MsgWrite\ interface and is annotated with \Provider.

The following describes the logical steps taken by a \jaxrs\ implementation when mapping a return value to a response entity body:

\begin{enumerate}
\item Obtain the object that will be mapped to the response entity body. For a return type of \Response\ or subclasses the object is the value of the \code{entity} property, for other return types it is the returned object.
\item Obtain the effective value of \ProduceMime\ (see section \ref{declaring_method_capabilities}) and intersect that with the requested response formats to obtain set of permissible media types for the response entity body. Note that section \ref{mapping_requests_to_java_methods} ensures that this set will not be empty.
\item Select the set of \MsgWrite\ providers that support (see section \ref{declaring_provider_capabilities}) one or more of the permissible media types for the response entity body.
\item Sort the selected \MsgWrite\ providers as described in section \ref{declaring_provider_capabilities}.
\item Iterate through the sorted \MsgWrite\ providers and, utilizing the \code{isWriteable} method of each, choose an \MsgWrite\ that supports the object that will be mapped to the entity body.
\item Use the \code{writeTo} method of the chosen \MsgWrite\ provider to map the object to the entity body.
\end{enumerate}

\subsection{Declaring Media Type Capabilities}
\label{declaring_provider_capabilities}

Message body readers and writers MAY restrict the media types they support using the \ConsumeMime\ and \ProduceMime\ annotations respectively. The absence of these annotations is equivalent to their inclusion with media type (\lq\lq*/*\rq\rq), i.e. absence implies that any media type is supported. An implementation MUST NOT use an entity provider for a media type that is not supported by that provider.

When choosing an entity provider an implementation sorts the available providers according to the media types they declare support for. Sorting of media types follows the general rule: x/y $<$ x/* $<$ */*, i.e. a provider that explicitly lists a media types is sorted before a provider that lists */*. Quality parameter values are also used such that x/y;q=1.0 $<$ x/y;q=0.7.

\subsection{Standard Entity Providers}
\label{standard_entity_providers}

An implementation MUST include pre-packaged \MsgRead\ and \MsgWrite\ implementations for the following Java and media type combinations:

\begin{description}
\item[\code{byte[]}] All media types (\code{*/*}).
\item[\code{java.lang.String}] All text media types (\code{text/*}).
\item[\code{java.io.InputStream}] All media types (\code{*/*}).
\item[\code{java.io.File}] All media types (\code{*/*}).
\item[\code{javax.activation.DataSource}] All media types (\code{*/*}).
\item[\code{javax.transform.Source}] XML types (\code{text/xml}, \code{application\-/\-xml} and \code{application\-/\-*+xml}).
\item[\code{javax.xml.bind.JAXBElement} and application-supplied JAXB classes] XML media types (\code{text\-/\-xml}, \code{application/xml} and \code{application/*+xml}).
\item[\code{MultivaluedMap<String,String>}] Form content (\code{application/x-www-form-urlencoded}).
\end{description}

An implementation MUST support application-provided entity providers and MUST use those in preference to its own pre-packaged providers when either could handle the same request.

\subsection{Transfer Encoding}

Transfer encoding for inbound data is handled by a component of the container or the \jaxrs\ runtime. \MsgRead\ providers always operate on the decoded HTTP entity body rather than directly on the HTTP message body.

\begin{ednote}Should JAX-RS require support for specific transfer encodings ?\end{ednote}

A JAX-RS runtime or container MAY transfer encode outbound data or this MAY be done by an application returning a suitable \Response\ instance.

\subsection{Content Encoding}

Content encoding is the responsibility of the application. Application-supplied entity providers MAY perform such encoding and manipulate the HTTP headers accordingly.