spec/chapters/environment.tex - jsr311 - Git at Google

 \chapter{Environment}
 \label{environment}

 The container-managed resources available to a \jaxrs\ root resource class or provider depend on the environment in which it is deployed. Section \ref{contexttypes} describes the types of context available regardless of container. The following sections describe the additional container-managed resources available to a \jaxrs\ root resource class or provider deployed in a variety of environments.

 \section{Servlet Container}
 \label{servlet_container}

 The \Context\ annotation can be used to indicate a dependency on a Servlet-defined resource. A Servlet-based implementation MUST support injection of the following Servlet-defined types: \code{Servlet\-Config}, \code{Servlet\-Context}, \code{Http\-Servlet\-Request} and \code{Http\-Servlet\-Response}.

 An injected \code{Http\-Servlet\-Request} allows a resource method to stream the contents of a request entity. If the resource method has a parameter whose value is derived from the request entity then the stream will have already been consumed and an attempt to access it MAY result in an exception.

 An injected \code{Http\-Servlet\-Response} allows a resource method to commit the HTTP response prior to returning. An implementation MUST check the committed status and only process the return value if the response is not yet committed.

 Servlet filters may trigger consumption of a request body by accessing request parameters. In a servlet container the @FormParam annotation and the standard entity provider for \code{application\-/x-\-www-\-form-\-urlencoded} MUST obtain their values from the servlet request parameters if the request body has already been consumed. Servlet APIs do not differentiate between parameters in the URI and body of a request so URI-based query parameters may be included in the entity parameter.

 \section{Java EE Container}
 \label{javaee}

 This section describes the additional requirements that apply to a \jaxrs\ implementation when combined in a product that supports these other Java specifications:

 \begin{itemize}
 \item In a product that also supports the Servlet specification, implementations MUST support \jaxrs\ applications that are packaged as a web application, see section \ref{servlet}.
 \item In a product that also supports Managed Beans, implementations MUST support use of Managed Beans as root resource classes, providers and \code{Application} subclasses. All such classes may make use of any container-supplied facilities including dependency injection and interceptors. Providers and \code{Application} subclasses MUST be singletons or use application scope.
 \item In a product that also supports EJB, an implementation MUST support use of stateless and singleton session beans as root resource classes, providers and \code{Application} subclasses in a Web application. \jaxrs\ annotations MAY be applied to a beanÕs local interface or directly to a no-interface bean. If an \code{Exception\-Mapper} for a \code{EJBException} or subclass is not included with an application then exceptions thrown by an EJB resource class or provider method MUST be treated as EJB application exceptions: the embedded cause of the \code{EJBException} MUST be unwrapped and processed as described in section \ref{method_exc}.
 \end{itemize}

 \section{Other}

 Other container technologies MAY specify their own set of injectable resources but MUST, at a minimum, support access to the types of context listed in section \ref{contexttypes}.
	\chapter{Environment}
	\label{environment}

	The container-managed resources available to a \jaxrs\ root resource class or provider depend on the environment in which it is deployed. Section \ref{contexttypes} describes the types of context available regardless of container. The following sections describe the additional container-managed resources available to a \jaxrs\ root resource class or provider deployed in a variety of environments.

	\section{Servlet Container}
	\label{servlet_container}

	The \Context\ annotation can be used to indicate a dependency on a Servlet-defined resource. A Servlet-based implementation MUST support injection of the following Servlet-defined types: \code{Servlet\-Config}, \code{Servlet\-Context}, \code{Http\-Servlet\-Request} and \code{Http\-Servlet\-Response}.

	An injected \code{Http\-Servlet\-Request} allows a resource method to stream the contents of a request entity. If the resource method has a parameter whose value is derived from the request entity then the stream will have already been consumed and an attempt to access it MAY result in an exception.

	An injected \code{Http\-Servlet\-Response} allows a resource method to commit the HTTP response prior to returning. An implementation MUST check the committed status and only process the return value if the response is not yet committed.

	Servlet filters may trigger consumption of a request body by accessing request parameters. In a servlet container the @FormParam annotation and the standard entity provider for \code{application\-/x-\-www-\-form-\-urlencoded} MUST obtain their values from the servlet request parameters if the request body has already been consumed. Servlet APIs do not differentiate between parameters in the URI and body of a request so URI-based query parameters may be included in the entity parameter.

	\section{Java EE Container}
	\label{javaee}

	This section describes the additional requirements that apply to a \jaxrs\ implementation when combined in a product that supports these other Java specifications:

	\begin{itemize}
	\item In a product that also supports the Servlet specification, implementations MUST support \jaxrs\ applications that are packaged as a web application, see section \ref{servlet}.
	\item In a product that also supports Managed Beans, implementations MUST support use of Managed Beans as root resource classes, providers and \code{Application} subclasses. All such classes may make use of any container-supplied facilities including dependency injection and interceptors. Providers and \code{Application} subclasses MUST be singletons or use application scope.
	\item In a product that also supports EJB, an implementation MUST support use of stateless and singleton session beans as root resource classes, providers and \code{Application} subclasses in a Web application. \jaxrs\ annotations MAY be applied to a beanÕs local interface or directly to a no-interface bean. If an \code{Exception\-Mapper} for a \code{EJBException} or subclass is not included with an application then exceptions thrown by an EJB resource class or provider method MUST be treated as EJB application exceptions: the embedded cause of the \code{EJBException} MUST be unwrapped and processed as described in section \ref{method_exc}.
	\end{itemize}

	\section{Other}

	Other container technologies MAY specify their own set of injectable resources but MUST, at a minimum, support access to the types of context listed in section \ref{contexttypes}.