| <dependency>
| <groupId>org.apache.juneau</groupId>
| <artifactId>juneau-rest-client</artifactId>
| <version>9.0.0</version>
| </dependency>
| juneau-rest-client-9.0.0.jar
| org.apache.juneau.rest.client_9.0.0.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.
| // Create a basic REST client with JSON support and download a bean.
| MyBean bean = RestClient.create()
| .json5()
| .build()
| .get(URI)
| .run()
| .assertStatus().asCode().is(200)
| .assertHeader("Content-Type").matchesSimple("application/json*")
| .getContent().as(MyBean.class);
Breaking apart the fluent call, we can see the classes being used:
| RestClient.Builder builder = RestClient.create().json5();
| RestClient client = builder.build();
| RestRequest req = client.get(URI);
| RestResponse res = req.run();
| RestResponseStatusLineAssertion statusLineAssertion = res.assertStatus();
| FluentIntegerAssertion<RestResponse> codeAssertion = statusLineAssertion.asCode();
| res = codeAssertion.is(200);
| FluentStringAssertion<RestResponse> headerAssertion = res.assertHeader("Content-Type");
| res = headerAssertion.matchesSimple("application/json*");
| ResponseContent content = res.getContent();
| MyBean bean = content.as(MyBean.class);
It additionally provides support for creating remote proxy interfaces using REST as the transport medium.
| // Define a Remote proxy for interacting with a REST interface.
| @Remote(path="/petstore")
| public interface PetStore {
|
| @RemotePost("/pets")
| Pet addPet(
| @Content CreatePet pet,
| @Header("E-Tag") UUID etag,
| @Query("debug") boolean debug
| );
| }
|
| PetStore store = RestClient
| .create()
| .json5()
| .build()
| .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 oajrc.RestClient} implements {@link org.apache.http.client.HttpClient}, creates {@link oajrc.RestRequest} objects.
- {@link oajrc.RestRequest} implements {@link org.apache.http.client.methods.HttpUriRequest}, creates {@link oajrc.RestResponse} objects.
- {@link oajrc.RestResponse} implements {@link org.apache.http.HttpResponse}, creates {@link oajrc.ResponseContent} and {@link oajrc.ResponseHeader} objects.
- {@link oajrc.ResponseContent} implements {@link org.apache.http.HttpEntity}
Instances of this class are built using the {@link oajrc.RestClient.Builder} class which can be constructed using
the {@link oajrc.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 oajrc.RestClient.Builder#rootUrl(Object)} method.
| // Create a client where all URIs are relative to localhost.
| RestClient client = RestClient.create().json().rootUrl("http://localhost:10000").build();
|
| // Use relative paths.
| String content = client.get("/subpath").run().getContent().asString();
The {@link oajrc.RestClient} class creates {@link oajrc.RestRequest} objects using the following methods:
- {@link oajrc.RestClient}
- {@link oajrc.RestClient#get(Object) get(uri)} / {@link oajrc.RestClient#get() get()}
- {@link oajrc.RestClient#put(Object,Object) put(uri,body)} / {@link oajrc.RestClient#put(Object) put(uri)}
- {@link oajrc.RestClient#post(Object) post(uri,body)} / {@link oajrc.RestClient#post(Object) post(uri)}
- {@link oajrc.RestClient#patch(Object,Object) patch(uri,body)} / {@link oajrc.RestClient#patch(Object) patch(uri)}
- {@link oajrc.RestClient#delete(Object) delete(uri)}
- {@link oajrc.RestClient#head(Object) head(uri)}
- {@link oajrc.RestClient#options(Object) options(uri)}
- {@link oajrc.RestClient#formPost(Object,Object) formPost(uri,body)} / {@link oajrc.RestClient#formPost(Object) formPost(uri)}
- {@link oajrc.RestClient#formPostPairs(Object,String...) formPostPairs(uri,parameters...)}
- {@link oajrc.RestClient#request(String,Object,Object) request(method,uri,body)}
The {@link oajrc.RestRequest} class creates {@link oajrc.RestResponse} objects using the following methods:
- {@link oajrc.RestRequest}
- {@link oajrc.RestRequest#run() run()}
- {@link oajrc.RestRequest#complete() complete()}
The distinction between the two methods is that {@link oajrc.RestRequest#complete() complete()} automatically consumes the response body and
{@link oajrc.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 oajrc.ResponseContent} 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 content = client.get(URI).run().getContent().asString();
|
| // Only interested in response status code, so use complete().
| int status = client.get(URI).complete().getStatusCode();