docs/src/main/docbook/dependencies.xml - third_party/eclipse-ee4j/jersey - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--

     Copyright (c) 2010, 2021 Oracle and/or its affiliates. All rights reserved.

     This program and the accompanying materials are made available under the
     terms of the Eclipse Public License v. 2.0, which is available at
     http://www.eclipse.org/legal/epl-2.0.

     This Source Code may also be made available under the following Secondary
     Licenses when the conditions for such availability set forth in the
     Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
     version 2 with the GNU Classpath Exception, which is available at
     https://www.gnu.org/software/classpath/license.html.

     SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

 -->

 <!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent"> %ents;]>
 <chapter xmlns="http://docbook.org/ns/docbook"
          version="5.0"
          xml:lang="en"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
                              http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
          xml:id="modules-and-dependencies">
     <title>Modules and dependencies</title>

     <section>
         <title>Java SE Compatibility</title>

         <para>
             <emphasis>3.x branch: </emphasis>
             <itemizedlist>
                 <listitem>
                     <para>This user guide refers only to version 3 and above of Jersey, its compatibility is described below</para>
                 </listitem>
                 <listitem>
                     <para>Since version 3.0.0* all Jersey components are compiled with Java SE 1.8 target.
                     It means, that you will need at least Java SE 1.8 to be able to compile and run your application
                         which uses the latest Jersey 3.x.
                     All modules however are fully compatible with JDK 11 and above. So, it's possible to use JDK 11+ to
                         build your app.
                     </para>
                 </listitem>
             </itemizedlist>
         </para>
     </section>
     <section>
         <title>Introduction to Jersey dependencies</title>

         <para>
             Jersey is built, assembled and installed using <link xlink:href="http://maven.apache.org/">Apache Maven</link>.
             Non-snapshot Jersey releases are deployed to the
             <link xlink:href="https://search.maven.org/">Central Maven Repository</link>. Jersey is also being deployed to
             <link xlink:href="https://oss.sonatype.org/">Sonatype Maven repositories</link>, which contain also Jersey SNAPSHOT
             versions. In case you would want to test the latest development builds check out the
             <link xlink:href="https://oss.sonatype.org/content/repositories/snapshots/org/glassfish/jersey">
                 Sonatype Snapshots Maven repository</link>.
         </para>

         <para>
             An application that uses Jersey and depends on Jersey modules is in turn required to also include a set
             of 3rd party modules that Jersey modules depend on. Jersey is designed as a pluggable component
             architecture and different applications can therefore require different sets of Jersey modules. This also means that
             a set of external Jersey dependencies required to be included in the application dependencies may vary in each
             application based on the Jersey modules that are being used by the application.
         </para>

         <para>
             Developers using Maven or a Maven-aware build system in their projects are likely to find it easier to include and
             manage dependencies of their applications compared to developers using ant or other build systems that are not
             compatible with Maven. This document will explain to both maven and non-maven developers how to depend on
             Jersey modules in their application. Ant developers are likely to find the
             <link xlink:href="http://maven.apache.org/ant-tasks/index.html">Ant Tasks for Maven</link> very useful.
         </para>
     </section>

     <section xml:id="dependencies">
         <title>Common Jersey Use Cases</title>

         <section xml:id="servlet-app-glassfish">
             <title>Servlet based application on Glassfish</title>
             <para>If you are using Glassfish application server, you don't need to package
                 anything with your application, everything is already included. You just need to declare
                 (provided) dependency on JAX-RS API to be able to compile your application.
             </para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId>jakarta.ws.rs&lt;/groupId&gt;
     &lt;artifactId>jakarta.ws.rs-api&lt;/artifactId&gt;
     &lt;version&gt;&jax-rs-api-jar.version;&lt;/version&gt;
     &lt;scope&gt;provided&lt;/scope&gt;
 &lt;/dependency&gt;</programlisting>

             <para>If you are using any Jersey specific feature, you will need to depend on Jersey directly.</para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-servlet&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
     &lt;scope&gt;provided&lt;/scope&gt;
 &lt;/dependency&gt;
 &lt;!-- if you are using Jersey client specific features without the server side --&gt;
 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.core&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-client&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
     &lt;scope&gt;provided&lt;/scope&gt;
 &lt;/dependency&gt;
             </programlisting>
         </section>

         <section xml:id="servlet-app-general">
             <title>Servlet based server-side application</title>
             <para>Following dependencies apply to application server (servlet containers) without any
                 integrated JAX-RS implementation. Then application needs to include JAX-RS API and Jersey
                 implementation in deployed application.</para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-servlet&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;
 &lt;!-- Required only when you are using JAX-RS Client --&gt;
 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.core&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-client&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;</programlisting>
         </section>

         <section xml:id="client-jdk">
             <title>Client application on JDK</title>
             <para>Applications running on plain JDK using only client part of JAX-RS specification need
                 to depend only on client. There are various additional modules which can be added, like
                 for example grizzly or apache or jetty connector (see dependencies snipped below). Jersey client
                 runs by default with plain JDK (using HttpUrlConnection). See <xref linkend="client"/>.
                 for more details.
             </para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.core&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-client&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;
             </programlisting>

             <para>Currently available connectors:</para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.connectors&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-grizzly-connector&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.connectors&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-apache-connector&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;
 <!-- Requires JDK 11+ -->
 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.connectors&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-jetty-connector&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;</programlisting>
         </section>

         <section xml:id="server-jdk">
             <title>Server-side application on supported containers</title>
             <para>Apart for a standard JAX-RS Servlet-based deployment that works with any Servlet container that
                 supports Servlet 5 and higher,
                 Jersey provides support for programmatic deployment to the following containers: Grizzly 3 (HTTP and Servlet),
                 JDK Http server, Simple Http server and Jetty Http server (requires JDK 11+). This chapter presents only
                 required maven dependencies,
                 more information can be found in <xref linkend="deployment"/>.
             </para>

             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-grizzly2-http&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-grizzly2-servlet&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-jdk-http&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-simple-http&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-jetty-http&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;

 &lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
     &lt;artifactId&gt;jersey-container-jetty-servlet&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;</programlisting>
         </section>
     </section>

     <xi:include href="modules.xml" />
 </chapter>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--

	Copyright (c) 2010, 2021 Oracle and/or its affiliates. All rights reserved.

	This program and the accompanying materials are made available under the
	terms of the Eclipse Public License v. 2.0, which is available at
	http://www.eclipse.org/legal/epl-2.0.

	This Source Code may also be made available under the following Secondary
	Licenses when the conditions for such availability set forth in the
	Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
	version 2 with the GNU Classpath Exception, which is available at
	https://www.gnu.org/software/classpath/license.html.

	SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

	-->

	<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent"> %ents;]>
	<chapter xmlns="http://docbook.org/ns/docbook"
	version="5.0"
	xml:lang="en"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
	http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
	xml:id="modules-and-dependencies">
	<title>Modules and dependencies</title>

	<section>
	<title>Java SE Compatibility</title>

	<para>
	<emphasis>3.x branch: </emphasis>
	<itemizedlist>
	<listitem>
	<para>This user guide refers only to version 3 and above of Jersey, its compatibility is described below</para>
	</listitem>
	<listitem>
	<para>Since version 3.0.0* all Jersey components are compiled with Java SE 1.8 target.
	It means, that you will need at least Java SE 1.8 to be able to compile and run your application
	which uses the latest Jersey 3.x.
	All modules however are fully compatible with JDK 11 and above. So, it's possible to use JDK 11+ to
	build your app.
	</para>
	</listitem>
	</itemizedlist>
	</para>
	</section>
	<section>
	<title>Introduction to Jersey dependencies</title>

	<para>
	Jersey is built, assembled and installed using <link xlink:href="http://maven.apache.org/">Apache Maven</link>.
	Non-snapshot Jersey releases are deployed to the
	<link xlink:href="https://search.maven.org/">Central Maven Repository</link>. Jersey is also being deployed to
	<link xlink:href="https://oss.sonatype.org/">Sonatype Maven repositories</link>, which contain also Jersey SNAPSHOT
	versions. In case you would want to test the latest development builds check out the
	<link xlink:href="https://oss.sonatype.org/content/repositories/snapshots/org/glassfish/jersey">
	Sonatype Snapshots Maven repository</link>.
	</para>

	<para>
	An application that uses Jersey and depends on Jersey modules is in turn required to also include a set
	of 3rd party modules that Jersey modules depend on. Jersey is designed as a pluggable component
	architecture and different applications can therefore require different sets of Jersey modules. This also means that
	a set of external Jersey dependencies required to be included in the application dependencies may vary in each
	application based on the Jersey modules that are being used by the application.
	</para>

	<para>
	Developers using Maven or a Maven-aware build system in their projects are likely to find it easier to include and
	manage dependencies of their applications compared to developers using ant or other build systems that are not
	compatible with Maven. This document will explain to both maven and non-maven developers how to depend on
	Jersey modules in their application. Ant developers are likely to find the
	<link xlink:href="http://maven.apache.org/ant-tasks/index.html">Ant Tasks for Maven</link> very useful.
	</para>
	</section>

	<section xml:id="dependencies">
	<title>Common Jersey Use Cases</title>

	<section xml:id="servlet-app-glassfish">
	<title>Servlet based application on Glassfish</title>
	<para>If you are using Glassfish application server, you don't need to package
	anything with your application, everything is already included. You just need to declare
	(provided) dependency on JAX-RS API to be able to compile your application.
	</para>

	<programlisting language="xml"><dependency>
	<groupId>jakarta.ws.rs</groupId>
	<artifactId>jakarta.ws.rs-api</artifactId>
	<version>&jax-rs-api-jar.version;</version>
	<scope>provided</scope>
	</dependency></programlisting>

	<para>If you are using any Jersey specific feature, you will need to depend on Jersey directly.</para>

	<programlisting language="xml"><dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-servlet</artifactId>
	<version>&version;</version>
	<scope>provided</scope>
	</dependency>
	<!-- if you are using Jersey client specific features without the server side -->
	<dependency>
	<groupId>org.glassfish.jersey.core</groupId>
	<artifactId>jersey-client</artifactId>
	<version>&version;</version>
	<scope>provided</scope>
	</dependency>
	</programlisting>
	</section>

	<section xml:id="servlet-app-general">
	<title>Servlet based server-side application</title>
	<para>Following dependencies apply to application server (servlet containers) without any
	integrated JAX-RS implementation. Then application needs to include JAX-RS API and Jersey
	implementation in deployed application.</para>

	<programlisting language="xml"><dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-servlet</artifactId>
	<version>&version;</version>
	</dependency>
	<!-- Required only when you are using JAX-RS Client -->
	<dependency>
	<groupId>org.glassfish.jersey.core</groupId>
	<artifactId>jersey-client</artifactId>
	<version>&version;</version>
	</dependency></programlisting>
	</section>

	<section xml:id="client-jdk">
	<title>Client application on JDK</title>
	<para>Applications running on plain JDK using only client part of JAX-RS specification need
	to depend only on client. There are various additional modules which can be added, like
	for example grizzly or apache or jetty connector (see dependencies snipped below). Jersey client
	runs by default with plain JDK (using HttpUrlConnection). See <xref linkend="client"/>.
	for more details.
	</para>

	<programlisting language="xml"><dependency>
	<groupId>org.glassfish.jersey.core</groupId>
	<artifactId>jersey-client</artifactId>
	<version>&version;</version>
	</dependency>
	</programlisting>

	<para>Currently available connectors:</para>

	<programlisting language="xml"><dependency>
	<groupId>org.glassfish.jersey.connectors</groupId>
	<artifactId>jersey-grizzly-connector</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.connectors</groupId>
	<artifactId>jersey-apache-connector</artifactId>
	<version>&version;</version>
	</dependency>
	<!-- Requires JDK 11+ -->
	<dependency>
	<groupId>org.glassfish.jersey.connectors</groupId>
	<artifactId>jersey-jetty-connector</artifactId>
	<version>&version;</version>
	</dependency></programlisting>
	</section>

	<section xml:id="server-jdk">
	<title>Server-side application on supported containers</title>
	<para>Apart for a standard JAX-RS Servlet-based deployment that works with any Servlet container that
	supports Servlet 5 and higher,
	Jersey provides support for programmatic deployment to the following containers: Grizzly 3 (HTTP and Servlet),
	JDK Http server, Simple Http server and Jetty Http server (requires JDK 11+). This chapter presents only
	required maven dependencies,
	more information can be found in <xref linkend="deployment"/>.
	</para>

	<programlisting language="xml"><dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-grizzly2-http</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-grizzly2-servlet</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-jdk-http</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-simple-http</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-jetty-http</artifactId>
	<version>&version;</version>
	</dependency>

	<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-jetty-servlet</artifactId>
	<version>&version;</version>
	</dependency></programlisting>
	</section>
	</section>

	<xi:include href="modules.xml" />
	</chapter>