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}

 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.

 \section{Java EE Container (Non-normative)}

 This section describes the additional features anticipated to be available to a \jaxrs\ application hosted in a Java EE 6 container. It is planned that \jaxrs\ will be finalized prior to Java EE 6 so the contents of this section are preliminary and subject to change. Nothing in this section should be considered a conformance requirement.

 \jaxrs\ root resource classes and providers are supplied with the same resource injection capabilities as are provided for a Servlet instance running in a Java EE Web container. In particular the following annotations may be used according to their individual semantics: \code{@Resource}, \code{@Resources}, \code{@EJB}, \code{@EJBs}, \code{@Web\-Service\-Ref}, \code{@Web\-Service\-Refs}, \code{@Persistence\-Context}, \code{@Persistence\-Contexts}, \code{@Persistence\-Unit} and \code{@Persistence\-Units}.

 \jaxrs\ root resource classes and providers may also make use of the following JSR 250 lifecycle management and security annotations:  \code{@Post\-Construct}, \code{@Pre\-Destroy}, \code{@RunAs}, \code{@Roles\-Allowed}, \code{@Permit\-All}, \code{@Deny\-All} and \code{@Declare\-Roles}.

 \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}

	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.

	\section{Java EE Container (Non-normative)}

	This section describes the additional features anticipated to be available to a \jaxrs\ application hosted in a Java EE 6 container. It is planned that \jaxrs\ will be finalized prior to Java EE 6 so the contents of this section are preliminary and subject to change. Nothing in this section should be considered a conformance requirement.

	\jaxrs\ root resource classes and providers are supplied with the same resource injection capabilities as are provided for a Servlet instance running in a Java EE Web container. In particular the following annotations may be used according to their individual semantics: \code{@Resource}, \code{@Resources}, \code{@EJB}, \code{@EJBs}, \code{@Web\-Service\-Ref}, \code{@Web\-Service\-Refs}, \code{@Persistence\-Context}, \code{@Persistence\-Contexts}, \code{@Persistence\-Unit} and \code{@Persistence\-Units}.

	\jaxrs\ root resource classes and providers may also make use of the following JSR 250 lifecycle management and security annotations: \code{@Post\-Construct}, \code{@Pre\-Destroy}, \code{@RunAs}, \code{@Roles\-Allowed}, \code{@Permit\-All}, \code{@Deny\-All} and \code{@Declare\-Roles}.

	\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}.