Package org.apache.juneau.rest.client

Class RestClient

java.lang.Object

org.apache.juneau.rest.client.RestClient

All Implemented Interfaces:

Closeable, AutoCloseable

public final class RestClient
extends Object
implements Closeable

Next-generation transport-agnostic REST client.

Create instances via create() or builder():

// Minimal — uses the built-in JDK HttpClient transport RestClient client = RestClient.create(); // Explicit transport (e.g. for tests) RestClient client = RestClient.builder() .transport(mockTransport) .header("Accept", "application/json") .build();

By default, RestClient uses JavaHttpTransport (backed by the JDK's HttpClient), which ships built into the juneau-rest-client artifact and requires no extra dependencies on Java 11+. Pulling in one of the optional transport modules (juneau-rest-client-apache-httpclient-45, -apache-httpclient-50, -okhttp, -jetty) registers a higher-priority provider via ServiceLoader that takes over automatically. An explicit RestClient.Builder.transport(HttpTransport) call always wins.

See Also:

• Next-Generation REST Client

Since:

9.2.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	RestClient.Builder	Fluent builder for RestClient.

Field Summary

Fields

Modifier and Type	Field	Description
static final List<BodyConverter<?>>	DEFAULT_BODY_CONVERTERS	Default body converters applied in order when RestRequest.body(Object) is called.

Method Summary

Modifier and Type	Method	Description
static RestClient.Builder	builder()	Returns a new RestClient.Builder.
void	close()
static RestClient	create()	Creates a new RestClient using auto-discovered transport.
RestRequest	delete(String url)	Creates a DELETE request to the given URL.
RestRequest	get(String url)	Creates a GET request to the given URL.
RemoteUrlPolicy.AllowedRanges	getAllowedAddressRanges()	Returns the per-client special-purpose address ranges this client re-permits in the SSRF guardrail (see RestClient.Builder.allowAddressRanges(String...)).
String	getDefaultAccept()	Returns the default Accept header value advertising what this client can read.
Optional<Serializer>	getDefaultSerializer()	Returns the explicitly-configured default serializer used for outbound bodies when the format is not otherwise discernable.
Optional<Parser>	getMatchingParser(String contentType)	Returns the parser matching the given response Content-Type, or the explicitly-configured default parser.
Optional<Parser>	getParserForMediaType(String mediaType)	Returns the registered parser matching the given media type, or Optional.empty() if none matches.
Optional<Serializer>	getSerializerForMediaType(String mediaType)	Returns the registered request serializer matching the given media type, or Optional.empty() if none matches.
HttpTransport	getTransport()	Returns the underlying transport used by this client.
RestRequest	head(String url)	Creates a HEAD request to the given URL.
boolean	isAllowPrivateUrls()	Returns the effective builder/settings-level allowPrivateUrls opt-in for this client (the logical OR of RestClient.Builder.allowPrivateUrls(boolean) and the "RestClient.allowPrivateUrls" system property).
RestRequest	patch(String url)	Creates a PATCH request to the given URL.
RestRequest	post(String url)	Creates a POST request to the given URL.
RestRequest	put(String url)	Creates a PUT request to the given URL.
<T> T	remote(Class<T> iface)	Creates a Java proxy for the given Remote-annotated interface.
RestRequest	request(String method, String url)	Creates a request with the given HTTP method and URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_BODY_CONVERTERS

public static final List<BodyConverter<?>> DEFAULT_BODY_CONVERTERS

Default body converters applied in order when RestRequest.body(Object) is called.

Custom converters registered via RestClient.Builder.bodyConverter(BodyConverter[]) are prepended to this list. Call RestClient.Builder.bodyConverters(BodyConverter[]) to replace all defaults.

Method Details

isAllowPrivateUrls

public boolean isAllowPrivateUrls()

Returns the effective builder/settings-level allowPrivateUrls opt-in for this client (the logical OR of RestClient.Builder.allowPrivateUrls(boolean) and the "RestClient.allowPrivateUrls" system property).

The fully effective per-call value additionally ORs in the @Remote/@RemoteOp allowPrivateUrls annotation attribute (see Remote.allowPrivateUrls()).

Returns:

true if this client opts into allowing private/loopback/link-local/metadata @Remote targets.

getAllowedAddressRanges

public RemoteUrlPolicy.AllowedRanges getAllowedAddressRanges()

Returns the per-client special-purpose address ranges this client re-permits in the SSRF guardrail (see RestClient.Builder.allowAddressRanges(String...)). They are unioned with the "RestClient.allowAddressRanges" system property at each check.

Returns:

The allowed ranges. Never null.

create

public static RestClient create()

Creates a new RestClient using auto-discovered transport.

Returns:

A new instance. Never null.

builder

public static RestClient.Builder builder()

Returns a new RestClient.Builder.

get

public RestRequest get(String url)

Creates a GET request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

post

public RestRequest post(String url)

Creates a POST request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

put

public RestRequest put(String url)

Creates a PUT request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

patch

public RestRequest patch(String url)

Creates a PATCH request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

delete

public RestRequest delete(String url)

Creates a DELETE request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

head

public RestRequest head(String url)

Creates a HEAD request to the given URL.

Parameters:

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

request

public RestRequest request(String method,
 String url)

Creates a request with the given HTTP method and URL.

Parameters:

method - The HTTP method. Must not be null.

url - The target URL. Must not be null.

Returns:

A new RestRequest. Never null.

getTransport

public HttpTransport getTransport()

Returns the underlying transport used by this client.

Returns:

The transport. Never null.

getDefaultSerializer

public Optional<Serializer> getDefaultSerializer()

Returns the explicitly-configured default serializer used for outbound bodies when the format is not otherwise discernable.

Only an explicit default set via RestClient.Builder.defaultSerializer(Serializer) is honored — there is no implicit JSON fallback and no lone-registered-entry fallback. A fully-unconfigured client returns Optional.empty().

Returns:

The configured default serializer, or Optional.empty() if none was set.

getMatchingParser

public Optional<Parser> getMatchingParser(String contentType)

Returns the parser matching the given response Content-Type, or the explicitly-configured default parser.

Resolution precedence: an exact media-type match against the client's ParserSet wins; otherwise the explicitly-configured default parser is used; otherwise Optional.empty() is returned. There is no implicit JSON fallback and no lone-registered-entry fallback, so a fully-unconfigured client resolves to empty (callers throw 415 Unsupported Media Type).

Parameters:

contentType - The response Content-Type header value. May be null.

Returns:

The matching parser, or Optional.empty() if nothing matched and no default parser is configured.

getSerializerForMediaType

public Optional<Serializer> getSerializerForMediaType(String mediaType)

Returns the registered request serializer matching the given media type, or Optional.empty() if none matches.

Unlike getDefaultSerializer(), this method performs media-type-driven selection against the client's SerializerSet (via SerializerSet.getSerializer(String)) and returns Optional.empty() on no match so the caller can apply the locked no-match fallback (use the default serializer but still send the overridden Content-Type label). An explicitly-configured single default serializer is also consulted when no set is registered.

Parameters:

mediaType - The desired request media type. May be null/empty.

Returns:

The matching serializer, or Optional.empty() if no registered serializer matches.

getParserForMediaType

public Optional<Parser> getParserForMediaType(String mediaType)

Returns the registered parser matching the given media type, or Optional.empty() if none matches.

Used by the next-gen RemoteClient as the accept fallback parser: it is consulted only when the response Content-Type matched no registered parser (or the response was unlabeled). Returns Optional.empty() on no match so the caller can fall back to the default parser.

Parameters:

mediaType - The desired parse media type. May be null/empty.

Returns:

The matching parser, or Optional.empty() if no registered parser matches.

getDefaultAccept

public String getDefaultAccept()

Returns the default Accept header value advertising what this client can read.

Returns:

The default Accept header value, or null if no parsers and no default parser are configured (no implicit application/json fallback).

remote

public <T> T remote(Class<T> iface)

Creates a Java proxy for the given Remote-annotated interface.

Each method call on the returned proxy will be translated into an HTTP request using this client.

UserService svc = client.remote(UserService.class); String user = svc.getUser("42");

Type Parameters:

T - The interface type.

Parameters:

iface - The interface class. Must be annotated with Remote. Must not be null.

Returns:

A proxy instance backed by this client. Never null.

Throws:

IllegalArgumentException - If iface is not an interface or not annotated with @Remote.

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException