{updated} juneau-rest-client
Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-rest-client</artifactId> <version>7.2.0</version> </dependency>

Java Library

juneau-rest-client-7.2.0.jar

OSGi Module

org.apache.juneau.rest.client_7.2.0.jar

The REST client API provides the ability to access remote REST interfaces and transparently convert the input and output to and from POJOs using any of the provided serializers and parsers.

Built upon the Apache HttpClient libraries, it extends that API and provides specialized APIs for working with REST interfaces while maintaining all the functionality available in the HttpClient API.

// Create a reusable JSON client. try (RestClient client = RestClient.create().json().build()) { // The address of the root resource. String url = "http://localhost:10000/addressBook"; // Do a REST GET against a remote REST interface and convert // the response to an unstructured ObjectMap object. ObjectMap m1 = client.doGet(url).getResponse(ObjectMap.class); // Same as above, except parse the JSON as a bean. AddressBook a2 = client.doGet(url).getResponse(AddressBook.class); } try (RestClient client = RestClient.create().serializer(XmlSerializer.class).parser(XmlSerializer.class).build()) { // Add a person to the address book. // Use XML as the transport medium. Person p = new Person("Joe Smith", 21); int returnCode = client.doPost(url + "/entries", p).run(); }

Juneau provides an HTTP client API that makes it extremely simple to connect to remote REST interfaces and seemlessly send and receive serialized POJOs in requests and responses.

Features

The client API is designed to work as a thin layer on top of the proven Apache HttpClient API. By leveraging the HttpClient library, details such as SSL certificate negotiation, proxies, encoding, etc... are all handled in Apache code.

The Juneau client API prereq's Apache HttpClient 4.5+. At a minimum, the following jars are required:

Example:

// Examples below use the Juneau Address Book resource example // Create a reusable client with JSON support try (RestClient client = RestClient.create().json().build()) { // GET request, ignoring output try { int rc = client.doGet("http://localhost:10000/addressBook").run(); // Succeeded! } catch (RestCallException e) { // Failed! System.err.println( String.format("status=%s, message=%s", e.getResponseStatus(), e.getResponseMessage()) ); } // Remaining examples ignore thrown exceptions. // GET request, secure, ignoring output client.doGet("https://localhost:9443/sample/addressBook").run(); // GET request, getting output as a String. No POJO parsing is performed. // Note that when calling one of the getX() methods, you don't need to call connect() or disconnect(), since // it's automatically called for you. String output = client.doGet("http://localhost:10000/addressBook") .getResponseAsString(); // GET request, getting output as a Reader Reader r = client.doGet("http://localhost:10000/addressBook") .getReader(); // GET request, getting output as an untyped map // Input must be an object (e.g. "{...}") ObjectMap m = client.doGet("http://localhost:10000/addressBook/0") .getResponse(ObjectMap.class); // GET request, getting output as an untyped list // Input must be an array (e.g. "[...]") ObjectList l = client.doGet("http://localhost:10000/addressBook") .getResponse(ObjectList.class); // GET request, getting output as a parsed bean // Input must be an object (e.g. "{...}") // Note that you don't have to do any casting! Person p = client.doGet("http://localhost:10000/addressBook/0") .getResponse(Person.class); // GET request, getting output as a parsed bean // Input must be an array of objects (e.g. "[{...},{...}]") Person[] pa = client.doGet("http://localhost:10000/addressBook") .getResponse(Person[].class); // Same as above, except as a List<Person> List<Person> pl = client.doGet("http://localhost:10000/addressBook") .getResponse(List.class, Person.class); // GET request, getting output as a parsed string // Input must be a string (e.g. "<string>foo</string>" or "'foo'") String name = client.doGet("http://localhost:10000/addressBook/0/name") .getResponse(String.class); // GET request, getting output as a parsed number // Input must be a number (e.g. "<number>123</number>" or "123") int age = client.doGet("http://localhost:10000/addressBook/0/age") .getResponse(Integer.class); // GET request, getting output as a parsed boolean // Input must be a boolean (e.g. "<boolean>true</boolean>" or "true") boolean isCurrent = client.doGet("http://localhost:10000/addressBook/0/addresses/0/isCurrent") .getResponse(Boolean.class); } // GET request, getting a filtered object try (RestClient client = RestClient.create().pojoSwaps(CalendarSwap.ISO8601.class).build()) { Calendar birthDate = client.doGet("http://localhost:10000/addressBook/0/birthDate") .getResponse(GregorianCalendar.class); // PUT request on regular field String newName = "John Smith"; int rc = client.doPut("http://localhost:10000/addressBook/0/name", newName).run(); // PUT request on filtered field Calendar newBirthDate = new GregorianCalendar(1, 2, 3, 4, 5, 6); rc = client.doPut("http://localhost:10000/addressBook/0/birthDate", newBirthDate).run(); // POST of a new entry to a list Address newAddress = new Address("101 Main St", "Anywhere", "NY", 12121, false); rc = client.doPost("http://localhost:10000/addressBook/0/addresses", newAddress).run(); }

Notes: