spec/chapters/context.tex

\chapter{Context}
\label{context}

\jaxrs\ provides facilities for obtaining and processing information about the application deployment context and the context of individual requests. Such information is available to \code{Application} subclasses (see section \ref{config}), root resource classes (see chapter \ref{resources}), and providers (see chapter \ref{providers}). This chapter describes these facilities.

\section{Concurrency}

Context is specific to a particular request but instances of certain \jaxrs\ components (providers and resource classes with a lifecycle other than per-request) may need to support multiple concurrent requests. When injecting an instance of one of the types listed in section \ref{contexttypes}, the instance supplied MUST be capable of selecting the correct context for a particular request. Use of a thread-local proxy is a common way to achieve this.

\section{Context Types}
\label{contexttypes}

This section describes the types of context available to resource classes, providers and \code{Application} subclasses.

\subsection{Application}

The instance of the application-supplied \code{Application} subclass can be injected into a class field or method parameter using the \Context\ annotation. Access to the \code{Application} subclass instance allows configuration information to be centralized in that class. Note that this cannot be injected into the \code{Application} subclass itself since this would create a circular dependency.

\subsection{URIs and URI Templates}

An instance of \UriInfo\ can be injected into a class field or method parameter using the \Context\ annotation. \UriInfo\ provides both static and dynamic, per-request information, about the components of a request URI. E.g. the following would return the names of any query parameters in a request:

\begin{listing}{1}
@GET
@Produces{"text/plain"}
public String listQueryParamNames(@Context UriInfo info) {
  StringBuilder buf = new StringBuilder();
  for (String param: info.getQueryParameters().keySet()) {
    buf.append(param);
    buf.append("\n");
  }
  return buf.toString();
}
\end{listing}

Note that the methods of \UriInfo\ provide access to request URI information following the pre-processing described in section \ref{reqpreproc}.

\subsection{Headers}
\label{httpheaders}

An instance of \HttpHeaders\ can be injected into a class field or method parameter using the \Context\ annotation. \HttpHeaders\ provides access to request header information either in map form or via strongly typed convenience methods. E.g. the following would return the names of all the headers in a request:

\begin{listing}{1}
@GET
@Produces{"text/plain"}
public String listHeaderNames(@Context HttpHeaders headers) {
  StringBuilder buf = new StringBuilder();
  for (String header: headers.getRequestHeaders().keySet()) {
    buf.append(header);
    buf.append("\n");
  }
  return buf.toString();
}
\end{listing}

Note that the methods of \HttpHeaders\ provide access to request information following the pre-processing described in section \ref{reqpreproc}.

Response headers may be provided using the \Response\ class, see \ref{resource_method_return} for more details.

\subsection{Content Negotiation and Preconditions}
\label{conneg_and_preconditions}

\jaxrs\ simplifies support for content negotiation and preconditions using the \Request\ interface. An instance of \Request\ can be injected into a class field or method parameter using the \Context\ annotation. The methods of \Request\ allow a caller to determine the best matching representation variant and to evaluate whether the current state of the resource matches any preconditions in the request. Precondition support methods return a \ResponseBuilder\ that can be returned to the client to inform it that the request preconditions were not met. E.g. the following checks if the current entity tag matches any preconditions in the request before updating the resource:

\begin{listing}{1}
@PUT
public Response updateFoo(@Context Request request, Foo foo) {
	EntityTag tag = getCurrentTag();
	ResponseBuilder responseBuilder = request.evaluatePreconditions(tag);
	if (responseBuilder != null)
	  return responseBuilder.build();
	else
	  return doUpdate(foo);
}
\end{listing}


The application could also set the content location, expiry date and cache control information into the returned \code{ResponseBuilder} before building the response.

\subsection{Security Context}
\label{security_context}

The \SecurityContext\ interface provides access to information about the security context of the current request. An instance of \SecurityContext\ can be injected into a class field or method parameter using the \Context\ annotation. The methods of \SecurityContext\ provide access to the current user principal, information about roles assumed by the requester, whether the request arrived over a secure channel and the authentication scheme used.

\subsection{Providers}
\label{providercontext}

The \code{Providers} interface allows for lookup of provider instances based on a set of search criteria. An instance of \code{Providers} can be injected into a class field or method parameter using the \Context\ annotation.

This interface is expected to be primarily of interest to provider authors wishing to use other providers functionality.