Skip to content

Commit ffc03f3

Browse files
committed
More documentation
1 parent 063b78c commit ffc03f3

File tree

3 files changed

+161
-18
lines changed

3 files changed

+161
-18
lines changed

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

Lines changed: 150 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,30 @@
6565

6666
import android.content.Context;
6767

68+
69+
/**
70+
* The AsyncHttpClient can be used to make asynchronous GET, POST, PUT and
71+
* DELETE HTTP requests in your Android applications. Requests can be made
72+
* with additional parameters by passing a {@link RequestParams} instance,
73+
* and responses can be handled by passing an anonymously overridden
74+
* {@link AsyncHttpResponseHandler} instance.
75+
* <p>
76+
* For example:
77+
* <p>
78+
* <pre>
79+
* AsyncHttpClient client = new AsyncHttpClient("My User Agent");
80+
* client.get("http://www.google.com", new AsyncHttpResponseHandler() {
81+
* &#064;Override
82+
* public void onSuccess(String response) {
83+
* System.out.println(response);
84+
* }
85+
* });
86+
* </pre>
87+
*/
6888
public class AsyncHttpClient {
69-
public static final int DEFAULT_MAX_CONNECTIONS = 10;
70-
public static final int DEFAULT_SOCKET_TIMEOUT = 10 * 1000;
71-
public static final int DEFAULT_MAX_RETRIES = 5;
89+
private static final int DEFAULT_MAX_CONNECTIONS = 10;
90+
private static final int DEFAULT_SOCKET_TIMEOUT = 10 * 1000;
91+
private static final int DEFAULT_MAX_RETRIES = 5;
7292
private static final String ENCODING = "UTF-8";
7393
private static final String HEADER_ACCEPT_ENCODING = "Accept-Encoding";
7494
private static final String ENCODING_GZIP = "gzip";
@@ -83,7 +103,7 @@ public class AsyncHttpClient {
83103

84104
/**
85105
* Creates a new AsyncHttpClient which will identify itself with the user agent userAgent
86-
* @param userAgent The identifier to use in the User-Agent header in requests
106+
* @param userAgent the identifier to use in the User-Agent header in requests
87107
*/
88108
public AsyncHttpClient(String userAgent) {
89109
BasicHttpParams httpParams = new BasicHttpParams();
@@ -135,14 +155,35 @@ public void process(HttpResponse response, HttpContext context) {
135155
requestMap = new WeakHashMap<Context, List<WeakReference<Future>>>();
136156
}
137157

158+
/**
159+
* Sets an optional CookieStore to use when making requests
160+
* @param cookieStore The CookieStore implementation to use, usually an instance of {@link PersistentCookieStore}
161+
*/
138162
public void setCookieStore(CookieStore cookieStore) {
139163
httpContext.setAttribute(ClientContext.COOKIE_STORE, cookieStore);
140164
}
141165

166+
/**
167+
* Overrides the threadpool implementation used when queuing/pooling
168+
* requests. By default, Executors.newCachedThreadPool() is used.
169+
* @param threadPool an instance of {@link ThreadPoolExecutor} to use for queuing/pooling requests.
170+
*/
142171
public void setThreadPool(ThreadPoolExecutor threadPool) {
143172
this.threadPool = threadPool;
144173
}
145174

175+
/**
176+
* Cancels any pending (or potentially active) requests associated with the
177+
* passed Context.
178+
* <p>
179+
* <b>Note:</b> This will only affect requests which were created with a non-null
180+
* android Context. This method is intended to be used in the onDestroy
181+
* method of your android activities to destroy all requests which are no
182+
* longer required.
183+
*
184+
* @param context the android Context instance associated to the request.
185+
* @param mayInterruptIfRunning specifies if active requests should be cancelled along with pending requests.
186+
*/
146187
public void cancelRequests(Context context, boolean mayInterruptIfRunning) {
147188
List<WeakReference<Future>> requestList = requestMap.get(context);
148189
if(requestList != null) {
@@ -157,80 +198,172 @@ public void cancelRequests(Context context, boolean mayInterruptIfRunning) {
157198
}
158199

159200

160-
// Http GET Requests
201+
//
202+
// HTTP GET Requests
203+
//
204+
205+
/**
206+
* Perform a HTTP GET request, without any parameters.
207+
* @param url the URL to send the request to.
208+
* @param responseHandler the response handler instance that should handle the response.
209+
*/
161210
public void get(String url, AsyncHttpResponseHandler responseHandler) {
162211
get(null, url, null, responseHandler);
163212
}
164213

214+
/**
215+
* Perform a HTTP GET request with parameters.
216+
* @param url the URL to send the request to.
217+
* @param params additional GET parameters to send with the request.
218+
* @param responseHandler the response handler instance that should handle the response.
219+
*/
165220
public void get(String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
166221
get(null, url, params, responseHandler);
167222
}
168223

224+
/**
225+
* Perform a HTTP GET request without any parameters and track the Android Context which initiated the request.
226+
* @param context the Android Context which initiated the request.
227+
* @param url the URL to send the request to.
228+
* @param responseHandler the response handler instance that should handle the response.
229+
*/
169230
public void get(Context context, String url, AsyncHttpResponseHandler responseHandler) {
170231
get(context, url, null, responseHandler);
171232
}
172233

234+
/**
235+
* Perform a HTTP GET request and track the Android Context which initiated the request.
236+
* @param context the Android Context which initiated the request.
237+
* @param url the URL to send the request to.
238+
* @param params additional GET parameters to send with the request.
239+
* @param responseHandler the response handler instance that should handle the response.
240+
*/
173241
public void get(Context context, String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
174242
sendRequest(httpClient, httpContext, new HttpGet(getUrlWithQueryString(url, params)), null, responseHandler, context);
175243
}
176244

177245

178-
// Http POST Requests
246+
//
247+
// HTTP POST Requests
248+
//
249+
250+
/**
251+
* Perform a HTTP POST request, without any parameters.
252+
* @param url the URL to send the request to.
253+
* @param responseHandler the response handler instance that should handle the response.
254+
*/
179255
public void post(String url, AsyncHttpResponseHandler responseHandler) {
180256
post(null, url, null, responseHandler);
181257
}
182258

259+
/**
260+
* Perform a HTTP POST request with parameters.
261+
* @param url the URL to send the request to.
262+
* @param params additional POST parameters or files to send with the request.
263+
* @param responseHandler the response handler instance that should handle the response.
264+
*/
183265
public void post(String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
184266
post(null, url, params, responseHandler);
185267
}
186268

187-
public void post(Context context, String url, AsyncHttpResponseHandler responseHandler) {
188-
post(context, url, null, responseHandler);
189-
}
190-
269+
/**
270+
* Perform a HTTP POST request and track the Android Context which initiated the request.
271+
* @param context the Android Context which initiated the request.
272+
* @param url the URL to send the request to.
273+
* @param params additional POST parameters or files to send with the request.
274+
* @param responseHandler the response handler instance that should handle the response.
275+
*/
191276
public void post(Context context, String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
192277
post(context, url, paramsToEntity(params), null, responseHandler);
193278
}
194279

280+
/**
281+
* Perform a HTTP POST request and track the Android Context which initiated the request.
282+
* @param context the Android Context which initiated the request.
283+
* @param url the URL to send the request to.
284+
* @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}.
285+
* @param contentType the content type of the payload you are sending, for example application/json if sending a json payload.
286+
* @param responseHandler the response handler instance that should handle the response.
287+
*/
195288
public void post(Context context, String url, HttpEntity entity, String contentType, AsyncHttpResponseHandler responseHandler) {
196289
sendRequest(httpClient, httpContext, addEntityToRequestBase(new HttpPost(url), entity), contentType, responseHandler, context);
197290
}
198291

199292

200-
// Http PUT Requests
293+
//
294+
// HTTP PUT Requests
295+
//
296+
297+
/**
298+
* Perform a HTTP PUT request, without any parameters.
299+
* @param url the URL to send the request to.
300+
* @param responseHandler the response handler instance that should handle the response.
301+
*/
201302
public void put(String url, AsyncHttpResponseHandler responseHandler) {
202303
put(null, url, null, responseHandler);
203304
}
204305

306+
/**
307+
* Perform a HTTP PUT request with parameters.
308+
* @param url the URL to send the request to.
309+
* @param params additional PUT parameters or files to send with the request.
310+
* @param responseHandler the response handler instance that should handle the response.
311+
*/
205312
public void put(String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
206313
put(null, params, responseHandler);
207314
}
208315

209-
public void put(Context context, String url, AsyncHttpResponseHandler responseHandler) {
210-
put(context, url, null, responseHandler);
211-
}
212-
316+
/**
317+
* Perform a HTTP PUT request and track the Android Context which initiated the request.
318+
* @param context the Android Context which initiated the request.
319+
* @param url the URL to send the request to.
320+
* @param params additional PUT parameters or files to send with the request.
321+
* @param responseHandler the response handler instance that should handle the response.
322+
*/
213323
public void put(Context context, String url, RequestParams params, AsyncHttpResponseHandler responseHandler) {
214324
put(context, url, paramsToEntity(params), null, responseHandler);
215325
}
216326

327+
/**
328+
* Perform a HTTP PUT request and track the Android Context which initiated the request.
329+
* @param context the Android Context which initiated the request.
330+
* @param url the URL to send the request to.
331+
* @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}.
332+
* @param contentType the content type of the payload you are sending, for example application/json if sending a json payload.
333+
* @param responseHandler the response handler instance that should handle the response.
334+
*/
217335
public void put(Context context, String url, HttpEntity entity, String contentType, AsyncHttpResponseHandler responseHandler) {
218336
sendRequest(httpClient, httpContext, addEntityToRequestBase(new HttpPut(url), entity), contentType, responseHandler, context);
219337
}
220338

221339

222-
// Http DELETE Requests
340+
//
341+
// HTTP DELETE Requests
342+
//
343+
344+
/**
345+
* Perform a HTTP DELETE request.
346+
* @param url the URL to send the request to.
347+
* @param responseHandler the response handler instance that should handle the response.
348+
*/
223349
public void delete(String url, AsyncHttpResponseHandler responseHandler) {
224350
delete(null, url, responseHandler);
225351
}
226352

353+
/**
354+
* Perform a HTTP DELETE request.
355+
* @param context the Android Context which initiated the request.
356+
* @param url the URL to send the request to.
357+
* @param responseHandler the response handler instance that should handle the response.
358+
*/
227359
public void delete(Context context, String url, AsyncHttpResponseHandler responseHandler) {
228360
final HttpDelete delete = new HttpDelete(url);
229361
sendRequest(httpClient, httpContext, delete, null, responseHandler, context);
230362
}
231363

232364

233-
// Private stuf
365+
366+
// Private stuff
234367
private void sendRequest(DefaultHttpClient client, HttpContext httpContext, HttpUriRequest uriRequest, String contentType, AsyncHttpResponseHandler responseHandler, Context context) {
235368
if(contentType != null) {
236369
uriRequest.addHeader("Content-Type", contentType);

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
import org.apache.http.impl.client.AbstractHttpClient;
2929
import org.apache.http.protocol.HttpContext;
3030

31-
public class AsyncHttpRequest implements Runnable {
31+
class AsyncHttpRequest implements Runnable {
3232
private AbstractHttpClient client;
3333
private HttpContext context;
3434
private HttpUriRequest request;

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,16 @@
3131
import android.os.Message;
3232
import android.os.Looper;
3333

34+
/**
35+
* Used to intercept and handle the responses from requests made using
36+
* {@link AsyncHttpClient}.
37+
* <p>
38+
* This class is designed to be passed to get, post, put and delete requests
39+
* with the {@link #onSuccess(String)} method anonymously overridden.
40+
* <p>
41+
* Optionally, you can also override the {@link #onFailure(Throwable)},
42+
* {@link #onStart()}, and {@link #onFinish()} methods as required.
43+
*/
3444
public class AsyncHttpResponseHandler {
3545
private static final int SUCCESS_MESSAGE = 0;
3646
private static final int FAILURE_MESSAGE = 1;

0 commit comments

Comments
 (0)