Added new appendix listing supported HTTP headers.
svn path=/trunk/; revision=435
diff --git a/spec/chapters/annotations.tex b/spec/chapters/annotations.tex
index d34e194..8adb8a5 100644
--- a/spec/chapters/annotations.tex
+++ b/spec/chapters/annotations.tex
@@ -1,5 +1,5 @@
\chapter{Summary of Annotations}
-\center
+\begin{center}
\begin{longtable}{|l|p{1.2in}|p{3.5in}|}
\hline
\bfseries Annotation & \bfseries Target & \bfseries Description \tabularnewline
@@ -43,3 +43,4 @@
\code{Provider} & \raggedright Type & \raggedright Specifies that the annotated class implements a \jaxrs\ extension interface. \tabularnewline
\hline
\end{longtable}
+\end{center}
diff --git a/spec/chapters/changes.tex b/spec/chapters/changes.tex
index ef1300b..b57d198 100644
--- a/spec/chapters/changes.tex
+++ b/spec/chapters/changes.tex
@@ -14,4 +14,7 @@
\item Section \ref{standard_entity_providers}: Require standard JAXB entity providers to use application-supplied JAXB contexts in preference to their own.
\item Section \ref{contextprovider}: Add support for specifying media type capabilities of context providers.
\item Renamed ApplicationConfig class to Application.
+\item Template parameters can specify the regular expression that forms their capturing group.
+\item UriBuilder reworked to always encode components.
+\item Chapter \ref{headersupport} added to describe where particular HTTP headers are supported.
\end{itemize}
\ No newline at end of file
diff --git a/spec/chapters/context.tex b/spec/chapters/context.tex
index d8abe6b..44958ab 100644
--- a/spec/chapters/context.tex
+++ b/spec/chapters/context.tex
@@ -32,6 +32,7 @@
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:
@@ -53,6 +54,7 @@
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:
@@ -72,6 +74,7 @@
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 principle, information about roles assumed by the requester, whether the request arrived over a secure channel and the authentication scheme used.
diff --git a/spec/chapters/headers.tex b/spec/chapters/headers.tex
new file mode 100644
index 0000000..4ffe6bd
--- /dev/null
+++ b/spec/chapters/headers.tex
@@ -0,0 +1,62 @@
+\chapter{HTTP Header Support}
+\label{headersupport}
+
+The following table lists HTTP headers that are directly supported, either automatically by a \jaxrs\ implementation runtime or by an application using the \jaxrs\ API. Any request header may be obtained using \HttpHeaders, see section \ref{httpheaders}; response headers not listed here may set using the \ResponseBuilder\-\code{.header} method.
+
+\begin{center}
+\begin{longtable}{|l|p{4.5in}|}
+\hline
+\bfseries Header & \bfseries Description \tabularnewline
+\hline\hline\endhead
+\code{Accept} & \raggedright Used by runtime when selecting a resource method, compared to value of \Produces\ annotation, see section \ref{declaring_method_capabilities}. \tabularnewline
+\hline
+\code{Accept-Charset} & \raggedright Processed by runtime if application uses \Request\code{.selectVariant} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{Accept-Encoding} & \raggedright Processed by runtime if application uses \Request\code{.selectVariant} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{Accept-Language} & \raggedright Processed by runtime if application uses \Request\code{.selectVariant} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{Allow} & \raggedright Included in automatically generated 405 error responses (see section \ref{request_matching}) and automatically generated responses to OPTIONS requests (see section \ref{head_and_options}).\tabularnewline
+\hline
+\code{Authorization} & \raggedright Depends on container, information available via \SecurityContext, see section \ref{security_context}. \tabularnewline
+\hline
+\code{Cache-Control} & \raggedright See \code{CacheControl} class and \ResponseBuilder\code{.cacheControl} method. \tabularnewline
+\hline
+\code{Content-Encoding} & \raggedright Response header set by application using \Response\code{.ok} or \ResponseBuilder\code{.variant}. \tabularnewline
+\hline
+\code{Content-Language} & \raggedright Response header set by application using \Response\code{.ok}, \ResponseBuilder\code{.language}, or \ResponseBuilder\code{.variant}. \tabularnewline
+\hline
+\code{Content-Length} & \raggedright Processed automatically for requests, set automatically in responses if value is provided by the \MsgWrite\ used to serialize the response entity. \tabularnewline
+\hline
+\code{Content-Type} & \raggedright Request header used by runtime when selecting a resource method, compared to value of \Consumes\ annotation, see section \ref{declaring_method_capabilities}. Response header either set by application using \Response\code{.ok}, \ResponseBuilder\code{.type}, or \ResponseBuilder\code{.variant}, or set automatically by runtime (see section \ref{determine_response_type}).\tabularnewline
+\hline
+\code{Cookie} & \raggedright See \code{Cookie} class and \HttpHeaders\code{.getCookies} method. \tabularnewline
+\hline
+\code{Date} & \raggedright Included in responses automatically as per HTTP/1.1. \tabularnewline
+\hline
+\code{ETag} & \raggedright See \code{EntityTag} class, \Response\code{.notModified} method and \ResponseBuilder\code{.tag} method. \tabularnewline
+\hline
+\code{Expect} & \raggedright Depends on underlying container. \tabularnewline
+\hline
+\code{If-Match} & \raggedright Processed by runtime if application uses corresponding \Request\code{.evaluatePreconditions} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{If-Modified-Since} & \raggedright Processed by runtime if application uses corresponding \Request\code{.evaluatePreconditions} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{If-None-Match} & \raggedright Processed by runtime if application uses corresponding \Request\code{.evaluatePreconditions} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{If-Unmodified-Since} & \raggedright Processed by runtime if application uses corresponding \Request\code{.evaluatePreconditions} method, see section \ref{conneg_and_preconditions}. \tabularnewline
+\hline
+\code{Last-Modified} & \raggedright Set by application using the \ResponseBuilder\code{.lastModified} method. \tabularnewline
+\hline
+\code{Location} & \raggedright Set by application using the applicable \Response\ method or directly using the \ResponseBuilder\code{.location} method.\tabularnewline
+\hline
+\code{Set-Cookie} & \raggedright See \code{NewCookie} class and \ResponseBuilder\code{.cookie} method. \tabularnewline
+\hline
+\code{Transfer-Encoding} & \raggedright See section \ref{transfer_encoding}. \tabularnewline
+\hline
+\code{Vary} & \raggedright Set by application using \Response\code{.notAcceptable} method or \ResponseBuilder\code{.variants} method. \tabularnewline
+\hline
+\code{WWW-Authenticate} & \raggedright Depends on container. \tabularnewline
+\hline
+\end{longtable}
+\end{center}
diff --git a/spec/chapters/intro.tex b/spec/chapters/intro.tex
index 30a229c..b34645e 100644
--- a/spec/chapters/intro.tex
+++ b/spec/chapters/intro.tex
@@ -127,6 +127,7 @@
Hao He (Individual Member) \\
Ryan Heaton (Individual Member) \\
David Hensley (Individual Member) \\
+Stephan Koops (Individual Member) \\
Changshin Lee (NCsoft Corporation) \\
Francois Leygues (Alcatel-Lucent) \\
Jerome Louvel (Individual Member) \\
@@ -142,7 +143,7 @@
\section{Acknowledgements}
-During the course of the JSR we have received many excellent suggestions on the JSR and Jersey (RI) mailing lists, thanks in particular to Stephan Koops (Hochschule f\"{u}r Angewandte Wissenschaften Hamburg) and Bill Burke (Red Hat) for their contributions.
+During the course of the JSR we have received many excellent suggestions on the JSR and Jersey (RI) mailing lists, thanks in particular to Stephan Koops (Hamburg University of Applied Sciences) and Bill Burke (Red Hat) for their contributions.
The \code{GenericEntity} class was inspired by the Google Guice \code{Type\-Literal} class. Our thanks to Bob Lee and Google for donating this class to \jaxrs.
diff --git a/spec/chapters/providers.tex b/spec/chapters/providers.tex
index 7b4638a..605d856 100644
--- a/spec/chapters/providers.tex
+++ b/spec/chapters/providers.tex
@@ -91,6 +91,7 @@
An implementation MUST support application-provided entity providers and MUST use those in preference to its own pre-packaged providers when either could handle the same request.
\subsection{Transfer Encoding}
+\label{transfer_encoding}
Transfer encoding for inbound data is handled by a component of the container or the \jaxrs\ runtime. \MsgRead\ providers always operate on the decoded HTTP entity body rather than directly on the HTTP message body.
diff --git a/spec/chapters/resources.tex b/spec/chapters/resources.tex
index 6f1d814..19a37bc 100644
--- a/spec/chapters/resources.tex
+++ b/spec/chapters/resources.tex
@@ -417,6 +417,7 @@
Note that the above renders the name of template variables irrelevant for template matching purposes. However, implementations will need to retain template variable names in order to facilitate the extraction of template variable values via \PathParam\ or \UriInfo\code{.getTemplateParameters}.
\section{Determining the MediaType of Responses}
+\label{determine_response_type}
In many cases it is not possible to statically determine the media type of a response. The following algorithm is used to determine the response media type, $M_{\mbox{selected}}$, at run time:
diff --git a/spec/spec.tex b/spec/spec.tex
index c103c48..e933850 100644
--- a/spec/spec.tex
+++ b/spec/spec.tex
@@ -92,6 +92,7 @@
\ \thechapter.\ #1}{}}
\include{chapters/annotations}
+\include{chapters/headers}
\include{chapters/changes}
\backmatter
