spec/chapters/applications.tex - jsr311 - Git at Google

 \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{Validation}

 Specific validation requirements are detailed throughout this specification and the \jaxrs\ Javadocs. Implementations MAY perform additional validation where feasible and SHOULD report any issues arising from such validation to the user.

 \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} Þle. The \code{Application} subclass (see section \ref{config}), resource classes, and providers are packaged in \code{WEB-INF/classes}, required libraries are packaged in \code{WEB-INF/lib}. Included libraries MAY also contain resource classes and providers as desired. See the Servlet speciÞcation for full details on packaging of web applications.

 When using a Servlet 3 container, the \code{Application} subclass is optional. By default, all root resource classes and providers packaged in the web application MUST be included in the published JAX-RS application. An \code{Application} subclass MAY be included in a \code{.war} file to override the default behavior. If both \code{getClasses} and \code{getSingletons} return an empty list then the default set of classes MUST be used. 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 a non-\jaxrs\ aware servlet container, the \code{servlet-class} or \code{filter-class} element of the web.xml descriptor SHOULD name the JAX-RS implementation-supplied \code{Servlet} or \code{Filter} class respectively. The application-supplied subclass of \code{Application} is identiÞed using an \code{init-param} with a \code{param-name} of \code{javax\-.ws\-.rs\-.Application}.

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

	Specific validation requirements are detailed throughout this specification and the \jaxrs\ Javadocs. Implementations MAY perform additional validation where feasible and SHOULD report any issues arising from such validation to the user.

	\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} Þle. The \code{Application} subclass (see section \ref{config}), resource classes, and providers are packaged in \code{WEB-INF/classes}, required libraries are packaged in \code{WEB-INF/lib}. Included libraries MAY also contain resource classes and providers as desired. See the Servlet speciÞcation for full details on packaging of web applications.

	When using a Servlet 3 container, the \code{Application} subclass is optional. By default, all root resource classes and providers packaged in the web application MUST be included in the published JAX-RS application. An \code{Application} subclass MAY be included in a \code{.war} file to override the default behavior. If both \code{getClasses} and \code{getSingletons} return an empty list then the default set of classes MUST be used. 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 a non-\jaxrs\ aware servlet container, the \code{servlet-class} or \code{filter-class} element of the web.xml descriptor SHOULD name the JAX-RS implementation-supplied \code{Servlet} or \code{Filter} class respectively. The application-supplied subclass of \code{Application} is identiÞed using an \code{init-param} with a \code{param-name} of \code{javax\-.ws\-.rs\-.Application}.

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