JAX-RS spec sources moved to it’s own repository.

Signed-off-by: Marek Potociar <[email protected]>

.gitignore

@@ -0,0 +1,22 @@
+# maven noise
+target
+
+# osx noise
+.DS_Store
+profile
+
+#IntelliJ Idea noise
+.idea
+*.iws
+*.ipr
+*.iml
+
+# TeX build noise
+*.aux
+*.bbl
+*.blg
+*.log
+*.out
+*.tex~
+*.thm
+*.toc

Makefile

@@ -0,0 +1,35 @@
+#
+
+SOURCES=spec.tex \
+        styles/jsr.sty \
+        styles/jsrfrontstyle.tex \
+        styles/jsrmainstyle.tex \
+        styles/lineno.sty \
+        styles/macros.tex \
+        styles/ntheorem.sty \
+        chapters/titlepage.tex \
+        chapters/license.tex \
+        chapters/intro.tex \
+        chapters/applications.tex \
+        chapters/resources.tex \
+        chapters/providers.tex \
+        chapters/context.tex \
+        chapters/environment.tex \
+        chapters/delegate.tex \
+        chapters/annotations.tex \
+        chapters/headers.tex \
+        chapters/changes.tex \
+        chapters/refs.tex \
+        references.bib
+
+all: spec.pdf
+
+spec.pdf: ${SOURCES}
+	pdflatex spec.tex
+	bibtex spec.aux
+	pdflatex spec.tex
+	pdflatex spec.tex
+
+clean:
+	rm -f spec.aux spec.bbl spec.blg spec.log spec.out spec.pdf spec.thm spec.toc
+	rm -f chapters/*.aux styles/*.aux

chapters/annotations.tex

@@ -0,0 +1,66 @@
+\chapter{Summary of Annotations}
+\label{annotation_table}
+%\begin{center}
+\begin{longtable}{|l|p{1.2in}|p{3.5in}|}
+\hline
+\bfseries Annotation & \bfseries Target & \bfseries Description \tabularnewline
+\hline\hline\endhead
+\code{Consumes} & \raggedright Type or method & \raggedright Specifies a list of media types that can be consumed. \tabularnewline
+\hline
+\code{Produces} & \raggedright Type or method & \raggedright Specifies a list of media types that can be produced. \tabularnewline
+\hline
+\code{GET} & \raggedright Method & \raggedright Specifies that the annotated method handles HTTP GET requests.  \tabularnewline
+\hline
+\code{POST} & \raggedright Method & \raggedright Specifies that the annotated method handles HTTP POST requests.  \tabularnewline
+\hline
+\code{PUT} & \raggedright Method & \raggedright Specifies that the annotated method handles HTTP PUT requests.  \tabularnewline
+\hline
+\code{DELETE} & \raggedright Method & \raggedright Specifies that the annotated method handles HTTP DELETE requests.  \tabularnewline
+\hline
+\code{HEAD} & \raggedright Method & \raggedright Specifies that the annotated method handles HTTP HEAD requests. Note that HEAD may be automatically handled, see Section \ref{head_and_options}. \tabularnewline
+\hline
+\code{ApplicationPath} & \raggedright Type & \raggedright Specifies the resource-wide application path that forms the base URI of all root resource classes. \tabularnewline
+\hline
+\code{Path} & \raggedright Type or method & \raggedright Specifies a relative path for a resource. When used on a class this annotation identifies that class as a root resource. When used on a method this annotation identifies a sub-resource method or locator. \tabularnewline
+\hline
+\code{PathParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from the request URI path. The value of the annotation identifies the name of a URI template parameter.\tabularnewline
+\hline
+\code{QueryParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI query parameter. The value of the annotation identifies the name of a query parameter. \tabularnewline
+\hline
+\code{FormParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter is to be extracted from a form parameter in a request entity body. The value of the annotation identifies the name of a form parameter. Note that whilst the annotation target allows use on fields and methods, the specification only requires support for use on resource method parameters.\tabularnewline
+\hline
+\code{MatrixParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI matrix parameter. The value of the annotation identifies the name of a matrix parameter. \tabularnewline
+\hline
+\code{CookieParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a HTTP cookie. The value of the annotation identifies the name of a the cookie. \tabularnewline
+\hline
+\code{HeaderParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a HTTP header. The value of the annotation identifies the name of a HTTP header. \tabularnewline
+\hline
+\code{Encoded} & \raggedright Type, constructor, method, field or parameter & \raggedright Disables automatic URI decoding for path, query, form and matrix parameters. \tabularnewline
+\hline
+\code{DefaultValue} & \raggedright Parameter, field or method & \raggedright Specifies a default value for a field, property or method parameter annotated with \QueryParam, \MatrixParam, \CookieParam, \FormParam\ or \HeaderParam. The specified value will be used if the corresponding query or matrix parameter is not present in the request URI, if the corresponding form parameter is not in the request entity body, or if the corresponding HTTP header is not included in the request.\tabularnewline
+\hline
+\code{Context} & \raggedright Field, method or parameter & \raggedright Identifies an injection target for one of the types listed in Section \ref{contexttypes} or the applicable section of Chapter \ref{environment}. \tabularnewline
+\hline
+\code{HttpMethod} & \raggedright Annotation & \raggedright Specifies the HTTP method for a request method designator annotation. \tabularnewline
+\hline
+\code{Provider} & \raggedright Type & \raggedright Specifies that the annotated class implements a \jaxrs\ extension interface. \tabularnewline
+\hline
+\hline
+\multicolumn{3}{|c|}
+{\bfseries Since JAX-RS 2.0} \\
+\hline
+\hline
+\code{NameBinding} & \raggedright Annotation  & \raggedright Meta-annotation to create annotations for binding filters or interceptors to resource methods and applications. Name binding is only supported as part of the Server API.  \tabularnewline
+\hline
+\code{Suspended} & \raggedright Parameter & \raggedright  Indicates that a resource method is asynchronous. I.e., that it does not produce a response upon returning. JAX-RS implementations will suspend the incoming connection until a response becomes available. \tabularnewline
+\hline
+\code{PreMatching} & \raggedright Type & \raggedright Global binding annotation that can be applied to a container filter to indicate that it should be applied globally and before the resource method is matched.\tabularnewline
+\hline
+\code{BeanParam} & \raggedright  Parameter, field or method & \raggedright Can be used to inject a user-defined bean whose fields and properties may be annotated with JAX-RS param annotations.\tabularnewline
+\hline
+\code{ConstrainedTo} & \raggedright Type & \raggedright Can be used to restrict the applicability of a provider to just the Client API or just the Server API. If omitted, a provider can be used in either context. 
+\tabularnewline\hline
+\code{ParamConverter.Lazy} & \raggedright Type & \raggedright Indicates that a conversion of a default value delegated to a \code{ParamConverter} SHOULD occur only when the value is actually requested.
+\tabularnewline\hline
+\end{longtable}
+%\end{center}

chapters/applications.tex

@@ -0,0 +1,110 @@
+\chapter{Applications}
+\label{applications}
+
+A \jaxrs\ application consists of one or more resources (see Chapter \ref{resources}) and zero or more providers (see Chapter \ref{providers}). This chapter describes aspects of \jaxrs\ that apply to an application as a whole, subsequent chapters describe particular aspects of a \jaxrs\ application and requirements on \jaxrs\ implementations.
+
+\section{Configuration}
+\label{config}
+
+The resources and providers that make up a \jaxrs\ application are configured via an application-supplied subclass of \code{Application}. An implementation MAY provide alternate mechanisms for locating resource classes and providers (e.g. runtime class scanning) but use of \code{Application} is the only portable means of configuration.
+
+\section{Verification}
+\label{verification}
+
+Specific application requirements are detailed throughout this specification and the \jaxrs\ Javadocs. Implementations MAY perform verification steps that go beyond what it is stated in this document. 
+
+A \jaxrs\ implementation MAY report an error condition if it detects that two or more resources could result in an ambiguity during the execution of the algorithm described Section \ref{request_matching}. For example, if two resource methods in the same resource class have identical (or even intersecting) values in all the annotations that are relevant to the algorithm described in that section. The exact set of verification steps as well as the error reporting mechanism is implementation dependent.
+
+\section{Publication}
+
+Applications are published in different ways depending on whether the application is run in a Java SE environment or within a container. This section describes the alternate means of publication.
+
+\subsection{Java SE}
+
+In a Java SE environment a configured instance of an endpoint class can be obtained using the \code{create\-Endpoint} method of \rd. The application supplies an instance of \code{Application} and the type of endpoint required. An implementation MAY support zero or more endpoint types of any desired type.
+
+How the resulting endpoint class instance is used to publish the application is outside the scope of this specification.
+
+\subsubsection{JAX-WS}
+
+An implementation that supports publication via JAX-WS MUST support \code{create\-Endpoint} with an endpoint type of \code{javax\-.xml\-.ws\-.Provider}. JAX-WS describes how a \code{Provider} based endpoint can be published in an SE environment.
+
+\subsection{Servlet}
+\label{servlet}
+
+A \jaxrs\ application is packaged as a Web application in a \code{.war} file. The application classes are packaged in \code{WEB-INF/classes} or \code{WEB-INF/lib} and required libraries are packaged in \code{WEB-INF/lib}. See the Servlet specification for full details on packaging of web applications.
+
+It is RECOMMENDED that implementations support the Servlet 3 framework pluggability mechanism to enable portability between containers and to avail themselves of container-supplied class scanning facilities. When using the pluggability mechanism the following conditions MUST be met:
+
+\begin{itemize}
+\item If {\em no} \code{Application} subclass is present, JAX-RS implementations are REQUIRED to dynamically add a servlet and set its name to
+\begin{quote}\code{javax.\-ws.\-rs.\-core.\-Application}\end{quote} and to automatically discover all root resource classes and providers which MUST be packaged with the application. Additionally, the application MUST be packaged with a \code{web.xml} that specifies a servlet mapping for the added servlet. An example of such a \code{web.xml} file is:
+
+\begin{listing}{1}
+<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
+        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
+    <servlet>
+        <servlet-name>javax.ws.rs.core.Application</servlet-name>
+    </servlet>
+    <servlet-mapping>
+        <servlet-name>javax.ws.rs.core.Application</servlet-name>
+        <url-pattern>/myresources/*</url-pattern>
+    </servlet-mapping>
+</web-app>
+\end{listing} 
+
+\item If an \code{Application} subclass is present:
+
+\begin{itemize}
+\item If there is already a servlet that handles this application. That is, a servlet that has an initialization parameter named
+\begin{quote}\code{javax.ws.rs.Application}\end{quote}  whose value is the fully qualified name of the \code{Application} subclass, then no additional configuration steps are required by the JAX-RS implementation.
+
+\item If {\em no} servlet handles this application, JAX-RS implementations are REQUIRED to dynamically add a servlet whose fully qualified name must be that of the \code{Application} subclass. If the \code{Application} subclass is annotated with \ApplicationPath, implementations are REQUIRED to use the value of this annotation appended with "/*" to define a mapping for the added server. Otherwise, the application MUST be packaged with a \code{web.xml} that specifies a servlet mapping. For example, if \code{org.example.MyApplication} is the name of the \code{Application} subclass, a sample \code{web.xml} would be:
+
+\begin{listing}{1}
+<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
+        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
+    <servlet>
+        <servlet-name>org.example.MyApplication</servlet-name>
+    </servlet>
+    <servlet-mapping>
+        <servlet-name>org.example.MyApplication</servlet-name>
+        <url-pattern>/myresources/*</url-pattern>
+    </servlet-mapping>
+</web-app>
+\end{listing} 
+
+\end{itemize}
+
+When an \code{Application} subclass is present in the archive, if both \code{Application.getClasses} and \code{Application.getSingletons} return an empty collection then all root resource classes and providers packaged in the web application MUST be included and the JAX-RS implementation is REQUIRED to discover them automatically by scanning a \code{.war} file as described above. If either \code{getClasses} or \code{getSingletons} returns a non-empty collection then only those classes or singletons returned MUST be included in the published \jaxrs\ application. 
+\end{itemize}
+
+The following table summarizes the Servlet 3 framework pluggability mechanism:
+
+{\small
+\begin{longtable}{|p{1.2in}|l|l|p{1.65in}|}
+\hline
+\bfseries Condition & {\bfseries Action} & {\bfseries Servlet Name} & \bfseries \code{web.xml} 
+\tabularnewline
+\hline\hline\endhead
+No \code{Application} subclass & Add servlet & \code{javax.\-ws.\-rs.\-core.\-Application} & Required for servlet mapping \tabularnewline
+\hline
+\code{Application} subclass handled by existing servlet & (none) & (already defined) & Not required \tabularnewline
+\hline
+\code{Application} subclass {\em not} handled by existing servlet & Add servlet & Subclass name & If no \ApplicationPath\ then required for servlet mapping \tabularnewline
+\hline
+\caption{Summary of Servlet 3 framework pluggability cases}
+\end{longtable}
+}
+
+If not using the Servlet 3 framework pluggability mechanism (e.g.~in a pre-Servlet 3.0 container), the \code{servlet-class} or \code{filter-class} element of the \code{web.xml} descriptor SHOULD name the \jaxrs\ implementation-supplied servlet or filter class respectively. The \code{Application} subclass SHOULD be identified using an \code{init-param} with a \code{param-name} of \code{javax.\-ws.\-rs.\-Application}.
+
+Note that the Servlet 3 framework pluggability mechanism described above is based on servlets and not filters. Applications that prefer to use an  implementation-supplied filter class must use the pre-Servlet 3.0 configuration mechanism.
+
+\subsection{Other Container}
+
+An implementation MAY provide facilities to host a \jaxrs\ application in other types of container, such facilities are outside the scope of this specification.