intro.tex

\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 
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}
\end{itemize}

\section{Status}
\label{status}

%This is an early draft; this specification is not yet complete. A list of open issues can %be found at:
%This is a JCP public review draft; this specification is not yet final. A list of open issues can be found at:
%This is a JCP final specification. A list of open issues can be found at:

This is the final release of version 2.1. The issue tracking system for this release can be found at:

\begin{quote}
https://github.com/jax-rs/api/issues
\end{quote}

The corresponding Javadocs can be found online at:

\begin{quote}
https://jax-rs.github.io/apidocs/2.1
\end{quote}

The reference implementation can be obtained from:

\begin{quote}
https://jersey.github.io
\end{quote}

The expert group seeks feedback from the community on any aspect of this specification, please send comments to:

\begin{quote}
jaxrs-spec@javaee.groups.io
\end{quote}

\section{Goals}

The following are the goals of the API:

\begin{description}

\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[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[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.

\end{description}

\section{Non-Goals}
\label{non_goals}

The following are non-goals:

\begin{description}

\item[Support for Java versions prior to Java SE 8] The API will make extensive use of annotations and lambda expressions that require Java SE 8 or later.

\item[Description, registration and discovery] The specification will neither define nor require any service description, registration or discovery capability.

\item[HTTP Stack] The specification will not define a new HTTP stack. HTTP protocol support is provided by a container that hosts artifacts developed using the API.

\item[Data model/format classes] The API will not define classes that support manipulation of entity body content, rather it will provide pluggability to allow such classes to be used by artifacts developed using the API.

\end{description}

\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}. 

Java code and sample data fragments are formatted as shown in figure \ref{ex1}:

\begin{figure}[hbtp]
\caption{Example Java Code}
\label{ex1}
\begin{listing}{1}
package com.example.hello;

public class Hello {
    public static void main(String args[]) {
        System.out.println("Hello World");
    }
}\end{listing}
\end{figure}

URIs of the general form `http://example.org/...' and `http://example.com/...' represent application or context-dependent URIs.

All parts of this specification are normative, with the exception of examples, notes and sections explicitly marked as `Non-Normative'. Non-normative notes are formatted as shown below.

\begin{nnnote*}
This is a note.
\end{nnnote*}

\section{Terminology}
\label{terminology}

\begin{description}
\item[Resource class] A Java class that uses \jaxrs\ annotations to implement a corresponding Web resource, see Chapter \ref{resources}.
\item[Root resource class] A {\em resource class} annotated with \Path. Root resource classes provide the roots of the resource class tree and provide access to sub-resources, see Chapter \ref{resources}.
\item[Request method designator] A runtime annotation annotated with \HttpMethod. Used to identify the HTTP request method to be handled by a {\em resource method}.
\item[Resource method] A method of a {\em resource class} annotated with a {\em request method designator} that is used to handle requests on the corresponding resource, see Section \ref{resource_method}.
\item[Sub-resource locator] A method of a {\em resource class} that is used to locate sub-resources of the corresponding resource, see Section \ref{sub_resources}.
\item[Sub-resource method] A method of a {\em resource class} that is used to handle requests on a sub-resource of the corresponding resource, see Section \ref{sub_resources}.
\item[Provider] An implementation of a \jaxrs\ extension interface. Providers extend the capabilities of a \jaxrs\ runtime and are described in Chapter \ref{providers}.
\item[Filter] A provider used for filtering requests and responses.
\item[Entity Interceptor] A provider used for intercepting calls to message body readers and writers.
\item[Invocation] A Client API object that can be configured to issue an HTTP request.
\item[WebTarget] The recipient of an Invocation, identified by a URI.
\item[Link] A URI with additional meta-data such as a media type, a relation, a title, etc.

\end{description}

\section{Expert Group Members} 
\label{expert_group}

This specification is being developed as part of JSR 370 under the Java Community Process. It is the result of the collaborative work of the members of the JSR 370 Expert Group. The following are the present expert group members:

\begin{list}{$-$}{\parsep 0em \labelwidth 0em}
\item Sergey Beryozkin (Talend SA) 
\item Adam Bien (Individual Member) 
\item Sebastian Dashner (Individual Member)
\item Markus Karg (Individual Member)
\item Casey Lee (Vision Service Plan)
\item Marcos Luna (Individual Member)
\item Andy McCright (IBM)
\item Julian Reschke (Individual Member)
\item Alessio Soldano (Red Hat) 
\end{list}

The following are former group members of the JSR 339 Expert Group:

\begin{list}{$-$}{\parsep 0em \labelwidth 0em}
\item Jan Algermussen (Individual Member)
\item Florent Beniot (OW2)
\item Sergey Beryozkin (Talend SA) 
\item Adam Bien (Individual Member)
\item Bill Burke (Red Hat)
\item Clinton L. Combs (Individual Member)
\item Jian Wu Dai (IBM)
\item Bill De Hora (Individual Member)
\item Markus Karg (Individual Member)
\item Sastry Malladi (eBay, Inc)
\item Julian Reschke (Individual Member)
\item Guilherme de Azevedo Silveira (Individual Member)
\item Synodinos, Dionysios G. (Individual Member)
\end{list}

JAX-RS 1.X has been developed as part of JSR 311 under the Java Community Process. The following were group members of the JSR 311 Expert Group:

\begin{list}{$-$}{\parsep 0em \labelwidth 0em}
\item Heiko Braun (Red Hat Middleware LLC) 
\item Larry Cable (BEA Systems)
\item Roy Fielding (Day Software, Inc.)
\item Harpreet Geekee (Nortel)
\item Nickolas Grabovas (Individual Member)
\item Mark Hansen (Individual Member)
\item John Harby (Individual Member)
\item Hao He (Individual Member)
\item Ryan Heaton (Individual Member)
\item David Hensley (Individual Member) 
\item Stephan Koops (Individual Member)
\item Changshin Lee (NCsoft Corporation) 
\item Francois Leygues (Alcatel-Lucent) 
\item Jerome Louvel (Individual Member) 
\item Hamid Ben Malek (Fujitsu Limited) 
\item Ryan J. McDonough (Individual Member) 
\item Felix Meschberger (Day Software, Inc.) 
\item David Orchard (BEA Systems) 
\item Dhanji R. Prasanna (Individual Member) 
\item Julian Reschke (Individual Member) 
\item Jan Schulz-Hofen (Individual Member) 
\item Joel Smith (IBM) 
\item Stefan Tilkov (innoQ Deutschland GmbH)
\end{list}

\section{Acknowledgements}
\label{acks}

During the course of this JSR we received great contributions and suggestions from many individuals. Special thanks to Marek Potociar and Michal Gajdos. Also Gunnar Morling, Ondrej Mihalyi, Arjan Tijms, Guillermo Gonzales de Aguero, Christian Kaltepoth and many, many others. Last but not least to the JSR 370 Expert Group for all their contributions.

During the course of JSR 339 we received many excellent suggestions. Special thanks to Martin Matula, Gerard Davison, Jakub Podlesak and Pavel Bucek from Oracle as well as Pete Muir and Emmanuel Bernard from Red Hat. Also to Gunnar Morling and Ron Sigal (Red Hat) for their suggestions on how to improve resource validation, and to Mattias Arthursson for his insights on hypermedia.

During the course of JSR 311 we received many excellent suggestions on the JSR and Jersey (RI) mailing lists, thanks in particular to James Manger (Telstra) and Reto Gm\"{u}r (FactsMission) for their contributions. The following individuals (all Sun Microsystems at the time) have also made invaluable technical contributions: Roberto Chinnici, Dianne Jiao (TCK), Ron Monzillo, Rajiv Mordani, Eduardo Pelegri-Llopart, Jakub Podlesak (RI) and Bill Shannon. 

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.