Merge pull request #1 from mb3364/features

Features

Author: urgrue

README.md

@@ -1,13 +1,13 @@
 # Java Async HTTP Client
-A simple asynchronous HTTP client built on top of Java's `HttpURLConnection`.
+A simple, lightweight, asynchronous HTTP client built on top of Java's `HttpURLConnection`.
 
 This project is actively being improved and major changes may break backwards compatibility.
 
 Please feel free to report any issues.
 
 ## Basics
 
-Simply create either an `AsyncHttpClient` (asynchronous) or `HttpClient` (synchronous) instance and make requests through it with the `get()`, `post()`, `put()`, `delete()`, or `head()` methods.
+Simply create either an `AsyncHttpClient` (asynchronous) or `SyncHttpClient` (synchronous) instance and make requests through it with the `get()`, `post()`, `put()`, `delete()`, or `head()` methods.
 Responses are handled by callbacks through `HttpResponseHandler` usually created as an anonymous inner class of the function call.
 
 
@@ -18,34 +18,50 @@ String url = "https://api.twitch.tv/kraken/games/top";
 
 // Set the GET parameters
 RequestParams params = new RequestParams();
-params.put("limit", "1");
-params.put("offset", "0");
+params.put("limit", 1);
+params.put("offset", 0);
 
-AsyncHttpClient client = new AsyncHttpClient();
-client.setHeader("Accept", "application/vnd.twitchtv.v3+json"); // Optional: send custom headers
+HttpClient client = new AsyncHttpClient();
+client.setHeader("Accept", "application/vnd.twitchtv.v3+json"); // Optional: send custom headers, send with all future requests
 client.setUserAgent("my-java-application"); // Optional: set a custom user-agent
 
+client.get(url, params, new StringHttpResponseHandler() {
+    @Override
+    public void onSuccess(int statusCode, Map<String, List<String>> headers, String content) {
+        /* Request was successful */
+    }
+
+    @Override
+    public void onFailure(int statusCode, Map<String, List<String>> headers, String content) {
+        /* Server responded with a status code 4xx or 5xx error */
+    }
+
+    @Override
+    public void onFailure(Throwable throwable) {
+        /* An exception occurred during the request. Usually unable to connect or there was an error reading the response */
+    }
+});
+```
+
+The above example reads String responses using `StringHttpResponseHandler`. It will automatically read the response encoding and encode the String automatically for you.
+
+For raw data in an array of bytes, you may use `HttpResponseHandler`,
+
+```java
 client.get(url, params, new HttpResponseHandler() {
     @Override
-    public void onSuccess(HttpResponse response) {
-        // Successful response from the server
-        System.out.println(response.getStatusCode());
-        System.out.println(response.getStatusMessage());
-        System.out.println(response.getContent());
+    public void onSuccess(int statusCode, Map<String, List<String>> headers, byte[] content) {
+        /* Request was successful */
     }
 
     @Override
-    public void onFailure(HttpResponse response) {
-        // The server returned an error (4xx/5xx status code)
-        System.out.println(response.getUrl());
-        System.out.println(response.getStatusCode());
-        System.out.println(response.getStatusMessage());
+    public void onFailure(int statusCode, Map<String, List<String>> headers, byte[] content) {
+        /* Server responded with a status code 4xx or 5xx error */
     }
 
     @Override
     public void onFailure(Throwable throwable) {
-        // Something went wrong with the request and an exception was thrown
-        throwable.printStackTrace();
+        /* An exception occurred during the request. Usually unable to connect or there was an error reading the response */
     }
 });
 ```
@@ -54,10 +70,18 @@ client.get(url, params, new HttpResponseHandler() {
 
 The `RequestParams` object is used to specify the HTTP request parameters such as for GET or POST. GET parameters are automatically appended to the URL and POST parameters will be x-www-form-urlencoded and sent in the content body.
 
+## Limitations
+
+* Currently only able to send basic form data in UTF-8. Files are currently not supported.
+* All response data is buffered before the callback is fired. This means downloading large files can cause an out of memory error.
+
 ## Download
-* [v1.0.0 jar](https://github.com/mb3364/java-async-http/releases/tag/v1.0.0)
+
+* [v1.2.0 jar](https://github.com/mb3364/java-async-http/releases/tag/v1.2.0)
 
 ## Roadmap
 
-* Handle chunked streaming of data for efficient file uploads/downloads.
-* More control over setting Content-Type.
+* Allow file uploads with form data.
+* Allow streaming downloads to file.
+* More control over setting Content-Type.
+* Handle cookies.

pom.xml

@@ -1,10 +1,10 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>com.mb3364.http</groupId>
     <artifactId>async-http-client</artifactId>
-    <version>1.0.0</version>
+    <version>1.2.0</version>
     <packaging>jar</packaging>
 
     <name>async-http-client</name>

src/main/java/com/mb3364/http/HttpClient.java

@@ -8,41 +8,38 @@
 import java.util.List;
 import java.util.Map;
 
-public class HttpClient {
+public abstract class HttpClient {
 
     public static final String DEFAULT_USER_AGENT = "Java-Async-Http";
-    public static final String DEFAULT_CHARSET = "UTF-8";
 
     private final Map<String, String> headers;
 
-    private String charset;
     private int connectionTimeout = 20000;
     private int dataRetrievalTimeout = 20000;
 
     public HttpClient() {
         headers = Collections.synchronizedMap(new LinkedHashMap<String, String>());
         setUserAgent(DEFAULT_USER_AGENT);
-        setCharset(DEFAULT_CHARSET);
     }
 
     /**
-     * Read the input stream and convert to a string
+     * Reads an InputStream into a byte array.
      *
      * @param inputStream InputStream to read
-     * @return String representing entire input stream contents
+     * @return byte array representing entire InputStream contents
+     * @throws IOException if unable to read stream
      */
-    private static String readStream(InputStream inputStream) {
-        if (inputStream == null) return "";
-        StringBuilder text = new StringBuilder();
-        try (BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream))) {
-            String line;
-            while ((line = reader.readLine()) != null) {
-                text.append(line);
-            }
-        } catch (IOException e) {
-            e.printStackTrace();
+    private static byte[] readStreamAsBytes(InputStream inputStream) throws IOException {
+        if (inputStream == null) return new byte[0];
+
+        ByteArrayOutputStream os = new ByteArrayOutputStream();
+        byte[] buffer = new byte[1024 * 32];
+        int bytesRead;
+        while ((bytesRead = inputStream.read(buffer, 0, buffer.length)) != -1) {
+            os.write(buffer, 0, bytesRead);
         }
-        return text.toString();
+        os.flush();
+        return os.toByteArray();
     }
 
     protected void request(String url, HttpRequestMethod method, RequestParams params, HttpResponseHandler handler) {
@@ -79,38 +76,26 @@ protected void request(String url, HttpRequestMethod method, RequestParams param
             // POST and PUT expect an output body.
             if (method == HttpRequestMethod.POST || method == HttpRequestMethod.PUT) {
                 urlConnection.setDoOutput(true);
-                // TODO: Allow user to set content-type
                 byte[] content = params.toEncodedString().getBytes();
-                urlConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=" + charset);
+                urlConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=" + "utf-8"); // TODO: Allow user to set content-type
                 urlConnection.setRequestProperty("Content-Length", Long.toString(content.length));
+                urlConnection.setFixedLengthStreamingMode(content.length); // Stream the data so we don't run out of memory
                 try (OutputStream os = urlConnection.getOutputStream()) {
                     os.write(content);
                 }
             }
 
             // Response
             int responseCode = urlConnection.getResponseCode();
-            String responseMessage = urlConnection.getResponseMessage();
-
-            // Response Headers
             Map<String, List<String>> responseHeaders = urlConnection.getHeaderFields();
 
-            // Build response object
-            HttpResponse response = new HttpResponse();
-            response.setUrl(urlConnection.getURL().toString());
-            response.setStatusCode(responseCode);
-            response.setStatusMessage(responseMessage);
-            response.setHeaders(responseHeaders);
-
             // 'Successful' response codes will be in interval [200,300)
             if (responseCode >= 200 && responseCode < 300) {
-                String responseContent = readStream(urlConnection.getInputStream());
-                response.setContent(responseContent);
-                handler.onSuccess(response);
+                byte[] responseContent = readStreamAsBytes(urlConnection.getInputStream());
+                handler.onSuccess(responseCode, responseHeaders, responseContent);
             } else {
-                String responseContent = readStream(urlConnection.getErrorStream());
-                response.setContent(responseContent);
-                handler.onFailure(response);
+                byte[] responseContent = readStreamAsBytes(urlConnection.getErrorStream());
+                handler.onFailure(responseCode, responseHeaders, responseContent);
             }
 
         } catch (IOException e) {
@@ -178,10 +163,6 @@ public void setUserAgent(String userAgent) {
         headers.put("User-Agent", userAgent);
     }
 
-    public void setCharset(String charset) {
-        this.charset = charset;
-    }
-
     public int getConnectionTimeout() {
         return connectionTimeout;
     }

src/main/java/com/mb3364/http/HttpResponse.java

@@ -1,9 +1,13 @@
 package com.mb3364.http;
 
+import java.util.List;
+import java.util.Map;
+
 public abstract class HttpResponseHandler {
-    public abstract void onSuccess(HttpResponse response);
 
-    public abstract void onFailure(HttpResponse response);
+    public abstract void onSuccess(int statusCode, Map<String, List<String>> headers, byte[] content);
+
+    public abstract void onFailure(int statusCode, Map<String, List<String>> headers, byte[] content);
 
     public abstract void onFailure(Throwable throwable);
 }

src/main/java/com/mb3364/http/HttpResponseHandler.java

@@ -11,12 +11,18 @@ public class RequestParams {
     public static final String DEFAULT_ENCODING = "UTF-8";
 
     private ConcurrentHashMap<String, String> params = new ConcurrentHashMap<>();
+
     private String encoding;
 
     public RequestParams() {
         encoding = DEFAULT_ENCODING;
     }
 
+    public RequestParams(String key, String value) {
+        this();
+        params.put(key, value);
+    }
+
     public boolean containsKey(String key) {
         return params.containsKey(key);
     }
@@ -25,6 +31,38 @@ public void put(String key, String value) {
         params.put(key, value);
     }
 
+    public void put(String key, short value) {
+        params.put(key, Short.toString(value));
+    }
+
+    public void put(String key, int value) {
+        params.put(key, Integer.toString(value));
+    }
+
+    public void put(String key, double value) {
+        params.put(key, Double.toString(value));
+    }
+
+    public void put(String key, float value) {
+        params.put(key, Float.toString(value));
+    }
+
+    public void put(String key, long value) {
+        params.put(key, Long.toString(value));
+    }
+
+    public void put(String key, boolean value) {
+        params.put(key, Boolean.toString(value));
+    }
+
+    public void put(String key, char value) {
+        params.put(key, Character.toString(value));
+    }
+
+    public void put(Map<String, String> otherMap) {
+        params.putAll(otherMap);
+    }
+
     public String get(String key) {
         return params.get(key);
     }