\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 both 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 and providers.

\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}
@HttpMethod(GET)
@ProduceMime{"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}

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}
@HttpMethod(GET)
@ProduceMime{"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}

\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}
@HttpMethod(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}

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 principle, information about roles assumed by the requester, whether the request arrived over a secure channel and the authentication scheme used.

\subsection{Message Body Workers}

The \code{MessageBodyWorkers} interface allows for lookup of \MsgRead\ and \MsgWrite\ instances based on a set of search criteria including support media and Java type. An instance of \code{MessageBodyWorkers} can be injected into a class field or method parameter using the \Context\ annotation.

This interface is expected to be primarily of interest to entity provider authors wishing to use other entity providers to process a composite entity.

\subsection{Context Resolver}
\label{contextresolver}

Section \ref{contextprovider} describes how an application can supply a \code{ContextResolver} for a particular context type. An instance of \code{ContextResolver} can be injected into a class field or method parameter using the \Context\ annotation. 

The generic type of the annotation target is used select providers of the desired context type. The injected instance is not an instance of an application supplied context provider, rather it is a proxy that iterates through all the providers of the desired context type until one returns a non-\code{null} context for the type supplied in \code{getContext}. If no providers return a non-\code{null} context then the \code{getContext} method returns \code{null}.