Thanks for the patch. I've committed everything apart from the spaces
preceding each \cite - I think I read somewhere that there shouldn't
be a space but I could be wrong and want to look into that first.
Marc.
On Feb 26, 2008, at 8:13 AM, Stephan Koops wrote:
> 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}}
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: users-help_at_jsr311.dev.java.net
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.