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 features available to an application hosted in a Java EE 6 container that supports \jaxrs.

 An implementation MUST support applications packaged as described in section \ref{servlet}. An implementation MUST support use of session beans as root resource classes and stateless session and singleton beans as providers in a Web application. \jaxrs\ annotations MAY be applied to a bean's local interface or directly to a no-interface bean.

 \begin{note}The new \code{java:module} JNDI context enables easy lookup of a bean instance given a bean local interface or class name.\end{note}

 In a container that also includes support for JSR-299 (Contexts and Dependency Injection for Java), an implementation MUST support use of JSR-299 beans as root resource classes, providers and as \code{Application} subclasses in a Web application. \code{Provider} and \code{Application} classes MUST use application scope. \jaxrs\ annotations MAY be directly applied to JSR-299 beans and the \jaxrs\ implementation MUST the appropriate APIs to obtain bean instances that use JSR-299 facilities.

 \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 features available to an application hosted in a Java EE 6 container that supports \jaxrs.

	An implementation MUST support applications packaged as described in section \ref{servlet}. An implementation MUST support use of session beans as root resource classes and stateless session and singleton beans as providers in a Web application. \jaxrs\ annotations MAY be applied to a bean's local interface or directly to a no-interface bean.

	\begin{note}The new \code{java:module} JNDI context enables easy lookup of a bean instance given a bean local interface or class name.\end{note}

	In a container that also includes support for JSR-299 (Contexts and Dependency Injection for Java), an implementation MUST support use of JSR-299 beans as root resource classes, providers and as \code{Application} subclasses in a Web application. \code{Provider} and \code{Application} classes MUST use application scope. \jaxrs\ annotations MAY be directly applied to JSR-299 beans and the \jaxrs\ implementation MUST the appropriate APIs to obtain bean instances that use JSR-299 facilities.

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