mp.jaxrs.helidon-connector.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of helidon-docs
There is a newer version: 4.1.4
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2023, 2024 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Helidon Connector
:feature-name: Helidon Connector
:description: Helidon Connector for Jakarta REST Client
:keywords: helidon, rest, jax-rs, client, microprofile, micro-profile, connector
:rootdir: {docdir}/../..

include::{rootdir}/includes/mp.adoc[]

== Contents

- <>
- <>
- <>
- <>
- <>
- <>
- <>

== Overview

Helidon uses Jersey as the Jakarta REST (JAX-RS) implementation. Jersey supports the concept of _connectors_
which is an SPI to handle low-level HTTP connections when using the Jakarta REST Client API. Helidon provides a
connector that is based on its `WebClient` implementation and that has a few benefits,
most notably, configuration using Config and support for HTTP/2.

include::{rootdir}/includes/dependencies.adoc[]

[source,xml]
----
 
     io.helidon.jersey
     helidon-jersey-connector
 
----

== API

Enabling the Helidon connector is possible at creation time using Jersey's `ClientConfig` instance
as shown below:

[source,java]
----
include::{sourcedir}/mp/jaxrs/HelidonConnectorSnippets.java[tag=snippet_1, indent=0]
----

Any subsequent requests using a `Client` instance configured this way will defer to the
Helidon connector to handle the underlying HTTP connection.

== Configuration

The Helidon connector implementation is based on `WebClient`, so it can be configured
using config in the same way as any other instance of that class.
The config root used by the Helidon connector to initialize all instances of `WebClient` is
rooted at `jersey.connector.helidon.config`. Thus, if using a properties file,
use this prefix for all the properties that you want to set in the connector.

For example, suppose you need to enable automatic storage for server cookies and to
turn off redirects, you can add the following lines to your `microprofile-config.properties` file:

[source, properties]
----
jersey.connector.helidon.config.cookie-manager.automatic-store-enabled=true
jersey.connector.helidon.config.follow-redirects=false
----

Alternatively, assuming the root of the `WebClient` configuration is located at
`my.webclient`, this can be done programmatically when building the `ClientConfig`
instance as follows:

[source,java]
----
include::{sourcedir}/mp/jaxrs/HelidonConnectorSnippets.java[tag=snippet_2, indent=0]
----

There are additional properties that can be set programmatically and that shall
override any related property set via config. The following table lists all the
properties supported by the connector, their types, scopes and default values.

|===
|Property Name |Type |Scope |Default

|jersey.config.client.connectTimeout
|`Integer`
|client
|10000 (millis)

|jersey.config.client.readTimeout
|`Integer`
|client, invocation
|10000 (millis)

|jersey.config.client.followRedirects
|`Boolean`
|client, invocation
|true

|jersey.connector.helidon.config
|`io.helidon.config.Config`
|client
|(none)

|jersey.connector.helidon.tls
|`io.helidon.common.tls.Tls`
|client
|(none)

|jersey.connector.helidon.protocolConfigs
|`List`
|client
|(none)

|jersey.connector.helidon.defaultHeaders
|`Map`
|client
|(none)

|jersey.connector.helidon.protocolId
|`String`
|invocation
|(none)

|jersey.connector.helidon.shareConnectionCache
|`Boolean`
|client
|false
|===


=== HTTP/2 Support

One clear advantage of using the Helidon connector, as opposed to the default one
provided by Jersey, is the ability to issue HTTP/2 requests. There are three ways
to enable HTTP/2:

1. Via content negotiation from HTTP/1.1, where the initial request is HTTP/1.1 (text)
and the first response is HTTP/2 (binary), assuming the negotiation is successful.
2. Similar to (1) except that a TLS extension called ALPN is used to convey the
upgrade negotiation. Naturally, this only works with secure connections, so TLS
is a requirement here.
3. Using prior knowledge, where the client simply sends an HTTP/2 request knowing
_a priori_ that the server is capable of handling it. This option always requires TLS.

== Examples

=== HTTP/2 Negotiation Without TLS

Without TLS, HTTP/2 negotiation is accomplished by setting a single property. In the
example below, the property is set on the correspoding `WebTarget`, which indicates
that it applies to all requests created from it.

[source,java]
----
include::{sourcedir}/mp/jaxrs/HelidonConnectorSnippets.java[tag=snippet_3, indent=0]
----

NOTE: Properties in the Jakarta REST Client API can be set on `Client`, `WebTarget` and
`Invocation`  and are inherited accordingly.

The request invocation in the example above will include an HTTP/2 protocol upgrade
request which may be granted by the server if HTTP/2 support is enabled.

=== HTTP/2 Negotiation With TLS/ALPN

ALPN is a TLS extension that can be used for HTTP/2 negotiation. The Helidon connector
accepts a `Tls` instance to enable protocol security and also to
negotiate an HTTP/2 upgrade as shown below.

[source,java]
----
include::{sourcedir}/mp/jaxrs/HelidonConnectorSnippets.java[tag=snippet_4, indent=0]
----

The call to `addApplicationProtocol()` indicates the desire to negotiate a protocol upgrade. Naturally,
ALPN only works on secure connections, so TLS is always configured at the same time.

=== HTTP/2 Prior Knowledge

The last example shows how to enable HTTP/2 when prior knowledge of the server's capabilities is
known ahead of time. In order to force HTTP/2 for the initial request, we must provide an
`Http2ClientProtocolConfig` instance that is properly configured for that purpose. Passing
protocol configurations is a general mechanism supported by the connector; in this example,
we take advantage of this mechanism to pre-configure the desired HTTP/2 support as shown next.

[source,java]
----
include::{sourcedir}/mp/jaxrs/HelidonConnectorSnippets.java[tag=snippet_5, indent=0]
----

The property `HelidonProperties.PROTOCOL_CONFIGS` accepts a list of protocol configurations
that are passed directly to the underlying `WebClient` layer.

== Additional Information

For additional information, see the link:{jakarta-jaxrs-javadoc-url}[Jakarta REST Javadocs].

== Reference

* link:{jakarta-jaxrs-spec-url}#client_api[Jakarta REST Client Specification]
* https://eclipse-ee4j.github.io/jersey.github.io/documentation/latest31x/index.html[Jersey User Guide]