Hello Paul,
after consulting you, here's a subversion patch (see attachment) for
some little inconsistencies in the spec compared to the API:
* changed macro from @SecurityContext to SecurityContext
* request.evaluate(..) was renamed to
request.evaluatePredondictions(..) and is returning a
ResponseBuilder instead of a Response. I added a sentence why. I
think it is useful to also put it to the javadoc of
Request.evalueatPreconditions(..)
* In the code example in the chapter resources the public modifier
was missing.
* As cosmetic change I put a space in front of every \cite command.
I also switched the abbrecation REST in front of the \cite command
in the second line of the introduction.
I've also added some latex parameters, so that the table of content is
available as PDF bookmarks. The links in the table of content are
clickable now.
best regards
Stephan
P.S: Paul, please change my texts if necessary, because my english is
not very well.
Property changes on: .
___________________________________________________________________
Name: svn:ignore
- *.thm
*.aux
*.bbl
*.blg
*.out
*.pdf
outlines
*.log
*.ps
*.dvi
*.cb
*.toc
+ *.thm
*.aux
*.bbl
*.blg
*.out
*.pdf
outlines
*.log
*.ps
*.dvi
*.cb
*.toc
.project
spec.cb2
spec.tcp
spec.tps
Index: spec.tex
===================================================================
--- spec.tex (revision 210)
+++ spec.tex (working copy)
@@ -12,6 +12,11 @@
pdfsubject={JAX-RS: Java API for RESTful Web Services},
pdfkeywords={Java XML Web Services API REST RESTful},
letterpaper=true,
+ pdftex, % show table of contents as bookmarks and links clickable.
+ colorlinks=true, % no red box around the links, but red links
+ linkcolor=black, % color of the links black, as before
+ citecolor=black, % color of cites also black, also as before
+ pdfstartview=FitH, % opened document with full page width
bookmarksnumbered=true
]{hyperref}
@@ -62,6 +67,7 @@
%\cleardoublepage
%\include{chapters/status}
+\pdfbookmark[0]{Contents}{toc} % adds toc to pdf bookmarks
\tableofcontents
\mainmatter
Index: chapters/context.tex
===================================================================
--- chapters/context.tex (revision 210)
+++ chapters/context.tex (working copy)
@@ -41,20 +41,22 @@
\section{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 \Response\ 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:
+\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();
- Response response = request.evaluate(tag, null);
- if (response != null)
- return response;
- else
- return doUpdate(foo);
+ EntityTag tag = getCurrentTag();
+ ResponseBuilder responseBuilder = request.evaluatePrecondition(tag, null);
+ if (responseBuilder != null)
+ return responseBuilder.build();
+ else
+ return doUpdate(foo);
}
\end{listing}
+The application could also set the Content-Location, the expiring date and Cache-Control into the Response before build the response.
+
\section{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.
Index: chapters/intro.tex
===================================================================
--- chapters/intro.tex (revision 210)
+++ chapters/intro.tex (working copy)
@@ -1,12 +1,12 @@
\chapter{Introduction}
-This specification defines a set of Java APIs for the development of Web services built according to the Representational State Transfer\cite{rest} (REST) architectural style. Readers are assumed to be familiar with
+This specification defines a set of Java APIs for the development of Web services built according to the Representational State Transfer (REST) \cite{rest} architectural style. Readers are assumed to be familiar with
REST; for more information about the REST architectural style and RESTful Web services, see:
\begin{itemize}
-\item Architectural Styles and the Design of Network-based Software Architectures\cite{rest}
-\item The REST Wiki\cite{restwiki}
-\item Representational State Transfer on Wikipedia\cite{restwikipedia}
+\item Architectural Styles and the Design of Network-based Software Architectures \cite{rest}
+\item The REST Wiki \cite{restwiki}
+\item Representational State Transfer on Wikipedia \cite{restwikipedia}
\end{itemize}
\section{Status}
@@ -43,11 +43,11 @@
\item[POJO-based] The API will provide a set of annotations and associated classes/interfaces that may be used with POJOs in order to expose them as Web resources. The specification will define object lifecycle and scope.
-\item[HTTP-centric] The specification will assume HTTP\cite{http11} is the underlying network protocol and will provide a clear mapping between HTTP and URI\cite{uri} elements and the corresponding API classes and annotations. The API will provide high level support for common HTTP usage patterns and will be sufficiently flexible to support a variety of HTTP applications including WebDAV\cite{webdav} and the Atom Publishing Protocol\cite{atompub}.
+\item[HTTP-centric] The specification will assume HTTP \cite{http11} is the underlying network protocol and will provide a clear mapping between HTTP and URI \cite{uri} elements and the corresponding API classes and annotations. The API will provide high level support for common HTTP usage patterns and will be sufficiently flexible to support a variety of HTTP applications including WebDAV \cite{webdav} and the Atom Publishing Protocol \cite{atompub}.
\item[Format independence] The API will be applicable to a wide variety of HTTP entity body content types. It will provide the necessary pluggability to allow additional types to be added by an application in a standard manner.
-\item[Container independence] Artifacts using the API will be deployable in a variety of Web-tier containers. The specification will define how artifacts are deployed in a Servlet\cite{servlet} container and as a JAX-WS\cite{jsr224} Provider.
+\item[Container independence] Artifacts using the API will be deployable in a variety of Web-tier containers. The specification will define how artifacts are deployed in a Servlet \cite{servlet} container and as a JAX-WS \cite{jsr224} Provider.
\item[Inclusion in Java EE] The specification will define the environment for a Web resource class hosted in a Java EE container and will specify how to use Java EE features and components within a Web resource class.
@@ -73,7 +73,7 @@
\section{Conventions}
-The keywords `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', `RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in RFC 2119\cite{rfc2119}.
+The keywords `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', `RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in RFC 2119 \cite{rfc2119}.
Java code and sample data fragments are formatted as shown in figure \ref{ex1}:
Index: chapters/resources.tex
===================================================================
--- chapters/resources.tex (revision 210)
+++ chapters/resources.tex (working copy)
@@ -90,7 +90,7 @@
\begin{ednote}Add reference to URI Templates ID when available.\end{ednote}
-A URI path template is a string with zero or more embedded parameters that, when values are substituted for all the parameters, is a valid URI\cite{uri} path. A template parameter is represented as \lq\{\rq{\em name}\lq\}\rq\ where {\em name} is the name of the parameter. E.g.:
+A URI path template is a string with zero or more embedded parameters that, when values are substituted for all the parameters, is a valid URI \cite{uri} path. A template parameter is represented as \lq\{\rq{\em name}\lq\}\rq\ where {\em name} is the name of the parameter. E.g.:
\begin{listing}{1}
@Path("widgets/{id}")
@@ -100,7 +100,7 @@
In the above example the \code{Widget} resource class is identified by the relative URI path \code{widgets/{\em xxx}} where \code{\em xxx} is the value of the \code{id} parameter.
-\begin{nnnote}Because \lq\{\rq and \lq\}\rq\ are not part of either the reserved or unreserved productions of URI\cite{uri} they will not appear in a valid URI.\end{nnnote}
+\begin{nnnote}Because \lq\{\rq and \lq\}\rq\ are not part of either the reserved or unreserved productions of URI \cite{uri} they will not appear in a valid URI.\end{nnnote}
The \code{encode} property of \Path\ controls whether the value of the annotation is automatically encoded (the default) or not. E.g. the following two lines are equivalent:
@@ -138,10 +138,10 @@
public class WidgetsResource {
@GET
@Path("offers")
- WidgetList getDiscounted() {...}
+ public WidgetList getDiscounted() {...}
@Path("{id}")
- WidgetResource findWidget(@UriParam("id") String id) {
+ public WidgetResource findWidget(@UriParam("id") String id) {
return lookupWidget(id);
}
}\end{listing}
Index: spec.tex
===================================================================
--- spec.tex (revision 210)
+++ spec.tex (working copy)
@@ -12,6 +12,11 @@
pdfsubject={JAX-RS: Java API for RESTful Web Services},
pdfkeywords={Java XML Web Services API REST RESTful},
letterpaper=true,
+ pdftex, % show table of contents as bookmarks and links clickable.
+ colorlinks=true, % no red box around the links, but red links
+ linkcolor=black, % color of the links black, as before
+ citecolor=black, % color of cites also black, also as before
+ pdfstartview=FitH, % opened document with full page width
bookmarksnumbered=true
]{hyperref}
@@ -62,6 +67,7 @@
%\cleardoublepage
%\include{chapters/status}
+\pdfbookmark[0]{Contents}{toc} % adds toc to pdf bookmarks
\tableofcontents
\mainmatter
Index: styles/macros.tex
===================================================================
--- styles/macros.tex (revision 210)
+++ styles/macros.tex (working copy)
@@ -7,7 +7,7 @@
\newcommand{\Encoded}{\code{_at_Encoded}}
\newcommand{\HeaderParam}{\code{_at_Header\-Param}}
\newcommand{\Context}{\code{_at_Context}}
-\newcommand{\SecurityContext}{\code{_at_Security\-Context}}
+\newcommand{\SecurityContext}{\code{Security\-Context}}
\newcommand{\HttpHeaders}{\code{Http\-Headers}}
\newcommand{\HttpMethod}{\code{_at_Http\-Method}}
\newcommand{\MatrixParam}{\code{_at_Matrix\-Param}}
@@ -21,6 +21,7 @@
\newcommand{\CookieParam}{\code{_at_Cookie\-Param}}
\newcommand{\Request}{\code{Request}}
\newcommand{\Response}{\code{Response}}
+\newcommand{\ResponseBuilder}{\code{ResponseBuilder}}
\newcommand{\rd}{\code{Runtime\-Delegate}}
\newcommand{\UriInfo}{\code{Uri\-Info}}
\newcommand{\WebAppExc}{\code{WebApplicationException}}