JarCastingRestClient - Unirest fork
This fork is intended to fix the bugs left by the original authors, improve the API, and provide continuous support. Improvements, new ideas, and bug reports are always welcome. The
Features
Apart from the features provided by the original Unirest Java, this fork also has:
- Updated API to make use of Java 8
- Major Bug fixes
- Support for multiple independent clients
- General API improvements
- Updated async requests to use Java 8 CompletableFuture
- Lazy response body parsing
- Default Gson parser
Maven
<dependency>
<groupId>io.joshworks.unirest</groupId>
<artifactId>unirest-java</artifactId>
<version>1.7.1</version>
</dependency>
Creating a new client with defaults
The following example creates a new basic RestClient instance. At the moment, each client will have its own HttpClient sync and async client.
RestClient client = RestClient.builder().build();
Creating Request
RestClient client = RestClient.builder().build();
HttpResponse<JsonNode> jsonResponse = client.post("http://httpbin.org/post")
.header("accept", "application/json")
.queryString("apiKey", "123")
.asJson();
Base url
RestClient client = RestClient.builder().baseUrl("http://my-api.com/v1").build();
String response = client.get("/some-resource").asString();
Unirest client
Unirest provides the same static methods as the original version. It's ideal for simple usage with default configuration.
String response = Unirest.get("http://my-api.com/v1").asString();
Path parameters
With the new API, there's no need to concatenate path parameters, making the it easier and much more convenient to use. You can either provide a varargs path. Or you can use a template and then use .routeParam() to specify its values.
//Sends a request to http://my-api.com/v1/users
String response = client.post("http://my-api.com", "v1", "users").asString();
//Alternatively
//Also Sends a request to http://my-api.com/v1/users
String response = client.get("http://my-api.com/{verion}/{endpoint}")
.routeParam("verion", "v1")
.routeParam("endpoint", "users")
.asString();
Async requests with CompletableFuture
When using asynchronous requests you can use Java 8 CompletableFuture to handle the response. This also gives you the ability to compose multiple requests in a convenient way.
client.get("http://my-api.com/v1/hello")
.asStringAsync()
.thenAccept(resp -> {
System.out.println(resp.body())
})
.exceptionally(e -> {
e.printStackTrace();
return null;
});
New multipart/form-data and x-www-form-urlencoded API
The new API for form data makes easier to specify the right values for each type of request. When using .part(...) a multipart/form-data request will be sent, .field(...) will create x-www-form-urlencoded request. This makes the interface cleaner and less error prone. The content type is also set automatically.
//multipart
client.post("http://my-service.com/fileUpload")
.part("param3", value)
.part("file", new File("test.txt"))
.asJson();
//form-urlencoded
client.post("http://my-service.com/login")
.field("username", "admin")
.field("password", "admin123")
.asJson();
Serialization
Before using asObject(Class) or .body(Object), is necessary to provide a custom implementation of the ObjectMapper interface. This should be done for each client. Json is supported out-of-the-box, so there's no need to register any other json mapper unless you want a custom configuration. Here's how to configure a new ObjectMapper:
public class XmlMapper implements ObjectMapper {
@Override
public <T> T readValue(String value, Class<T> valueType) {
//...
}
@Override
public String writeValue(Object value) {
//...
}
}
ObjectMappers.register(MediaType.APPLICATION_XML_TYPE, new XmlMapper());
HttpResponse<User> response = client.post("http://my-api.com/echo-xml")
.header("Accept", "application/xml")
.header("Content-Type", "application/xml")
.body(new User("John"))
.asObject(User.class);
Client stats
The API also exposes HttpClient's PoolStats, so you can inspect the usage of each client.
ClientStats stats = client.stats();
int leased = stats.sync.getLeased();
int available = stats.sync.getAvailable();
int max = stats.sync.getMax();
int pending = stats.sync.getPending();
//All clients
Map<String, ClientStats> allStats = ClientContainer.stats();
//...
Exiting an application
RestClient starts a background idle thread monitor, which is a daemon thread. When exiting the application, you can use the ClientContainer to release all the allocated resources, as follows:
//If a client is no longer needed and you want to dispose its resources
client.shutdown();
//When your application is shutting down:
//Closes all client connections and the monitor
ClientContainer.shutdown();