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}

 A \jaxrs\ application is packaged as a Servlet in a \code{.war} file. 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 specification for full details on packaging of web applications.

 When using a \jaxrs\ aware servlet container, the \code{servlet-class} element of the \code{web.xml} descriptor SHOULD name the application-supplied subclass of \code{Application}.

 When using a non-\jaxrs\ aware servlet container, the \code{servlet-class} element of the \code{web.xml} descriptor SHOULD name the \jaxrs\ implementation-supplied Servlet class. The application-supplied subclass of \code{Application} is identified 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}

	A \jaxrs\ application is packaged as a Servlet in a \code{.war} file. 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 specification for full details on packaging of web applications.

	When using a \jaxrs\ aware servlet container, the \code{servlet-class} element of the \code{web.xml} descriptor SHOULD name the application-supplied subclass of \code{Application}.

	When using a non-\jaxrs\ aware servlet container, the \code{servlet-class} element of the \code{web.xml} descriptor SHOULD name the \jaxrs\ implementation-supplied Servlet class. The application-supplied subclass of \code{Application} is identified 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.