| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| |
| Copyright (c) 2010, 2024 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.0.x branch: </emphasis> |
| <itemizedlist> |
| <listitem> |
| <para>This user guide refers only to version 3.0.x of Jersey, its compatibility is described below.</para> |
| </listitem> |
| <listitem> |
| <para>Jersey 3.0.x 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.0.x. All modules are also fully compatible with JDK 11 and above - depending on Jersey version. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <table pgwide="1" frame='all' xml:id="jersey-jdk-compatibility"> |
| <title>Jersey 3.0.x JDK compatibility</title> |
| <tgroup cols='3' align='center' colsep='1' rowsep='1'> |
| <colspec colname='c1'/> |
| <colspec colname='c2'/> |
| <colspec colname='c3'/> |
| <thead> |
| <row> |
| <entry>Jersey version</entry> |
| <entry>JDK min version</entry> |
| <entry>JDK max version</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>3.0.0</entry><entry>1.8</entry><entry>16</entry></row> |
| <row><entry>3.0.1</entry><entry>1.8</entry><entry>16</entry></row> |
| <row><entry>3.0.2</entry><entry>1.8</entry><entry>17</entry></row> |
| <row><entry>3.0.3</entry><entry>1.8</entry><entry>18</entry></row> |
| <row><entry>3.0.4</entry><entry>1.8</entry><entry>18</entry></row> |
| <row><entry>3.0.5</entry><entry>1.8</entry><entry>19</entry></row> |
| <row><entry>3.0.6</entry><entry>1.8</entry><entry>19</entry></row> |
| <row><entry>3.0.7</entry><entry>1.8</entry><entry>19</entry></row> |
| <row><entry>3.0.8</entry><entry>1.8</entry><entry>19</entry></row> |
| <row><entry>3.0.9</entry><entry>1.8</entry><entry>20</entry></row> |
| <row><entry>3.0.10</entry><entry>1.8</entry><entry>20</entry></row> |
| <row><entry>3.0.11</entry><entry>1.8</entry><entry>21</entry></row> |
| <row><entry>3.0.12</entry><entry>1.8</entry><entry>22</entry></row> |
| <row><entry>3.0.13</entry><entry>1.8</entry><entry>23</entry></row> |
| <row><entry>3.0.14</entry><entry>1.8</entry><entry>23</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </para> |
| <section> |
| <title>Virtual Threads and Thread Factories</title> |
| <para> |
| With JDK 21 and above, Jersey (since 2.44) has the ability to use virtual threads instead of |
| the <literal>CachedThreadPool</literal> in the internal <literal>ExecutorServices</literal>. |
| Jersey also has the ability to specify the backing <literal>ThreadFactory</literal> for the |
| default <literal>ExecutorServices</literal> (the default <literal>ExecutorServices</literal> |
| can be overridden by the &jersey.common.spi.ExecutorServiceProvider; SPI). |
| </para> |
| <para> |
| To enable virtual threads and/or specify the <literal>ThreadFactory</literal>, use |
| &jersey.common.CommonProperties.USE_VIRTUAL_THREADS; and/or &jersey.common.CommonProperties.THREAD_FACTORY; |
| properties, respectively. See also the <xref linkend="appendix-properties-common"/> in appendix for property details. |
| </para> |
| </section> |
| </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> |
