mp.jaxrs.jaxrs-client.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2022, 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.
///////////////////////////////////////////////////////////////////////////////
= Jakarta REST Client
:feature-name: Jakarta REST Client
:description: Jakarta REST Client
:keywords: helidon, rest, jax-rs, client, microprofile, micro-profile
:rootdir: {docdir}/../..
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
The Jakarta REST Client defines a programmatic API to access
REST resources. This API sits at a higher level than traditional HTTP client APIs and
provides full integration with server-side API concepts like providers. It differs
from the xref:../restclient.adoc[Rest Client API] in that it does not support
annotations or proxies, but instead uses builders and a fluent API to
create and execute requests.
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.jersey
helidon-jersey-client
----
== API
Bootstrapping the API is done by obtaining an instance of `Client`. A single instance of this
class can be used to create multiple service requests that share the same basic
configuration, e.g., the same set of _providers_. More precisely, from a `Client` we
can create multiple `WebTarget` s, and in turn, from each `WebTarget` we can
create multiple `Invocation` s.
[source,java]
----
include::{sourcedir}/mp/jaxrs/JaxrsClientSnippets.java[tag=snippet_1, indent=0]
----
In the snippet above, the call to `target` returns a `WebTarget`, and the call to
`request` returns an `Invocation.Builder`; finally, the call to `get` returns the `Response`
that results from accessing the remote resource.
Given that this API is fully integrated with message body readers and writers, it is
possible to request the response body be provided after conversion to a Java type
-- such as a `String` in the example below.
[source,java]
----
include::{sourcedir}/mp/jaxrs/JaxrsClientSnippets.java[tag=snippet_2, indent=0]
----
Alternatively, there are also methods in `Response` that can trigger similar conversions.
Configuration can be specified at the `Client` or `WebTarget` level, as both types implement
`Configurable`. This enables common configuration to be inherited by a `WebTarget` created
from a `Client` instance. In either case, several `register` methods can be used to
configure providers such as filters and exception mappers.
[source,java]
----
include::{sourcedir}/mp/jaxrs/JaxrsClientSnippets.java[tag=snippet_3, indent=0]
----
The example above shows registration of `GreetFilter.class` for all targets and
registration of `GreetExceptionMapper.class` for just one of them. The same
logic applies to other types of configuration such as properties and features.
The Jakarta REST Client API has support for asynchronous invocations. Accessing
a resource asynchronously prevents the calling thread from blocking for the
duration of the call. By default, all invocations are _synchronous_ but can be
turned into either asynchronous or reactive calls by simply inserting the
corresponding fluent method call during the creation phase.
Using `Future`:
[source,java]
----
include::{sourcedir}/mp/jaxrs/JaxrsClientSnippets.java[tag=snippet_4, indent=0]
----
Or using a more modern, reactive style:
[source,java]
----
include::{sourcedir}/mp/jaxrs/JaxrsClientSnippets.java[tag=snippet_5, indent=0]
----
In either case, the implementation will ensure the calling thread is not blocked
and that the result from the invocation is available upon request or via a callback
mechanism.
== Configuration
Configuration for this API is all done programmatically as shown in the previous sections.
== Examples
See <> for same simple examples. For additional information, refer to the
link:{jakarta-jaxrs-spec-url}#client_api[Jakarta REST Client Specification].
== 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]