More javadoc documentation for classes

Author: loopj

build.xml

@@ -54,6 +54,7 @@
     <!-- Clean out the build files -->
     <target name="clean">
         <delete dir="build" />
+        <delete dir="doc" />
         <delete>
             <fileset dir="." includes="${jarfile}"/>
             <fileset file="MANIFEST.MF"/>

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

@@ -49,6 +49,9 @@ public class AsyncHttpResponseHandler {
 
     private Handler handler;
 
+    /**
+     * Creates a new AsyncHttpResponseHandler
+     */
     public AsyncHttpResponseHandler() {
         // Set up a handler to post events back to the correct thread if possible
         if(Looper.myLooper() != null) {
@@ -61,44 +64,58 @@ public void handleMessage(Message msg){
     }
 
 
-    // Pre-processing of messages (in background thread)
-    public void sendResponseMessage(HttpResponse response) {
-        StatusLine status = response.getStatusLine();
-        if(status.getStatusCode() >= 300) {
-            sendFailureMessage(new HttpResponseException(status.getStatusCode(), status.getReasonPhrase()));
-        } else {
-            try {
-                HttpEntity entity = null;
-                HttpEntity temp = response.getEntity();
-                if(temp != null) {
-                    entity = new BufferedHttpEntity(temp);
-                }
+    //
+    // Callbacks to be overridden, typically anonymously
+    //
+
+    /**
+     * Fired when the request is started, override to handle in your own code
+     */
+    public void onStart() {}
+
+    /**
+     * Fired in all cases when the request is finished, after both success and failure, override to handle in your own code
+     */
+    public void onFinish() {}
+
+    /**
+     * Fired when a request returns successfully, override to handle in your own code
+     * @param content the body of the HTTP response from the server
+     */
+    public void onSuccess(String content) {}
+
+    /**
+     * Fired when a request fails to complete, override to handle in your own code
+     * @param error the underlying cause of the failure
+     */
+    public void onFailure(Throwable error) {}
 
-                sendSuccessMessage(EntityUtils.toString(entity));
-            } catch(IOException e) {
-                sendFailureMessage(e);
-            }
-        }
-    }
 
-    public void sendSuccessMessage(String responseBody) {
+    //
+    // Pre-processing of messages (executes in background threadpool thread)
+    //
+
+    protected void sendSuccessMessage(String responseBody) {
         sendMessage(obtainMessage(SUCCESS_MESSAGE, responseBody));
     }
 
-    public void sendFailureMessage(Throwable e) {
+    protected void sendFailureMessage(Throwable e) {
         sendMessage(obtainMessage(FAILURE_MESSAGE, e));
     }
 
-    public void sendStartMessage() {
+    protected void sendStartMessage() {
         sendMessage(obtainMessage(START_MESSAGE, null));
     }
 
-    public void sendFinishMessage() {
+    protected void sendFinishMessage() {
         sendMessage(obtainMessage(FINISH_MESSAGE, null));
     }
 
 
-    // Pre-processing of messages (in original calling thread)
+    //
+    // Pre-processing of messages (in original calling thread, typically the UI thread)
+    //
+
     protected void handleSuccessMessage(String responseBody) {
         onSuccess(responseBody);
     }
@@ -108,7 +125,8 @@ protected void handleFailureMessage(Throwable e) {
     }
 
 
-    // Utility functions
+
+    // Methods which emulate android's Handler and Message methods
     protected void handleMessage(Message msg) {
         switch(msg.what) {
             case SUCCESS_MESSAGE:
@@ -147,9 +165,23 @@ protected Message obtainMessage(int responseMessage, Object response) {
     }
 
 
-    // Public callbacks
-    public void onStart() {}
-    public void onFinish() {}
-    public void onSuccess(String content) {}
-    public void onFailure(Throwable error) {}
+    // Interface to AsyncHttpRequest
+    void sendResponseMessage(HttpResponse response) {
+        StatusLine status = response.getStatusLine();
+        if(status.getStatusCode() >= 300) {
+            sendFailureMessage(new HttpResponseException(status.getStatusCode(), status.getReasonPhrase()));
+        } else {
+            try {
+                HttpEntity entity = null;
+                HttpEntity temp = response.getEntity();
+                if(temp != null) {
+                    entity = new BufferedHttpEntity(temp);
+                }
+
+                sendSuccessMessage(EntityUtils.toString(entity));
+            } catch(IOException e) {
+                sendFailureMessage(e);
+            }
+        }
+    }
 }

src/com/loopj/android/http/JsonHttpResponseHandler.java

@@ -23,9 +23,44 @@
 import org.json.JSONObject;
 import org.json.JSONTokener;
 
+/**
+ * Used to intercept and handle the responses from requests made using 
+ * {@link AsyncHttpClient}, with automatic parsing into a {@link JSONObject}
+ * or {@link JSONArray}.
+ * <p>
+ * This class is designed to be passed to get, post, put and delete requests
+ * with the {@link #onSuccess(JSONObject)} or {@link #onSuccess(JSONArray)}
+ * methods anonymously overridden.
+ * <p>
+ * Additionally, you can override the other event methods from the 
+ * parent class.
+ */
 public class JsonHttpResponseHandler extends AsyncHttpResponseHandler {
+    //
+    // Callbacks to be overridden, typically anonymously
+    //
+
+    /**
+     * Fired when a request returns successfully and contains a json object
+     * at the base of the response string. Override to handle in your
+     * own code.
+     * @param response the parsed json object found in the server response (if any)
+     */
+    public void onSuccess(JSONObject response) {}
+
+
+    /**
+     * Fired when a request returns successfully and contains a json array
+     * at the base of the response string. Override to handle in your
+     * own code.
+     * @param response the parsed json array found in the server response (if any)
+     */
+    public void onSuccess(JSONArray response) {}
+
+
+    // Utility methods
     @Override
-    public void handleSuccessMessage(String responseBody) {
+    protected void handleSuccessMessage(String responseBody) {
         super.handleSuccessMessage(responseBody);
 
         try {
@@ -39,12 +74,8 @@ public void handleSuccessMessage(String responseBody) {
             onFailure(e);
         }
     }
-    
+
     protected Object parseResponse(String responseBody) throws JSONException {
         return new JSONTokener(responseBody).nextValue();
     }
-    
-    // Public callbacks
-    public void onSuccess(JSONObject response) {}
-    public void onSuccess(JSONArray response) {}
 }

src/com/loopj/android/http/PersistentCookieStore.java

@@ -34,6 +34,16 @@
 import android.content.SharedPreferences;
 import android.text.TextUtils;
 
+/**
+ * A persistent cookie store which implements the Apache HttpClient
+ * {@link CookieStore} interface. Cookies are stored and will persist on the
+ * user's device between application sessions since they are serialized and
+ * stored in {@link SharedPreferences}.
+ * <p>
+ * Instances of this class are designed to be used with
+ * {@link AsyncHttpClient#setCookieStore}, but can also be used with a 
+ * regular old apache HttpClient/HttpContext if you prefer.
+ */
 public class PersistentCookieStore implements CookieStore {
     private static final String COOKIE_PREFS = "CookiePrefsFile";
     private static final String COOKIE_NAME_STORE = "names";
@@ -42,6 +52,9 @@ public class PersistentCookieStore implements CookieStore {
     private ConcurrentHashMap<String, Cookie> cookies;
     private SharedPreferences cookiePrefs;
 
+    /**
+     * Construct a persistent cookie store.
+     */
     public PersistentCookieStore(Context context) {
         cookiePrefs = context.getSharedPreferences(COOKIE_PREFS, 0);
         cookies = new ConcurrentHashMap<String, Cookie>();
@@ -65,6 +78,7 @@ public PersistentCookieStore(Context context) {
         }
     }
 
+    @Override
     public void addCookie(Cookie cookie) {
         String name = cookie.getName();
 
@@ -78,6 +92,7 @@ public void addCookie(Cookie cookie) {
         prefsWriter.commit();
     }
 
+    @Override
     public void clear() {
         // Clear cookies from local store
         cookies.clear();
@@ -91,6 +106,7 @@ public void clear() {
         prefsWriter.commit();
     }
 
+    @Override
     public boolean clearExpired(Date date) {
         boolean clearedAny = false;
         SharedPreferences.Editor prefsWriter = cookiePrefs.edit();
@@ -119,14 +135,16 @@ public boolean clearExpired(Date date) {
         return clearedAny;
     }
 
-    public Cookie getCookie(String name) {
-        return cookies.get(name);
-    }
-
+    @Override
     public List<Cookie> getCookies() {
         return new ArrayList<Cookie>(cookies.values());
     }
 
+
+    //
+    // Cookie serialization/deserialization
+    //
+
     protected String encodeCookie(SerializableCookie cookie) {
         ByteArrayOutputStream os = new ByteArrayOutputStream();
         try {