Added stuff related to GenericEntity and how to determine raw and generic types from return type and returned instance. Added acknowledgment for TypeLiteral code. Updated change log.
svn path=/trunk/; revision=358
diff --git a/spec/chapters/changes.tex b/spec/chapters/changes.tex
index 9d0e876..83b7ec2 100644
--- a/spec/chapters/changes.tex
+++ b/spec/chapters/changes.tex
@@ -3,5 +3,8 @@
\section{Changes Since Public Review Draft}
\begin{itemize}
-\item Section \ref{request_matching}: Reorganized the request matching algorithm to remove redundancy and improve readability, no functional change.
+\item Section \ref{resource_method_return}: Added text describing how to determine raw and generic types from method return type and returned instance.
+\item Section \ref{request_matching}: Reorganized the request matching algorithm to remove redundancy and improve readability, no functional change.
+\item Section \ref{reqpreproc}: Make pre-processed URIs available rather than original request URI.
+\item Section \ref{template_to_regex}: Changes to regular expressions to eliminate edge cases.
\end{itemize}
\ No newline at end of file
diff --git a/spec/chapters/intro.tex b/spec/chapters/intro.tex
index 9be65a2..30a229c 100644
--- a/spec/chapters/intro.tex
+++ b/spec/chapters/intro.tex
@@ -144,4 +144,6 @@
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.
-The following individuals (all Sun Microsystems) have also made invaluable technical contributions: Roberto Chinnici, Dianne Jiao (TCK), Ron Monzillo, Rajiv Mordani, Eduardo Pelegri-Llopart, Jakub Podlesak (RI) and Bill Shannon.
\ No newline at end of file
+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.
+
+The following individuals (all Sun Microsystems) have also made invaluable technical contributions: Roberto Chinnici, Dianne Jiao (TCK), Ron Monzillo, Rajiv Mordani, Eduardo Pelegri-Llopart, Jakub Podlesak (RI) and Bill Shannon.
diff --git a/spec/chapters/resources.tex b/spec/chapters/resources.tex
index cbe5a3d..9999faf 100644
--- a/spec/chapters/resources.tex
+++ b/spec/chapters/resources.tex
@@ -79,18 +79,53 @@
\subsection{Return Type}
\label{resource_method_return}
-Resource methods MAY return \code{void}, \Response\ or another Java type, these return types are mapped to a response entity body as follows:
+Resource methods MAY return \code{void}, \Response, \code{Generic\-Entity}, or another Java type, these return types are mapped to a response entity body as follows:
\begin{description}
\item[\code{void}] Results in an empty entity body with a 204 status code.
\item[\Response] Results in an entity body mapped from the \code{Entity} property of the \Response\ with the status code specified by the status property of the \Response. A \code{null} return value results in a 204 status code.
-\item[Other] Results in an entity body mapped from the return type. If the return value is not \code{null} a 200 status code is used, a \code{null} return value results in a 204 status code.
+\item[\code{Generic\-Entity}] Results in an entity body mapped from the \code{Entity} property of the \code{Generic\-Entity}. If the return value is not \code{null} a 200 status code is used, a \code{null} return value results in a 204 status code.
+\item[Other] Results in an entity body mapped from the class of the returned instance. If the return value is not \code{null} a 200 status code is used, a \code{null} return value results in a 204 status code.
\end{description}
-Conversion between a Java types and an entity body is the responsibility of an entity provider, see section \ref{entity_providers}.
-
Methods that need to provide additional metadata with a response should return an instance of \Response, the \Response\code{Builder} class provides a convenient way to create a \Response\ instance using a builder pattern.
+Conversion between a Java object and an entity body is the responsibility of an entity provider, see section \ref{entity_providers}. The return type of a resource method and the type of the returned instance\footnote{Or \code{Entity} property of returned instance if returning a \Response.} are used to determine the raw type and generic type supplied to the \code{isWritable} method of \MsgWrite as follows:
+
+\begin{longtable}{|l|l|l|l|}
+\hline
+\bfseries Return Type & \bfseries Returned Instance & \bfseries Raw Type & \bfseries Generic Type
+\tabularnewline
+\hline\hline\endhead
+\code{GenericEntity} & \code{GenericEntity} subclass\footnote{Use of \code{GenericEntity} always entails creation of a, usually anonymous, subclass} & \code{RawType} property & \code{Type} property \tabularnewline
+\hline
+\code{Response} & \code{GenericEntity} subclass & \code{RawType} property & \code{Type} property \tabularnewline
+\hline
+\code{Response} & \code{Object} or subclass & Class of instance & Class of instance \tabularnewline
+\hline
+\code{Other} & Return type or subclass & Class of instance & Generic type of return type \tabularnewline
+\hline
+\caption{Determining raw and generic types of return values}
+\end{longtable}
+
+To illustrate the above consider a method that always returns an instance of \code{ArrayList<String>} either directly or wrapped in some combination of \Response\ and \code{GenericEntity}. The resulting raw and generic types are shown below.
+
+\begin{longtable}{|l|l|l|l|}
+\hline
+\bfseries Return Type & \bfseries Returned Instance & \bfseries Raw Type & \bfseries Generic Type
+\tabularnewline
+\hline\hline\endhead
+\code{GenericEntity} & \code{GenericEntity<List<String>>} & \code{ArrayList<?>} & \code{List<String>} \tabularnewline
+\hline
+\code{Response} & \code{GenericEntity<List<String>>} & \code{ArrayList<?>} & \code{List<String>} \tabularnewline
+\hline
+\code{Response} & \code{ArrayList<String>} & \code{ArrayList<?>} & \code{ArrayList<?>} \tabularnewline
+\hline
+\code{List<String>} & \code{ArrayList<String>} & \code{ArrayList<?>} & \code{List<String>} \tabularnewline
+\hline
+\caption{Example raw and generic types of return values}
+\end{longtable}
+
\subsection{Exceptions}
\label{method_exc}
