A Simple HTTP Client – Part 1 (Overview)

This post is the first of a series describing the use and implementation of the Stringtree HTTP Client.

Recently I have been working with systems which talk to each other using REST/HTTP. Providing services and resources is pretty simple using Mojasef, but accessing such resources and consuming such services (in client code and in tests) has always seemed a bit more clumsy than it should be. I tried Apache HTTPClient and HttpUnit, but both seemed cumbersome for simple tasks, and bring in several hundred KB or more of dependencies, which can really bloat a small client application. I’m sure there are others, but I got bored with looking, and instead wrote my own simple HTTP Client which does the things I need without dragging in tons of extra stuff.

The Stringtree HTTP Client consists of just four classes, with no dependencies other than the standard Java APIs:

The point of these classes is to allow simple construction and calling of all valid HTTP requests, including the ability to set and read headers and cookies, simulate the submission of an HTML form, and support both textual and binary content data.

As a very simple example, consider the following code which issues a GET request to a specified URL:

HTTPClient client = new HTTPClient();
Document response = client.get("http://localhost:8080/?a=b");
System.out.println("response content type=" + response.getHeader("Content-Type"));
System.out.println("response content=" + response.getContentAsString());

The above code example shows basic usage of the Stringtree HTTP Client. In more general terms, usage is as follows:

  1. Create an object of the HTTPClient class.
  2. Set any long-lived settings, such as cookies or a user-agent.
  3. Call one of the request methods with appropriate parameters.
  4. Read returned headers and content as required from the returned Document object.
  5. Repeat from (3) for each new request.

A slightly more complex example using a POST request to submit an HTML form might look like:

HTTPClient client = new HTTPClient("Mozilla/5.0 (example)");
client.setCookie("username", "Frank");
Form form = new Form();
form.put("name", "Widget");
form.put("category", "thing");
Document response = client.post("http://localhost:8080/update", form);
boolean ok = "200".equals(response.getHeader(HTTPClient.HTTP_RESPONSE_CODE));

All the request methods return an org.stringtree.http.Document object. This object represents the structure of an HTTP request or response: a collection of name/value headers (which may contain duplicate names), and a block of “content” which may be considered as text or as a sequence of bytes. The HTTPClient code does make one simplifying concession; as seen in the above POST example the HTTP response code is added as a pseudo-header with the name “http.response.code”.

This should be enough to get started playing with the Stringtree HTTP Client. In the next post I will discuss the possibilities for creating and configuring an HTTPClient object in full detail.


  1. hi, while the org.stringtree.http.* package seems interesting enough I didn’t find any licensing information attached to it. And while it is accessible directly from the repository I didnt succeed in downloading it as a part of one of the stringtree projects at sourceforge (which would then help resolving the licensing issues)

    Can you quote me some licensing terms? This one looks so much more concise than apache’s http client package: 10 kB vs 500 kB speaks loud and clear 🙂

    BTW: the “…with no dependencies other than the standard Java APIs…” is not 100% true: you need the URLutils class from org.stringtree.util.

  2. Thanks for the comment. I hope you find the code useful. Please let me know how you get on, especially if you have any thoughts or suggestions.

    I have generally held off from putting licensing information in the code itself – probably because I am just lazy 🙂

    Rest assured that all Stringtree code is easy to use. It is dual licensed: you may choose either LGPL or Apache license (see here for details.) If you don’t like either of these licenses for some reason, let me know. I have also issued versions with other licences in the past.

    I am worried that you could not download the HTTP Client code from sourceforge. What sort of problems did you face?

    As for the dependencies, it seems you have got me on that one. It looks like a dependency has crept in (probably since I wrote that post back in January)

  3. Hey frank, thank you for your answer.. I will look into that.

    The sourceforge “issue” was that you don’t find these files as part of an official source package on sourceforge (I guess because you haven’t released it yet.) It is however, possible to check out from the sourceforge SVN repository.

    One more question though: I guess you drop the connection after a request is done? So no HTTP/1.1. keep alive in here? Is that right?

Comments are closed.