High level wrapper on top of the Apache HTTP client, including JSON support.

The Apache HTTP Client Java libraries are great and allow a great flexibility when it comes to deal with HTTP, HTTPS, different methods, header manipulation, etc. However, it is quickly complex to setup and this setup has to be done for each project which needs to connect to remote applications using HTTP.

This library aims to simplify the HTTP(S) connections by offering an easy configuration and a high level view on the HTTP communication.

This code was initially part of the Ontrack application and has been extracted from it.

Getting the library

Using Gradle:

dependencies {
compile 'net.nemerosa:http-client-core:1.4.1'
}

or:

dependencies {
compile 'net.nemerosa:http-client-json:1.4.1'
}

if you need the JSON support.

The http-client-core depends on JDK8. No support for JDK7 is foreseen.

Creating a HTTP client

Use the ClientBuilder class to configure and create a (HTTP) Client:

Clientclient = ClientBuilder
.create(url, disableSsl)
.withLogger(logger)
.withCredentials(user, password)
.build()

The url is the base URL to connect to.

The disableSsl flag disables SSL checks (host & certificate validity) should be set to false - however, in a testing context, where some servers would not have a valid certificate, it might be useful to set to true. If SSL checks are disabled, a warning will be emitted on the logs.

If set, the logger must be an implementation of the ClientLogger interface. Using the JDK8, it is as simple as doing:

.withLogger(message -> doSomething(message))

The default logger writes the message on a SLF4J logger associated with the Client class.

The credentials are of course optional and will be used for a Basic authentication.

Finally, the Client to use is created using the build() method.

This client can be reused as many times as needed.

Using the client

To perform a GET:

Stringhtml = client.get(
content -> content,
"relative/path/%s",
"param1");

The argument is a ResponseParser interface and is responsible for parsing the HTTP response as text. See below for JSON specific behaviour.

To perform a delete, just use delete(...) instead of get(...).

You can also POST or PUT any entity:

Stringhtml = client.post(
content -> content,
newStringEntity(
"Some text",
ContentType.create("text/plain", "UTF-8")
),
"relative/path/%s",
"param1"
);

Use put(...) for a PUT.

You can also upload a document:

Stringhtml = client.upload(
"parameterName",
newDocument("text/plain", "Some text"),
"fileName.txt",
"relative/path/%s",
"param1"
);

... or download one:

Documentdocument = client.download(
"relative/path/%s",
"param1"
);

Using the JSON library

The http-client-json module leverages the http-client-core for dealing with JSON. It relies on the Jackson JSON library (the one used by Spring).

To create a JSON client, you need a Client, configured as shown above:

JsonClientjsonClient = newJsonClientImpl(
client
);

The JSON parsing/serialisation will be done using a default ObjectMapper. If you need to provide your own, it's also possible:

JsonClientjsonClient = newJsonClientImpl(
client,
objectMapper
);

The calls are the same than for a Client, but for the fact that you do not need any ResponseParser (because JSON is always assumed, for both request and response).

For example:

JsonNodenode = jsonClient.get("relative/%s", "path");

or:

JsonNodenode = jsonClient.post(data, "relative/%s", "path");

where data is any Object that will be serialized as JSON using the ObjectMapper associated with the JsonClient. This can be a JsonNode as well.

Apache HTTP client version

This library depends on Apache HTTP Client 4.5. This might cause conflicts with other libraries using less recent versions.

Developing

Contributing

Contributions are welcome! Fork and create pull requests, or create issues.

Importing in Intellij

• The Lombok plugin must be installed
• Do not forget to enable annotation processing in Preferences > Compiler > Annotation processors