Jakartified User Guide - first 10 chapters (#4653)

Jakartified User Guide: chapters 1 - 10

Signed-off-by: Maxim Nesen <maxim.nesen@oracle.com>

Author: senivam

docs/pom.xml

@@ -193,7 +193,7 @@
         <javanet.repository.id>snapshots</javanet.repository.id>
         <jersey.docs.version>snapshot</jersey.docs.version>
         <jersey.apidocs.version>snapshot</jersey.apidocs.version>
-        <jersey.src.branch>master</jersey.src.branch>
+        <jersey.src.branch>3.x</jersey.src.branch>
         <jaxrs.version>${jaxrs.api.spec.version}</jaxrs.version>
         <jaxrs.impl.version>${jaxrs.api.impl.version}</jaxrs.impl.version>
     </properties>

docs/src/main/docbook/client.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-    Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved.
+    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
@@ -31,7 +31,7 @@
 
     <para>
         This section introduces the JAX-RS Client API, which is a fluent Java based API for communication with RESTful Web
-        services. This standard API that is also part of Java EE 7 is designed to make it very easy to consume a Web service
+        services. This standard API that is also part of Jakarta EE 9 is designed to make it very easy to consume a Web service
         exposed via HTTP protocol and enables developers to concisely and efficiently implement portable client-side solutions
         that leverage existing and well established client-side HTTP connector implementations.
     </para>
@@ -746,7 +746,7 @@ Client client = ClientBuilder.newClient(clientConfig);</programlisting>
             into the &lit.jersey.client.ClientConfig;. The &lit.jersey.grizzly.GrizzlyConnectorProvider; is used as a custom
             connector provider in the example above. Please note that the connector provider cannot be registered as a provider
             using &lit.jaxrs.core.Configurable;<literal>.register(...)</literal>. Also, please note that in this API has changed
-            in Jersey 2.5, where the &lit.jersey.client.ConnectorProvider; SPI has been introduced in order to decouple client
+            since Jersey 2.5, where the &lit.jersey.client.ConnectorProvider; SPI has been introduced in order to decouple client
             initialization from the connector instantiation. Starting with Jersey 2.5 it is therefore not possible to directly
             register &lit.jersey.client.Connector; instances in the Jersey &jersey.client.ClientConfig;. The new
             &lit.jersey.client.ConnectorProvider; SPI must be used instead to configure a custom client-side transport connector.
@@ -822,33 +822,33 @@ System.out.println("Now the connection is closed.");</programlisting>
         </para>
         <para>
             To solve injection of a custom type into a client provider instance
-            use &jersey.client.ServiceLocatorClientProvider; to
+            use &jersey.client.InjectionManagerClientProvider; to
             extract &hk2.ServiceLocator; which can return the required injection. The following example shows how to utilize
-            &lit.jersey.client.ServiceLocatorClientProvider;:
+            &lit.jersey.client.InjectionManagerClientProvider;:
         </para>
         <example>
-            <title>ServiceLocatorClientProvider example</title>
+            <title>InjectionManagerClientProvider example</title>
             <programlisting language="java" linenumbering="numbered">public static class MyRequestFilter implements ClientRequestFilter {
     // this injection does not work as filter is registered as an instance:
     // @Inject
     // private MyInjectedService service;
 
     @Override
     public void filter(ClientRequestContext requestContext) throws IOException {
-        // use ServiceLocatorClientProvider to extract HK2 ServiceLocator from request
-        final ServiceLocator locator = ServiceLocatorClientProvider.getServiceLocator(requestContext);
+        // use InjectionManagerClientProvider to extract InjectionManager from request
+        final InjectionManager injectionManager = InjectionManagerClientProvider.getInjectionManager(requestContext);
 
         // and ask for MyInjectedService:
-        final MyInjectedService service = locator.getService(MyInjectedService.class);
+        final MyInjectedService service = injectionManager.getInstance(MyInjectedService.class);
 
         final String name = service.getName();
         ...
     }
 }</programlisting>
         </example>
         <para>
-            For more information see javadoc of &jersey.client.ServiceLocatorClientProvider;
-            (and javadoc of &jersey.common.ServiceLocatorProvider; which supports common JAX-RS components).
+            For more information see javadoc of &jersey.client.InjectionManagerClientProvider;
+            (and javadoc of &jersey.common.InjectionManagerProvider; which supports common JAX-RS components).
         </para>
     </section>
 
@@ -897,7 +897,7 @@ Client client = ClientBuilder.newBuilder().sslContext(sslContext).build();</prog
                 A behaviour of &jdk6.HostnameVerifier; is dependent on an http client implementation.
                 &lit.jersey.client.HttpUrlConnectorProvider; and &lit.jersey.apache.ApacheConnectorProvider; work properly, that means that after
                 the unsuccessful URL verification &lit.jdk6.HostnameVerifier; is called and by means of it is possible to
-                revalidate URL using a custom implementation of &lit.jdk6.HostnameVerifier; and go on in a handskahe processing.
+                revalidate URL using a custom implementation of &lit.jdk6.HostnameVerifier; and go on in a handshake processing.
                 &lit.jersey.jetty.JettyConnectorProvider; and &lit.jersey.grizzly.GrizzlyConnectorProvider; provide only host URL verification
                 and throw a &lit.jdk6.CertificateException; without any possibility to use custom &lit.jdk6.HostnameVerifier;.
                 Moreover, in case of &lit.jersey.jetty.JettyConnectorProvider; there is a property
@@ -923,12 +923,11 @@ Client client = ClientBuilder.newBuilder().sslContext(sslContext).build();</prog
             <para>Jersey supports Basic and Digest HTTP Authentication.</para>
             <important>
                 <para>
-                    In version prior to Jersey 2.5 the support was
-                    provided by <literal>org.glassfish.jersey.client.filter.HttpBasicAuthFilter</literal>
-                    and <literal>org.glassfish.jersey.client.filter.HttpDigestAuthFilter</literal>. Since Jersey
-                    2.5 these filters are deprecated (and removed in 2.6) and both authentication methods
-                    are provided by single &lit.jaxrs.core.Feature;
+                    In version of Jersey 3.x both authentication methods are provided by single &lit.jaxrs.core.Feature;
                     &jersey.client.HttpAuthenticationFeature;.
+                    For migration of older applications: <literal>org.glassfish.jersey.client.filter.HttpBasicAuthFilter</literal>
+                    and <literal>org.glassfish.jersey.client.filter.HttpDigestAuthFilter</literal> shall be replaced by
+                    those two authentication methods.
                 </para>
             </important>
 

docs/src/main/docbook/dependencies.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-    Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
+    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
@@ -33,25 +33,18 @@
         <title>Java SE Compatibility</title>
 
         <para>
-            <emphasis>2.x branch: </emphasis>
+            <emphasis>3.x branch: </emphasis>
             <itemizedlist>
                 <listitem>
-                    <para>Until version 2.6, Jersey was compiled with Java SE 6. This has changed in Jersey 2.7.</para>
+                    <para>This user guide refers only to version 3 and above of Jersey, its compatibility is described below</para>
                 </listitem>
                 <listitem>
-                    <para>Up to version 2.25.x almost all Jersey components are compiled with Java SE 7 target.
-                    It means, that you will need at least Java
-                    SE 7 to be able to compile and run your application that is using latest Jersey.
-                    Only <literal>core-common</literal> and <literal>core-client</literal> modules are still compiled with Java class
-                    version runnable with Java SE 6.</para>
-                </listitem>
-                <listitem>
-                    <para>Since Jersey 2.26, all modules are build using Java SE 8 and there is no support for running it
-                    on older Java SE distributions.</para>
-                </listitem>
-                <listitem>
-                    <para>Since Jersey 2.29, all modules can be built using Java SE 11 and all distributed modules provide support
-                        for Java SE 8+ (9,11).</para>
+                    <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>
@@ -62,18 +55,18 @@
         <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="http://search.maven.org/">Central Maven Repository</link>. Jersey is also being deployed to
+            <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 in the application
-            dependencies the set of 3rd party modules that Jersey modules depend on. Jersey is designed as a pluggable component
+            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
-            the set of external Jersey dependencies required to be included in the application dependencies may vary in each
+            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>
 
@@ -129,7 +122,6 @@
 
             <programlisting language="xml">&lt;dependency&gt;
     &lt;groupId&gt;org.glassfish.jersey.containers&lt;/groupId&gt;
-    &lt;!-- if your container implements Servlet API older than 3.0, use "jersey-container-servlet-core"  --&gt;
     &lt;artifactId&gt;jersey-container-servlet&lt;/artifactId&gt;
     &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;
@@ -170,7 +162,7 @@
     &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;
@@ -181,9 +173,10 @@
         <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 2.5 and higher,
-                Jersey provides support for programmatic deployment to the following containers: Grizzly 2 (HTTP and Servlet),
-                JDK Http server, Simple Http server and Jetty Http server. This chapter presents only required maven dependencies,
+                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>