Runtime generates exceptions subject to exception mpping providers rather than simply returning a specific response directly
svn path=/trunk/; revision=318
diff --git a/spec/chapters/providers.tex b/spec/chapters/providers.tex
index 9155a71..34e2e1b 100644
--- a/spec/chapters/providers.tex
+++ b/spec/chapters/providers.tex
@@ -33,7 +33,7 @@
\item Select the set of \MsgRead\ classes that support the media type of the request, see section \ref{declaring_provider_capabilities}.
\item\label{findreader} Iterate through the selected \MsgRead\ classes and, utilizing the \code{isReadable} method of each, choose a \MsgRead\ provider that supports the desired Java type.
\item If step \ref{findreader} locates a suitable \MsgRead\ then use its \code{readFrom} method to map the entity body to the desired Java type.
-\item If step \ref{findreader} fails to locate a suitable \MsgRead\ then generate an unsupported media type response (HTTP 415 status).
+\item If step \ref{findreader} fails to locate a suitable \MsgRead\ then generate a \WebAppExc\ with an unsupported media type response (HTTP 415 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
\end{enumerate}
A \MsgRead\code{readFrom} method MAY throw \WebAppExc\. If thrown, the resource method is not invoked and the exception is treated as if it originated from a resource method, see section \ref{method_exc}.
@@ -52,7 +52,7 @@
\item Sort the selected \MsgWrite\ providers as described in section \ref{declaring_provider_capabilities}.
\item\label{findwriter} Iterate through the sorted \MsgWrite\ providers and, utilizing the \code{isWriteable} method of each, choose an \MsgWrite\ that supports the object that will be mapped to the entity body.
\item If step \ref{findwriter} locates a suitable \MsgWrite\ then use its \code{writeTo} method to map the object to the entity body.
-\item If step \ref{findwriter} fails to locate a suitable \MsgWrite\ then generate a not acceptable response (HTTP 406 status).
+\item If step \ref{findwriter} fails to locate a suitable \MsgWrite\ then generate a \WebAppExc\ with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
\end{enumerate}
A \MsgWrite\code{write} method MAY throw \WebAppExc. If thrown before the response is committed, the exception is treated as if it originated from a resource method, see section \ref{method_exc}. To avoid an infinite loop, implementations SHOULD NOT attempt to map exceptions thrown during serialization of an response previously mapped from an exception and SHOULD instead simply return a server error (status code 500) response.
diff --git a/spec/chapters/resources.tex b/spec/chapters/resources.tex
index dd987d6..c096257 100644
--- a/spec/chapters/resources.tex
+++ b/spec/chapters/resources.tex
@@ -51,7 +51,7 @@
The \code{Default\-Value} annotation may be used to supply a default value for some of the above, see the Javadoc for \code{Default\-Value} for usage details and rules for generating a value in the absence of this annotation and the requested data. The \code{Encoded} annotation may be used to disable automatic URI decoding for \MatrixParam, \QueryParam\ and \PathParam\ annotated fields and properties.
-Exceptions thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above are treated as client errors: if the field or property is annotated with \MatrixParam, \QueryParam\ or \PathParam\ an implementation MUST return a not found response (404 status); if the field or property is annotated with \HeaderParam\ or \CookieParam\ an implementation MUST return a client error response (400 status).
+A \WebAppExc\ thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above is processed directly as described in section \ref{method_exc}. Other exceptions thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above are treated as client errors: if the field or property is annotated with \MatrixParam, \QueryParam\ or \PathParam\ an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a not found response (404 status) and no entity; if the field or property is annotated with \HeaderParam\ or \CookieParam\ an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a client error response (400 status) and no entity. The \WebAppExc\ MUST be then be processed as described in section \ref{method_exc}.
\section{Resource Methods}
\label{resource_method}
@@ -97,10 +97,10 @@
A resource method, sub-resource method or sub-resource locator may throw any checked or unchecked exception. An implementation MUST catch all exceptions and process them as follows:
\begin{enumerate}
-\item \WebAppExc\ MUST be mapped to a response. If the \code{response} property of the exception is not \code{null} then it MUST be used to create the response. If the \code{response} property of the exception is \code{null} an implementation MUST generate a server error (status code 500) response.
+\item Instances of \WebAppExc\ MUST be mapped to a response as follows. If the \code{response} property of the exception does not contain an entity and an exception mapping provider (see section \ref{exceptionmapper}) is available for \WebAppExc\, an implementation MUST use the provider to create a new \Response\ instance, otherwise the \code{response} property is used directly. The resulting \Response\ instance is then processed according to section \ref{resource_method_return}.
\item If an exception mapping provider (see section \ref{exceptionmapper}) is available for the exception or one of its superclasses, an implementation MUST use the closest matching provider to create a \Response\ instance that is then processed according to section \ref{resource_method_return}.
\item\label{runtimeexc} Unchecked exceptions MUST be re-thrown and allowed to propagate to the underlying container.
-\item\label{checkedexc} Checked exceptions that cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container. Servlet-based implementations MUST use \code{Servlet\-Exception} as the wrapper. JAX-WS \code{Provider}-based implementations MUST use \code{Web\-Service\-Exception}.
+\item\label{checkedexc} Checked exceptions that cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container. Servlet-based implementations MUST use \code{Servlet\-Exception} as the wrapper. JAX-WS \code{Provider}-based implementations MUST use \code{Web\-Service\-Exception} as the wrapper.
\end{enumerate}
\begin{nnnote}Items \ref{runtimeexc} and \ref{checkedexc} allow existing container facilities (e.g. a Servlet filter or error pages) to be used to handle the error if desired.\end{nnnote}
@@ -348,7 +348,7 @@
\item Remove members for which the final capturing group value is neither empty nor \lq/\rq\ and the class associated with $R(T_{\mbox{class}})$ had no sub-resource methods or locators.
\end{itemize}
-\item If $E$ is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate a not found response (HTTP 404 status).
+\item If $E$ is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate a \WebAppExc\ with a not found response (HTTP 404 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
\item Sort $E$ using the number of literal characters\footnote{Here, literal characters means those not resulting from template variable substitution.} in each member as the primary key (descending order) and the number of capturing groups as a secondary key (descending order).
@@ -375,7 +375,7 @@
\item Remove members derived from $T_{\mbox{method}}$ (those added in step \ref{t_method_items}) for which the final capturing group value is neither empty nor \lq/\rq.
\end{itemize}
-\item If $E$ is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate a not found response (HTTP 404 status).
+\item If $E$ is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate a \WebAppExc\ with a not found response (HTTP 404 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
\item Sort $E$ using the number of literal characters in each member as the primary key (descending order), the number of capturing groups as a secondary key (descending order), and the source of each member as tertiary key sorting those derived from $T_{\mbox{method}}$ ahead of those derived from $T_{\mbox{locator}}$.
@@ -395,9 +395,9 @@
\item Find the set of resource methods $M$ of $O$ that meet the following criteria:
\begin{itemize}
\item If $U$ is neither empty nor equal to \lq/\rq, the method must be annotated with a URI template that, when transformed into a regular expression using the process described in section \ref{template_to_regex}, matches $U$ with a final capturing group value that is either empty or equal to \lq/\rq.
-\item The request method is supported. If no methods support the request method an implementation MUST generate a method not allowed response (HTTP 405 status). Note the additional support for \code{HEAD} and \code{OPTIONS} described in section \ref{head_and_options}.
-\item The media type of the request entity body (if any) is a supported input data format (see section \ref{declaring_method_capabilities}). If no methods support the media type of the request entity body an implementation MUST generate an unsupported media type response (HTTP 415 status).
-\item At least one of the acceptable response entity body media types is a supported output data format (see section \ref{declaring_method_capabilities}). If no methods support one of the acceptable response entity body media types an implementation MUST generate a not acceptable response (HTTP 406 status).
+\item The request method is supported. If no methods support the request method an implementation MUST generate a \WebAppExc\ with a method not allowed response (HTTP 405 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}. Note the additional support for \code{HEAD} and \code{OPTIONS} described in section \ref{head_and_options}.
+\item The media type of the request entity body (if any) is a supported input data format (see section \ref{declaring_method_capabilities}). If no methods support the media type of the request entity body an implementation MUST generate a \WebAppExc\ with an unsupported media type response (HTTP 415 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
+\item At least one of the acceptable response entity body media types is a supported output data format (see section \ref{declaring_method_capabilities}). If no methods support one of the acceptable response entity body media types an implementation MUST generate a \WebAppExc\ with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}.
\end{itemize}
\item Sort $M$ a follows:
\begin{itemize}
@@ -452,7 +452,7 @@
\end{itemize}
\end{itemize}
-\item If $M = \{\}$ then return a not acceptable response (HTTP 406 status), finish.
+\item If $M = \{\}$ then generate a \WebAppExc\ with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}. Finish.
\item For each member of $M, m$:
\begin{itemize}
@@ -461,7 +461,7 @@
\item If $M$ contains \lq*/*\rq\ or \lq application/*\rq, set $M_{\mbox{selected}} = \mbox{\lq application/octet-stream\rq}$, finish.
-\item Return a not acceptable response (HTTP 406 status), finish.
+\item Generate a \WebAppExc\ with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section \ref{method_exc}. Finish.
\end{enumerate}
Note that the above renders a response with a default media type of \lq application/octet-stream\rq\ when a concrete type cannot be determined. It is RECOMMENDED that \MsgWrite\ implementations specify at least one concrete type via \ProduceMime.
\ No newline at end of file
