Skip to content
HTTP for humans, inspired by the amazing Python requests library.
Java
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/main/java/com/github/fracpete/requests4j
.gitignore
LICENSE
README.md
RELEASE.md
pom.xml

README.md

requests4j

HTTP for humans using Java, inspired by the amazing requests Python library. Not as feature rich, but it gets a lot done.

Why yet another Java HTTP client library?

JSoup was missing some functionality that I needed and the Apache HttpClient library seemed a bit too cumbersome to use. Instead, I reused functionality that I had written for my ADAMS framework over the years and turned it into a separate library, taking the requests API as model to make this library easy to use.

Usage

The following sections describe how to use the library.

Creating a request

The following methods are supported through the com.github.fracpete.requests4j.Requests class:

  • GET -- Requests.get()
  • POST -- Requests.post()
  • PUT -- Requests.put()
  • PATCH -- Requests.patch()
  • HEAD -- Requests.head()
  • DELETE -- Requests.delete()

The above mentioned methods can also take a URL string or a java.net.URL object, initializing the URL straight away. Otherwise, you need to set the URL via the url(String) or url(java.net.URL) method.

Calling one the request methods will generate an instance of the Request class (package com.github.fracpete.requests4j.core). This class supports daisy-chaining to make it easy to configure a full request with minimal code to write.

Headers and parameters

You can set custom HTTP headers using the following methods:

  • header(String,String) -- setting a single header, name and value
  • headers(Map<String,String>) -- setting multiple headers at once

Similarly, you can set parameters, eg to be encoded in the URL for GET requests, using the following methods:

  • parameter(String,String) -- setting a single parameter, name and value
  • parameter(Map<String,String>) -- setting multiple parameters at once

HTML forms

Being able to upload data, be it simple parameters or files, is an important feature for a HTTP client library. In case of GET, you can only use simple parameters, as they get appended to the URL of the request. POST, on the other hand, makes use of the multipart/form-data content type, allowing you to upload files (or any binary data) as well.

In order to make use of form data, you need to call the formData(FormData) method, with an instance of FormData (package com.github.fracpete.requests4j.form). The FormData class allows you to either add parameter objects (derived from AbstractParameter) or directly add simple parameters, files or input streams (eg a java.io.ByteArrayInputStream if you have the data only in its binary form).

The following example POSTs a file to the server with some credentials as part of the form data:

import com.github.fracpete.requests4j.Requests;
import com.github.fracpete.requests4j.core.Response;
import com.github.fracpete.requests4j.form.FormData;

public class FormUpload {
  public static void main(String[] args) throws Exception {
    Response r = Requests.post("http://some.server.com/upload")
      .formData(
        new FormData()
          .addFile("file", "/some/where/important.doc")
          .add("user", "myuser")
          .add("password", "mysecretpassword")
      )
      .execute();
    System.out.printnl(r);
  }
}

Execute and response

Once fully configured, you can execute a request with the execute() method, which will either fail with an exception or return a Response object (package com.github.fracpete.requests4j.core).

With a Response object, you have access to:

  • HTTP status code -- statusCode()
  • HTTP status message -- statusMessage()
  • HTTP headers -- headers()
  • Cookies -- cookies() (parsed from the Set-Cookie headers)
  • the body of the response
    • the raw byte array -- body()
    • as (UTF-8) text -- text()
    • as text using a custom encoding -- text(String)

With the saveBody methods, you can save the binary response data as is to the supplied file.

Sessions

To avoid having to string along and update any cookies for requests, you can simply create a Session object which will take of that (package com.github.fracpete.requests4j). The Session object has the same methods for instantiating request (though this time non-static) as the Requests class described above. The Session class also supports hostname verification (see below), which it will apply to each subsequent request.

import com.github.fracpete.requests4j.Requests;
import com.github.fracpete.requests4j.Session;
import com.github.fracpete.requests4j.core.FileResponse;

public class SessionExample {
  public static void main(String[] args) {
    Session session = new Session();
    Response login = session.post("http://some.server.com/login")
      .formData(
        new FormData()
          .add("user", "myuser")
          .add("password", "mysecretpassword")
      )
      .execute();
    if (login.ok()) {
      Response action = session.get("http://some.server.com/somethingelse")
        .execute();
      System.out.println(action.text());
    }
  }
}

Advanced usage

Different response objects

The Response object simply stores the received data in memory, which is fine for receiving HTML pages or small binary objects. However, for downloading large binary files, it is recommended to use one of the following response classes instead (package com.github.fracpete.requests4j.core):

  • FileResponse - streams the incoming data straight to the specified output file
  • StreamResponse - uses the supplied java.io.OutputStream to forward the incoming data to

Each of these classes implements the HttpResponse interface that all response classes share, giving you access to the following methods:

  • HTTP status code -- statusCode()
  • HTTP status message -- statusMessage()
  • HTTP headers -- headers()
  • Cookies -- cookies() (parsed from the Set-Cookie headers)

Instead of using the execute() method, you now use the execute(HttpResponse) method, supplying the fully configured response object. The following example shows how to download a remote ZIP file straight to a file:

import com.github.fracpete.requests4j.Requests;
import com.github.fracpete.requests4j.core.FileResponse;

public class FileResponseDownload {
  public static void main(String[] args) {
    FileResponse r = Requests.get("http://some.server.com/largefile.zip")
      .execute(new FileResponse("/some/where/largefile.zip"));
    if (r.ok())
      System.out.println("Saved to " + r.outputFile());
  }
}

Authentication

Some websites may require you to log in via password dialogs (eg Apache's htpasswd functionality). In that case, you can use BasicAuthentication to provide these credentials:

import com.github.fracpete.requests4j.Requests;
import com.github.fracpete.requests4j.auth.BasicAuthentication;
import com.github.fracpete.requests4j.core.Response;

public class Auth {
  public static void main(String[] args) throws Exception {
    Response r = Requests.get("http://some.server.com/")
      .auth(new BasicAuthentication("USER", "PASSWORD"))
      .execute();
  }
}

Redirects

Some websites, like sourceforge may perform redirects (eg from http to https). By default redirects are not allowed, but you can enable them using the allowRedirects(boolean) method. With the maxRedirects(int) method you can set the upper limit to the number of redirects to follow through (default is 3).

The following example downloads a Weka zip file from sourceforge.net:

public class Redirect {
  public static void main(String[] args) throws Exception {
    Response r = Requests.get("http://sourceforge.net/projects/weka/files/weka-3-9/3.9.3/weka-3-9-3.zip/download")
      .allowRedirects(true)
      .execute();
  }
}

Proxies

Basic proxy support is available through the proxy(...) and noProxy() methods. The following request configures a proxy (proxy.domain.com:80) for http connections:

import java.net.Proxy;

public class Redirect {
  public static void main(String[] args) throws Exception {
    Response r = Requests.get("http://some.server.com/")
      .proxy(Proxy.Type.HTTP, "proxy.domain.com", 80)
      .execute();
  }
}

Hostname verification

In certain cases, like development phase, it may be necessary to change Java's default hostname verification for https connections. This is possible using the hostnameVerification(javax.net.ssl.HostnameVerifier) or disableHostnameVerification() methods. The following pre-built verification schemes are available (package com.github.fracpete.requests4j.ssl):

  • LocahostVerification - localhost/127.0.0.1 always succeeds
  • NoHostnameVerification - always succeeds
  • RegExpHostnameVerification - matches the hostname against a regular expression

Examples

  • ReadHtml -- grabs the start page of github.com (storing the response in memory), dumps it to standard out, next to the cookies it received.
  • DownloadWeka -- downloads a Weka zip file and streams the downloaded file straight to disk
  • DownloadWekaAsStream -- downloads a Weka zip file to a supplied output stream.

Maven

Use the following dependency in your pom.xml:

    <dependency>
      <groupId>com.github.fracpete</groupId>
      <artifactId>requests4j</artifactId>
      <version>0.0.5</version>
    </dependency>
You can’t perform that action at this time.