Updated documentation, javadocs and formatted code

Author: smarek

CHANGELOG.md

@@ -9,6 +9,12 @@
   - Added support for HTTP PATCH requests
   - Fixed Assert exception when mkdirs in FileAsyncHttpResponseHandler tries to create dirs that already exists
   - Provided option to easily override ClientConnectionManager provision in AsyncHttpClient
+  - Changed onProgress from (int,int) to (long,long) for dealing with large transfers
+  - Renamed typo of `preemtive` to `preemptive` (preemptive basic auth)
+  - Added option to put File array in RequestParams
+  - RequestParams now support forcing Content-Type into `multipart/form-data` even if there are no files/streams to be multiparted
+  - Gradle added support for installing to local maven repository, through `gradle installArchives` task
+  - Added support for Json RFC5179 in JsonHttpResponseHandler
 
 ## 1.4.6 (released 7. 9. 2014)
 

library/src/main/java/com/loopj/android/http/AsyncHttpClient.java

@@ -632,8 +632,8 @@ public void setBasicAuth(String username, String password) {
      * Sets basic authentication for the request. Uses AuthScope.ANY. This is the same as
      * setBasicAuth('username','password',AuthScope.ANY)
      *
-     * @param username  Basic Auth username
-     * @param password  Basic Auth password
+     * @param username   Basic Auth username
+     * @param password   Basic Auth password
      * @param preemptive sets authorization in preemptive manner
      */
     public void setBasicAuth(String username, String password, boolean preemptive) {
@@ -656,9 +656,9 @@ public void setBasicAuth(String username, String password, AuthScope scope) {
      * Sets basic authentication for the request. You should pass in your AuthScope for security. It
      * should be like this setBasicAuth("username","password", new AuthScope("host",port,AuthScope.ANY_REALM))
      *
-     * @param username  Basic Auth username
-     * @param password  Basic Auth password
-     * @param scope     an AuthScope object
+     * @param username   Basic Auth username
+     * @param password   Basic Auth password
+     * @param scope      an AuthScope object
      * @param preemptive sets authorization in preemptive manner
      */
     public void setBasicAuth(String username, String password, AuthScope scope, boolean preemptive) {
@@ -1095,7 +1095,8 @@ public RequestHandle put(Context context, String url, Header[] headers, HttpEnti
     }
 
     /**
-     * Perform a HTTP PATCH request, without any parameters.
+     * Perform a HTTP
+     * request, without any parameters.
      *
      * @param url             the URL to send the request to.
      * @param responseHandler the response handler instance that should handle the response.
@@ -1136,6 +1137,11 @@ public RequestHandle patch(Context context, String url, RequestParams params, Re
      * @param context         the Android Context which initiated the request.
      * @param url             the URL to send the request to.
      * @param responseHandler the response handler instance that should handle the response.
+     * @param entity          a raw {@link HttpEntity} to send with the request, for example, use
+     *                        this to send string/json/xml payloads to a server by passing a {@link
+     *                        org.apache.http.entity.StringEntity}
+     * @param contentType     the content type of the payload you are sending, for example
+     *                        "application/json" if sending a json payload.
      * @return RequestHandle of future request process
      */
     public RequestHandle patch(Context context, String url, HttpEntity entity, String contentType, ResponseHandlerInterface responseHandler) {
@@ -1397,7 +1403,7 @@ public static String getUrlWithQueryString(boolean shouldEncodeUrl, String url,
      *
      * @param inputStream InputStream to be checked
      * @return true or false if the stream contains GZIP compressed data
-     * @throws java.io.IOException
+     * @throws java.io.IOException if read from inputStream fails
      */
     public static boolean isInputStreamGZIPCompressed(final PushbackInputStream inputStream) throws IOException {
         if (inputStream == null)

library/src/main/java/com/loopj/android/http/AsyncHttpResponseHandler.java

@@ -39,7 +39,7 @@
  * {@link #onSuccess(int, org.apache.http.Header[], byte[])} method is designed to be anonymously
  * overridden with your own response handling code. <p>&nbsp;</p> Additionally, you can override the
  * {@link #onFailure(int, org.apache.http.Header[], byte[], Throwable)}, {@link #onStart()}, {@link
- * #onFinish()}, {@link #onRetry(int)} and {@link #onProgress(int, int)} methods as required.
+ * #onFinish()}, {@link #onRetry(int)} and {@link #onProgress(long, long)} methods as required.
  * <p>&nbsp;</p> For example: <p>&nbsp;</p>
  * <pre>
  * AsyncHttpClient client = new AsyncHttpClient();

library/src/main/java/com/loopj/android/http/HttpDelete.java

@@ -35,17 +35,21 @@ public HttpDelete() {
         super();
     }
 
+    /**
+     * @param uri target url as URI
+     */
     public HttpDelete(final URI uri) {
         super();
         setURI(uri);
     }
 
     /**
+     * @param uri target url as String
      * @throws IllegalArgumentException if the uri is invalid.
-    */
+     */
     public HttpDelete(final String uri) {
-            super();
-            setURI(URI.create(uri));
+        super();
+        setURI(URI.create(uri));
     }
 
     @Override

library/src/main/java/com/loopj/android/http/HttpGet.java

@@ -36,17 +36,21 @@ public HttpGet() {
         super();
     }
 
+    /**
+     * @param uri target url as URI
+     */
     public HttpGet(final URI uri) {
         super();
         setURI(uri);
     }
 
     /**
+     * @param uri target url as String
      * @throws IllegalArgumentException if the uri is invalid.
-    */
+     */
     public HttpGet(final String uri) {
-            super();
-            setURI(URI.create(uri));
+        super();
+        setURI(URI.create(uri));
     }
 
     @Override

library/src/main/java/com/loopj/android/http/HttpPatch.java

@@ -18,33 +18,38 @@
 
 package com.loopj.android.http;
 
-import java.net.URI;
 import org.apache.http.client.methods.HttpEntityEnclosingRequestBase;
 
+import java.net.URI;
+
 /**
  * The current Android (API level 21) bundled version of the Apache Http Client does not implement
- * the HTTP PATCH method. Until the Android version is updated this can serve in it's stead. 
+ * the HTTP PATCH method. Until the Android version is updated this can serve in it's stead.
  * This implementation can and should go away when the official solution arrives.
  */
 public final class HttpPatch extends HttpEntityEnclosingRequestBase {
-	
+
     public final static String METHOD_NAME = "PATCH";
 
     public HttpPatch() {
         super();
     }
 
+    /**
+     * @param uri target url as URI
+     */
     public HttpPatch(final URI uri) {
         super();
         setURI(uri);
     }
 
     /**
+     * @param uri target url as String
      * @throws IllegalArgumentException if the uri is invalid.
-    */
+     */
     public HttpPatch(final String uri) {
-            super();
-            setURI(URI.create(uri));
+        super();
+        setURI(URI.create(uri));
     }
 
     @Override

library/src/main/java/com/loopj/android/http/JsonValueInterface.java

@@ -24,7 +24,7 @@
  * not rely on {@link org.json.JSONArray} or {@link org.json.JSONObject} to
  * exchange data.
  *
- * @author Noor Dawod <[email protected]>
+ * @author Noor Dawod {@literal <[email protected]>}
  */
 public interface JsonValueInterface {
 

library/src/main/java/com/loopj/android/http/RequestParams.java

@@ -109,7 +109,7 @@ public class RequestParams implements Serializable {
     protected final ConcurrentHashMap<String, String> urlParams = new ConcurrentHashMap<String, String>();
     protected final ConcurrentHashMap<String, StreamWrapper> streamParams = new ConcurrentHashMap<String, StreamWrapper>();
     protected final ConcurrentHashMap<String, FileWrapper> fileParams = new ConcurrentHashMap<String, FileWrapper>();
-    protected final ConcurrentHashMap<String, List<FileWrapper> >fileArrayParams = new ConcurrentHashMap<String, List<FileWrapper>>();
+    protected final ConcurrentHashMap<String, List<FileWrapper>> fileArrayParams = new ConcurrentHashMap<String, List<FileWrapper>>();
     protected final ConcurrentHashMap<String, Object> urlParamsWithObjects = new ConcurrentHashMap<String, Object>();
     protected String contentEncoding = HTTP.UTF_8;
 
@@ -130,7 +130,7 @@ public void setContentEncoding(final String encoding) {
     /**
      * If set to true will force Content-Type header to `multipart/form-data`
      * even if there are not Files or Streams to be send
-     *
+     * <p>&nbsp;</p>
      * Default value is false
      *
      * @param force boolean, should declare content-type multipart/form-data even without files or streams present
@@ -207,35 +207,34 @@ public void put(String key, String value) {
     /**
      * Adds files array to the request.
      *
-     * @param key the key name for the new param.
+     * @param key   the key name for the new param.
      * @param files the files array to add.
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if one of passed files is not found at time of assembling the requestparams into request
      */
     public void put(String key, File files[]) throws FileNotFoundException {
         put(key, files, null, null);
     }
 
     /**
-     *
      * Adds files array to the request with both custom provided file content-type and files name
      *
      * @param key            the key name for the new param.
-     * @param files           the files array to add.
+     * @param files          the files array to add.
      * @param contentType    the content type of the file, eg. application/json
      * @param customFileName file name to use instead of real file name
      * @throws FileNotFoundException throws if wrong File argument was passed
      */
     public void put(String key, File files[], String contentType, String customFileName) throws FileNotFoundException {
 
-        if(key != null){
+        if (key != null) {
             List<FileWrapper> fileWrappers = new ArrayList<FileWrapper>();
-            for (int i=0;i<files.length;i++){
-                if(files[i] == null || !files[i].exists()){
+            for (int i = 0; i < files.length; i++) {
+                if (files[i] == null || !files[i].exists()) {
                     throw new FileNotFoundException();
                 }
                 fileWrappers.add(new FileWrapper(files[i], contentType, customFileName));
             }
-            fileArrayParams.put(key,fileWrappers);
+            fileArrayParams.put(key, fileWrappers);
         }
     }
 
@@ -489,7 +488,7 @@ public void setUseJsonStreamer(boolean flag) {
      * Sets an additional field when upload a JSON object through the streamer
      * to hold the time, in milliseconds, it took to upload the payload. By
      * default, this field is set to "_elapsed".
-     *
+     * <p>&nbsp;</p>
      * To disable this feature, call this method with null as the field value.
      *
      * @param value field name to add elapsed time, or null to disable
@@ -606,7 +605,7 @@ private HttpEntity createMultipartEntity(ResponseHandlerInterface progressHandle
         // Add file collection
         for (ConcurrentHashMap.Entry<String, List<FileWrapper>> entry : fileArrayParams.entrySet()) {
             List<FileWrapper> fileWrapper = entry.getValue();
-            for (FileWrapper fw:fileWrapper){
+            for (FileWrapper fw : fileWrapper) {
                 entity.addPart(entry.getKey(), fw.file, fw.contentType, fw.customFileName);
             }
         }

library/src/main/java/com/loopj/android/http/ResponseHandlerInterface.java

@@ -91,28 +91,28 @@ public interface ResponseHandlerInterface {
      *
      * @return uri of origin request
      */
-    public URI getRequestURI();
+    URI getRequestURI();
 
     /**
      * Returns Header[] which were used to request
      *
      * @return headers from origin request
      */
-    public Header[] getRequestHeaders();
+    Header[] getRequestHeaders();
 
     /**
      * Helper for handlers to receive Request URI info
      *
      * @param requestURI claimed request URI
      */
-    public void setRequestURI(URI requestURI);
+    void setRequestURI(URI requestURI);
 
     /**
      * Helper for handlers to receive Request Header[] info
      *
      * @param requestHeaders Headers, claimed to be from original request
      */
-    public void setRequestHeaders(Header[] requestHeaders);
+    void setRequestHeaders(Header[] requestHeaders);
 
     /**
      * Can set, whether the handler should be asynchronous or synchronous
@@ -148,7 +148,7 @@ public interface ResponseHandlerInterface {
      * This method is called once by the system when the response is about to be
      * processed by the system. The library makes sure that a single response
      * is pre-processed only once.
-     * <p/>
+     * <p>&nbsp;</p>
      * Please note: pre-processing does NOT run on the main thread, and thus
      * any UI activities that you must perform should be properly dispatched to
      * the app's UI thread.
@@ -162,7 +162,7 @@ public interface ResponseHandlerInterface {
      * This method is called once by the system when the request has been fully
      * sent, handled and finished. The library makes sure that a single response
      * is post-processed only once.
-     * <p/>
+     * <p>&nbsp;</p>
      * Please note: post-processing does NOT run on the main thread, and thus
      * any UI activities that you must perform should be properly dispatched to
      * the app's UI thread.

library/src/main/java/com/loopj/android/http/SaxAsyncHttpResponseHandler.java

@@ -38,11 +38,11 @@
 /**
  * Provides interface to deserialize SAX responses, using AsyncHttpResponseHandler. Can be used like
  * this
- *
+ * <p>&nbsp;</p>
  * <pre>
  *     AsyncHttpClient ahc = new AsyncHttpClient();
  *     FontHandler handlerInstance = ... ; // init handler instance
- *     ahc.post("https://server.tld/api/call", new SaxAsyncHttpResponseHandler<FontHandler>(handlerInstance){
+ *     ahc.post("https://server.tld/api/call", new SaxAsyncHttpResponseHandler{@literal <}FontHandler{@literal >}(handlerInstance){
  *         &#064;Override
  *         public void onSuccess(int statusCode, Header[] headers, FontHandler t) {
  *              // Request got HTTP success statusCode
@@ -52,7 +52,7 @@
  *              // Request got HTTP fail statusCode
  *         }
  *     });
- * <pre/>
+ * </pre>
  *
  * @param <T> Handler extending {@link org.xml.sax.helpers.DefaultHandler}
  * @see org.xml.sax.helpers.DefaultHandler
@@ -85,7 +85,7 @@ public SaxAsyncHttpResponseHandler(T t) {
      *
      * @param entity returned HttpEntity
      * @return deconstructed response
-     * @throws java.io.IOException
+     * @throws java.io.IOException if there is problem assembling SAX response from stream
      * @see org.apache.http.HttpEntity
      */
     @Override