Skip to content

Commit

Permalink
Jakartified User Guide - first 10 chapters (#4653)
Browse files Browse the repository at this point in the history 
Jakartified User Guide: chapters 1 - 10

Signed-off-by: Maxim Nesen <maxim.nesen@oracle.com>
  • Loading branch information
@senivam
senivam committed Jan 7, 2021
1 parent cae04f9 commit bbff3b6
Show file tree
Hide file tree
Showing 11 changed files with 218 additions and 234 deletions.
2 changes: 1 addition & 1 deletion docs/pom.xml
View file
Expand Up @@ -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>
Expand Down
33 changes: 16 additions & 17 deletions docs/src/main/docbook/client.xml
View file
@@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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
Expand All @@ -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>

Expand Down
43 changes: 18 additions & 25 deletions docs/src/main/docbook/dependencies.xml
View file
@@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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>

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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>

Expand Down

0 comments on commit bbff3b6

Please sign in to comment.