Jumper

Simplified NIO (non-blocking I/O) HTTP client library with embedded cache. Get your code running in just a couple of minutes. Based on the Jersey library. Highly efficient and scalable with seamless client caching. Reasons for choosing Jumper:

Easy to read (and write) with a simplified builder client.
Enforce performance best practices.
Switch between Apache, Jetty, Netty, Grizzly, HttpUrlConnector implementation with an easy enum selection.
Providing seamless caching of clients for enhanced performance and scalability.
Easy secured connections (HTTPS) to un-certified domains (for QA and testing) with TrustAllSSL mode.
Out of the box performance metrics.
Based on the industry-standard Jersey.

Why not simply use Jersey?

While Jersey is a great library, it merely provides building blocks for http connections. Jumper aims to provide idioms and ready-to-use library that guarantees a high standard of performance and readability in your Java applications.

Jumper’s ultimate goal is to encapsulate, simplify, and facilitate all http client concerns within a Java application.

Choose the right library for your team! Your team is new to Jersey or programming http requests? With Jumper you will get :

Started in just 10 minutes.
Best practices in terms of performance are enforced seamlessly.
Readability and simplified usability.
Simplified non-blocking I/O.
Simplfied compression & seamless de-compression of gzip and deflate encoding.

Compatibility

Java 8+

Dependencies

Jersey 2 - REST framework that provides JAX-RS Reference Implementation.
Google Guava - utilities and cache instrumentation.
Jackson JSON - JSON parsing.
Apache Commons validator - utilities.
SLF4J - logging.

Usage

Basic Architecture

HttpConnector - is the REST http implementation; it should be instantiated by the HttpConnectorBuilder class.
HttpConnectorBuilder - setting the configuration of the http connection; it follows the builder design pattern. methods for collecting metrics and instrumenting various entities.
ClientFactory - provides the HttpConnector with a Client object, either from an internal cache or by instantiation.
Http - a collection of library enums.
HttpConnectorCookieManager - seamless cookies management.

Please see Javadoc comments for these classes to get a better grasp of them.

Installation

Maven

<dependency>
  <groupId>net.centro.rtb</groupId>
  <artifactId>jumper</artifactId>
  <version>${jumper-version}</version>
</dependency>

Gradle

dependencies {
  compile "net.centro.rtb:jumper:${jumper-version}"
}

Javadoc

The library contains a substantial amount of Javadoc comments. These should be available in your IDE, once you declare a dependency on Jumper via Maven or Gradle.

How to use it

(The unit tests contain many examples.)

Simple Get request

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://github.com/centro")
                .build();

httpConnector.execute();

System.out.println(httpConnector.getResponseBody());

//getResponseBody() parse response body to a String

Get request with response mapping

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://github.com/centro")
                .build();

httpConnector.execute();

// Object mapping
MyObject myObject = httpConnector.getResponseBody(MyObject.class);

// GenerticType mapping
GenericType<List<Integer>> type = new GenericType<List<Integer>>() {};
List<Integer> list = httpConnector.getResponseBody(type);

Post request

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
        .url("https://example.com/login")
        .setMethod(Http.HttpMethod.POST)
        .setBody(object)
        .addHeaderProperty("Content-Type", "application/json")
        .storeCookies()
        .build();

httpConnector.execute();

File download request (saveToFile() support both Path and String parameters)

java.nio.file.Path path = Paths.get("/Users/me/home/document.pdf");

http = new HttpConnectorBuilder()
            .url("http://example.com/downloadFile")
            .saveToFile(path)
            .build();

http.execute();

http.saveToFile();

Asyncronized requests

async() - will invoke the request async. and return a future

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://github.com/centro")
                .async()
                .build();

httpConnector.execute();

MyObject myObject = http.getResponseBody(myObject.class);

async(InvocationCallback) - will invoke the request async. and execute the InvocationCallback on response.

InvocationCallback invocationCallback = new InvocationCallback<Response>() {
    @Override
    public void completed(Response response) {
        System.out.println(response.getStatus());
        System.out.println(HttpConnector.getResponseBody(response,String.class));
    }
    
    @Override
    public void failed(Throwable throwable) {
        System.out.println("oops");
    }
};

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://example.com")
                .async(invocationCallback)
                .build();

httpConnector.execute();

JSON parsing

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://example.com/json")
                .async()
                .build();

httpConnector.execute();

ObjectNode objectNode = httpConnector.getResponseBody(ObjectNode.class);

Performance metrics

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
                .url("https://github.com/centro")
                .async()
                .build();

httpConnector.execute();

httpConnector.geResponseTime();

Fetch cookie - Retrieve all cookies stored by multiple requests per thread.

HttpConnector http = HttpConnectorBuilder.newBuilder()
        .url("http://localhost:9998/cookie")
        .storeCookies()
        .build()
        .execute();

Map<String,NewCookie> cookies = HttpConnectorCookieManager.getCookies();
Cookie cookie = HttpConnectorCookieManager.getCookie("test");

Gzip or Deflate encoded data - Parsing a response with gzip or Deflate encoding,

HttpConnector http = HttpConnectorBuilder.newBuilder()
        .url("http://localhost:9998/gzip")
        .build()
        .execute();

// automatically detects gzip, deflate compressed input stream
// and decompress it.

System.out.println(http.getResponseBody());

Gzip or Deflate request body compression - Compressing the request body.

HttpConnector http = HttpConnectorBuilder.newBuilder()
        .url("http://localhost:9998/gzip")
        .setBody(object)
        .compress(Http.Encoding.GZIP)
        .build()
        .execute();

Image (jpeg, png, bmp, wbmp, gif) - Parsing a response of an image.

HttpConnector http = HttpConnectorBuilder.newBuilder()
                .url("https://httpbin.org/image/jpeg")
                .build()
                .execute();

BufferedImage image = null;
image = ImageIO.read(http.getResponseBody(InputStream.class));

File (Multipart) upload - Parsing a file in a client request.

final FileDataBodyPart filePart = new FileDataBodyPart("test", new File("uploadFile.gz"));
final FormDataMultiPart multiPart = (FormDataMultiPart) new FormDataMultiPart()
        .bodyPart(filePart);

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
        .url("http://localhost:9998/multi")
        .addHeaderProperty("Content-Type", "multipart/form-data")
        .setBody(multiPart)
        .setMethod(Http.HttpMethod.POST)
        .build();

httpConnector.execute();

Testing mode - trust uncertified HTTPS domains

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
        .url("https://localhost:9998/slow")
        .trustAllSslContext()
        .build()
        .execute();

Non-ASCII URL - encoding to UTF-8

String url = "http://spain.es/geo?city=" + UriComponent.encode("Anyós", UriComponent.Type.QUERY);

HttpConnector httpConnector = HttpConnectorBuilder.newBuilder()
        .url(url)
        .build()
        .execute();

More info on Jumper

Review the Javadoc documentation and the github.io page. If you run into any issues or have questions, ask at ofir.gal@centro.net

jumper

Simplified NIO HTTP client library with embedded cache, designed with performance in mind.