{8.2.0-updated} juneau-rest-client

##### Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-rest-client</artifactId> <version>{@property juneauVersion}</version> </dependency>

##### Java Library

juneau-rest-client-{@property juneauVersion}.jar

##### OSGi Module

org.apache.juneau.rest.client_{@property juneauVersion}.jar

Built upon the feature-rich Apache HttpClient library, the Juneau RestClient API adds support for fluent-style REST calls and the ability to perform marshalling of POJOs to and from HTTP parts.

##### Example:

// Create a basic REST client with JSON support and download a bean. MyBean bean = RestClient.create() .simpleJson() .build() .get(URI) .run() .assertStatus().code().is(200) .assertHeader("Content-Type").matchesSimple("application/json*") .getBody().as(MyBean.class);

Breaking apart the fluent call, we can see the classes being used:

RestClientBuilder builder = RestClient.create().simpleJson(); RestClient client = builder.build(); RestRequest req = client.get(URI); RestResponse res = req.run(); RestResponseStatusLineAssertion statusLineAssertion = res.assertStatus(); FluentIntegerAssertion<RestResponse> codeAssertion = statusLineAssertion.code(); res = codeAssertion.is(200); FluentStringAssertion<RestResponse> headerAssertion = res.assertHeader("Content-Type"); res = headerAssertion.matchesSimple("application/json*"); RestResponseBody body = res.getBody(); MyBean bean = body.as(MyBean.class);

It additionally provides support for creating remote proxy interfaces using REST as the transport medium.

##### Example:

// Define a Remote proxy for interacting with a REST interface. @Remote(path="/petstore") public interface PetStore { @RemoteMethod(method=POST, path="/pets") Pet addPet( @Body CreatePet pet, @Header("E-Tag") UUID etag, @Query("debug") boolean debug ); } // Use a RestClient with default Simple JSON support. RestClient client = RestClient.create().simpleJson().build(); PetStore store = client.getRemote(PetStore.class, "http://localhost:10000"); CreatePet createPet = new CreatePet("Fluffy", 9.99); Pet pet = store.addPet(createPet, UUID.randomUUID(), true);

The classes are closely tied to Apache HttpClient, yet provide lots of additional functionality:

- {@link oajr.client2.RestClient} extends {@link org.apache.http.client.HttpClient}, creates {@link oajr.client2.RestRequest} objects.
- {@link oajr.client2.RestRequest} extends {@link org.apache.http.client.methods.HttpUriRequest}, creates {@link oajr.client2.RestResponse} objects.
- {@link oajr.client2.RestResponse} extends {@link org.apache.http.HttpResponse}, creates {@link oajr.client2.RestResponseBody} and {@link oajr.client2.RestResponseHeader} objects.
- {@link oajr.client2.RestResponseBody} extends {@link org.apache.http.HttpEntity}
- {@link oajr.client2.RestResponseHeader} extends {@link org.apache.http.Header}

Instances of this class are built using the {@link oajr.client2.RestClientBuilder} class which can be constructed using the {@link oajr.client2.RestClient#create() RestClient.create()} method as shown above.

Clients are typically created with a root URI so that relative URIs can be used when making requests. This is done using the {@link oajr.client2.RestClientBuilder#rootUri(Object)} method.

##### Example:

// Create a client where all URIs are relative to localhost. RestClient client = RestClient.create().json().rootUri("http://localhost:10000").build(); // Use relative paths. String body = client.get("/subpath").run().getBody().asString();

The {@link oajr.client2.RestClient} class creates {@link oajr.client2.RestRequest} objects using the following methods:

- {@link oajr.client2.RestClient}
  - {@link oajr.client2.RestClient#get(Object) get(uri)} / {@link oajr.client2.RestClient#get() get()}
  - {@link oajr.client2.RestClient#put(Object,Object) put(uri,body)} / {@link oajr.client2.RestClient#put(Object) put(uri)}
  - {@link oajr.client2.RestClient#post(Object) post(uri,body)} / {@link oajr.client2.RestClient#post(Object) post(uri)}
  - {@link oajr.client2.RestClient#patch(Object,Object) patch(uri,body)} / {@link oajr.client2.RestClient#patch(Object) patch(uri)}
  - {@link oajr.client2.RestClient#delete(Object) delete(uri)}
  - {@link oajr.client2.RestClient#head(Object) head(uri)}
  - {@link oajr.client2.RestClient#options(Object) options(uri)}
  - {@link oajr.client2.RestClient#formPost(Object,Object) formPost(uri,body)} / {@link oajr.client2.RestClient#formPost(Object) formPost(uri)}
  - {@link oajr.client2.RestClient#formPostPairs(Object,Object...) formPostPairs(uri,parameters...)}
  - {@link oajr.client2.RestClient#request(String,Object,Object) request(method,uri,body)}

The {@link oajr.client2.RestRequest} class creates {@link oajr.client2.RestResponse} objects using the following methods:

- {@link oajr.client2.RestRequest}
  - {@link oajr.client2.RestRequest#run() run()}
  - {@link oajr.client2.RestRequest#complete() complete()}

The distinction between the two methods is that {@link oajr.client2.RestRequest#complete() complete()} automatically consumes the response body and {@link oajr.client2.RestRequest#run() run()} does not. Note that you must consume response bodies in order for HTTP connections to be freed up for reuse! The {@link java.io.InputStream InputStreams} returned by the {@link oajr.client2.RestResponseBody} object are auto-closing once they are exhausted, so it is often not necessary to explicitly close them.

The following examples show the distinction between the two calls:

// Consuming the response, so use run(). String body = client.get(URI).run().getBody().asString(); // Only interested in response status code, so use complete(). int status = client.get(URI).complete().getStatusCode();