Return-Path: Delivered-To: apmail-hc-commits-archive@www.apache.org Received: (qmail 12034 invoked from network); 24 Jul 2008 20:09:02 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 24 Jul 2008 20:09:02 -0000 Received: (qmail 26583 invoked by uid 500); 24 Jul 2008 20:08:56 -0000 Delivered-To: apmail-hc-commits-archive@hc.apache.org Received: (qmail 26556 invoked by uid 500); 24 Jul 2008 20:08:56 -0000 Mailing-List: contact commits-help@hc.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "HttpComponents Project" Delivered-To: mailing list commits@hc.apache.org Received: (qmail 26535 invoked by uid 99); 24 Jul 2008 20:08:56 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 24 Jul 2008 13:08:56 -0700 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 24 Jul 2008 20:08:10 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id DF72D2388892; Thu, 24 Jul 2008 13:08:05 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r679523 - in /httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client: HttpClient.java package.html Date: Thu, 24 Jul 2008 20:08:05 -0000 To: commits@hc.apache.org From: olegk@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20080724200805.DF72D2388892@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: olegk Date: Thu Jul 24 13:08:05 2008 New Revision: 679523 URL: http://svn.apache.org/viewvc?rev=679523&view=rev Log: Added info about basic execution flow to HttpClient javadocs Modified: httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/package.html Modified: httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java?rev=679523&r1=679522&r2=679523&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java (original) +++ httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java Thu Jul 24 13:08:05 2008 @@ -36,18 +36,69 @@ import org.apache.http.HttpHost; import org.apache.http.HttpRequest; import org.apache.http.HttpResponse; -import org.apache.http.params.HttpParams; -import org.apache.http.protocol.HttpContext; import org.apache.http.client.methods.HttpUriRequest; import org.apache.http.conn.ClientConnectionManager; +import org.apache.http.params.HttpParams; +import org.apache.http.protocol.HttpContext; /** * Interface for an HTTP client. - * HTTP clients encapsulate a smorgasbord of objects required to + * HTTP clients act as a facade to a number of objects required to * execute HTTP requests while handling cookies, authentication, * connection management, and other features. * Thread safety of HTTP clients depends on the implementation * and configuration of the specific client. + *

+ * The usual execution flow can be demonstrated by the + * code snippet below: + *

+ * HttpClient httpclient = new DefaultHttpClient();
+ * 
+ * // Prepare a request object
+ * HttpGet httpget = new HttpGet("http://www.apache.org/"); 
+ * 
+ * // Execute the request
+ * HttpResponse response = httpclient.execute(httpget);
+ * 
+ * // Examine the response status
+ * System.out.println(response.getStatusLine());
+ * 
+ * // Get hold of the response entity
+ * HttpEntity entity = response.getEntity();
+ * 
+ * // If the response does not enclose an entity, there is no need
+ * // to worry about connection release
+ * if (entity != null) {
+ *     InputStream instream = entity.getContent();
+ *     try {
+ *         
+ *         BufferedReader reader = new BufferedReader(
+ *                 new InputStreamReader(instream));
+ *         // do something useful with the response
+ *         System.out.println(reader.readLine());
+ *         
+ *     } catch (IOException ex) {
+ * 
+ *         // In case of an IOException the connection will be released
+ *         // back to the connection manager automatically
+ *         throw ex;
+ *         
+ *     } catch (RuntimeException ex) {
+ * 
+ *         // In case of an unexpected exception you may want to abort
+ *         // the HTTP request in order to shut down the underlying 
+ *         // connection and release it back to the connection manager.
+ *         httpget.abort();
+ *         throw ex;
+ *         
+ *     } finally {
+ * 
+ *         // Closing the input stream will trigger connection release
+ *         instream.close();
+ *         
+ *     }
+ * }
+ *

* * @author Roland Weber * Modified: httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/package.html URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/package.html?rev=679523&r1=679522&r2=679523&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/package.html (original) +++ httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/package.html Thu Jul 24 13:08:05 2008 @@ -36,6 +36,59 @@ The API for client-side HTTP communication and entry point to the HttpClient module. +

+The usual execution flow can be demonstrated by the +code snippet below: + +

+HttpClient httpclient = new DefaultHttpClient();
+
+// Prepare a request object
+HttpGet httpget = new HttpGet("http://www.apache.org/"); 
+
+// Execute the request
+HttpResponse response = httpclient.execute(httpget);
+
+// Examine the response status
+System.out.println(response.getStatusLine());
+
+// Get hold of the response entity
+HttpEntity entity = response.getEntity();
+
+// If the response does not enclose an entity, there is no need
+// to worry about connection release
+if (entity != null) {
+    InputStream instream = entity.getContent();
+    try {
+        
+        BufferedReader reader = new BufferedReader(
+                new InputStreamReader(instream));
+        // do something useful with the response
+        System.out.println(reader.readLine());
+        
+    } catch (IOException ex) {
+
+        // In case of an IOException the connection will be released
+        // back to the connection manager automatically
+        throw ex;
+        
+    } catch (RuntimeException ex) {
+
+        // In case of an unexpected exception you may want to abort
+        // the HTTP request in order to shut down the underlying 
+        // connection and release it back to the connection manager.
+        httpget.abort();
+        throw ex;
+        
+    } finally {
+
+        // Closing the input stream will trigger connection release
+        instream.close();
+        
+    }
+}
+
+