hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r1353605 - in /httpcomponents/httpclient/trunk: fluent-hc/src/site/site.xml httpclient-cache/src/site/site.xml httpclient/src/site/site.xml httpmime/src/site/site.xml src/site/apt/index.apt src/site/apt/quickstart.apt
Date Mon, 25 Jun 2012 15:43:30 GMT
Author: olegk
Date: Mon Jun 25 15:43:28 2012
New Revision: 1353605

URL: http://svn.apache.org/viewvc?rev=1353605&view=rev
Log:
HTTPCLIENT-1201: Quick start doc improvements
Contributed by miles zarathustra <albert.bradley at thomsonreuters.com>

Modified:
    httpcomponents/httpclient/trunk/fluent-hc/src/site/site.xml
    httpcomponents/httpclient/trunk/httpclient-cache/src/site/site.xml
    httpcomponents/httpclient/trunk/httpclient/src/site/site.xml
    httpcomponents/httpclient/trunk/httpmime/src/site/site.xml
    httpcomponents/httpclient/trunk/src/site/apt/index.apt
    httpcomponents/httpclient/trunk/src/site/apt/quickstart.apt

Modified: httpcomponents/httpclient/trunk/fluent-hc/src/site/site.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/fluent-hc/src/site/site.xml?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/fluent-hc/src/site/site.xml (original)
+++ httpcomponents/httpclient/trunk/fluent-hc/src/site/site.xml Mon Jun 25 15:43:28 2012
@@ -33,7 +33,7 @@
   <body>
     <menu name="HttpClient Overview">
       <item name="Description" href="../index.html"/>
-      <item name="Examples" href="../examples.html"/>
+      <item name="Quick Start" href="../quickstart.html"/>
     </menu>
     <menu ref="modules" />
     <menu ref="reports"/>      

Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/site/site.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/site/site.xml?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/site/site.xml (original)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/site/site.xml Mon Jun 25 15:43:28
2012
@@ -33,7 +33,7 @@
   <body>
     <menu name="HttpClient Overview">
       <item name="Description" href="../index.html"/>
-      <item name="Examples" href="../examples.html"/>
+      <item name="Quick Start" href="../quickstart.html"/>
     </menu>
     <menu ref="modules" />
     <menu ref="reports"/>      

Modified: httpcomponents/httpclient/trunk/httpclient/src/site/site.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/site/site.xml?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/site/site.xml (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/site/site.xml Mon Jun 25 15:43:28 2012
@@ -30,7 +30,7 @@
   <body>
     <menu name="HttpClient Overview">
       <item name="Description" href="../index.html"/>
-      <item name="Examples" href="../examples.html"/>
+      <item name="Quick Start" href="../quickstart.html"/>
     </menu>
     <menu ref="modules" />
     <menu ref="reports"/>      

Modified: httpcomponents/httpclient/trunk/httpmime/src/site/site.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpmime/src/site/site.xml?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpmime/src/site/site.xml (original)
+++ httpcomponents/httpclient/trunk/httpmime/src/site/site.xml Mon Jun 25 15:43:28 2012
@@ -30,7 +30,7 @@
   <body>
     <menu name="HttpClient Overview">
       <item name="Description" href="../index.html"/>
-      <item name="Examples" href="../examples.html"/>
+      <item name="Quick Start" href="../quickstart.html"/>
     </menu>
     <menu ref="modules" />
     <menu ref="reports"/>      

Modified: httpcomponents/httpclient/trunk/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/site/apt/index.apt?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/site/apt/index.apt (original)
+++ httpcomponents/httpclient/trunk/src/site/apt/index.apt Mon Jun 25 15:43:28 2012
@@ -47,10 +47,21 @@ HttpClient Overview
 
 {Documentation}
 
-    * HttpClient Tutorial ( {{{./tutorial/html/index.html}HTML}} / {{{./tutorial/pdf/httpclient-tutorial.pdf}PDF}}
)
-    
-    * Some examples of HttpClient in action can be found {{{./examples.html}here}}
+    [[1]] {{{./quickstart.html}Quick Start}} - contains a simple, complete example of an
HTTP GET 
+    and POST with parameters.
+
+    [[1]] {{{./tutorial/html/index.html}HttpClient Tutorial}} - gives a detailed examination
of the 
+    HttpClient API, which was written in close accordance with the (sometimes not very intuitive)

+    HTTP specification/standard.  A copy is also shipped with the release.  
+    {{{./tutorial/pdf/httpclient-tutorial.pdf}A PDF version}} is also available
+        
+    [[1]] {{{./examples.html}HttpClient Examples}} - a set of examples demonstrating some
of 
+    the more complex behavior. 
     
+    [[1]] {{{./primer.html}HttpClient Primer}} - explains the scope of HttpClient.
+    Note that HttpClient is not a browser.  It lacks the UI, HTML renderer and a JavaScript
engine
+    that a browser will possess. 
+   
 {Features}
 
     * Standards based, pure Java, implementation of HTTP versions 1.0 and 1.1

Modified: httpcomponents/httpclient/trunk/src/site/apt/quickstart.apt
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/site/apt/quickstart.apt?rev=1353605&r1=1353604&r2=1353605&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/site/apt/quickstart.apt (original)
+++ httpcomponents/httpclient/trunk/src/site/apt/quickstart.apt Mon Jun 25 15:43:28 2012
@@ -34,7 +34,7 @@ HttpClient Quick Start
     the {{{http://hc.apache.org/downloads.cgi} project download page}}. 
   
     There should be 7 jars in total (components marked with (*) include additional features
and 
-    are optional)
+    are optional) on the classpath.
   
     * commons-logging-<x.x.x>.jar
   
@@ -51,13 +51,75 @@ HttpClient Quick Start
     * fluent-hc-<x.x.x>.jar (*)
 
     []
+
+    [[2]] Quite often the easiest way to get started is with a short example. This example

+    shows how to execute HTTP GET and POST requests using HttpClient native API.
+
+-------------    
+
+DefaultHttpClient httpclient = new DefaultHttpClient();
+HttpGet httpget = new HttpGet("http://targethost/homepage");
+
+HttpResponse response1 = httpclient.execute(httpget);
+
+// The underlying HTTP connection is still held by the response object 
+// to allow the response content to be streamed directly from the network socket. 
+// In order to ensure correct deallocation of system resources 
+// the user MUST either fully consume the response content  or abort request 
+// execution by calling HttpGet#releaseConnection().
+try {
+    System.out.println(response1.getStatusLine());
+    HttpEntity entity1 = response1.getEntity();
+    // do something useful with the response body
+    // and ensure it is fully consumed
+    EntityUtils.consume(entity1);
+} finally {
+    httpget.releaseConnection();
+}
+
+HttpPost httpost = new HttpPost("http://targethost/login");
+List <NameValuePair> nvps = new ArrayList <NameValuePair>();
+nvps.add(new BasicNameValuePair("username", "vip"));
+nvps.add(new BasicNameValuePair("password", "secret"));
+httpost.setEntity(new UrlEncodedFormEntity(nvps));
+HttpResponse response2 = httpclient.execute(httpost);
+try {
+    System.out.println(response2.getStatusLine());
+    HttpEntity entity2 = response2.getEntity();
+    // do something useful with the response body
+    // and ensure it is fully consumed
+    EntityUtils.consume(entity2);
+} finally {
+    httpost.releaseConnection();
+}
+
+-------------    
+
+    [[3]] The same requests can be executed using a simpler, albeit less felxible, fluent
API.
+
+-------------    
+
+// The fluent API relieves the user from having to deal with manual deallocation of system
+// resources at the cost of having to buffer response content in memory in some cases.
+
+Request.Get("http://targethost/homepage")
+    .execute().returnContent();
+Request.Post("http://targethost/login")
+    .bodyForm(Form.form().add("username",  "vip").add("password",  "secret").build())
+    .execute().returnContent();
+
+-------------    
     
-    [[2]] Take a look at the HttpClient tutorial shipped with the release package or available
-    {{{./tutorial/html/index.html}online}} to learn the HttpClient API.
-    
-    [[3]] Another good way of getting started with HttpClient is by seeing it in action.
Take 
-    a look at the samples shipped with the release package or available {{{./examples.html}online}}.
+    Please note fluent facade API requires an optional module 'fluent-hc'.
     
-    [[4]] Please note that HttpClient is not a browser. Importantly it lacks UI, cache, HTML

-    renderer and a JavaScript engine. To learn more about the scope of HttpClient please
refer to 
-    {{{./primer.html}HttpClient Primer}}
+    [[4]] {{{./examples.html}HttpClient Examples}} - a set of examples demonstrating some
of 
+    the more complex behavior. 
+
+    [[5]] {{{./tutorial/html/index.html}HttpClient Tutorial}} - gives a detailed examination
of the 
+    HttpClient API, which was written in close accordance with the (sometimes not very intuitive)

+    HTTP specification/standard.  A copy is also shipped with the release.  
+    {{{./tutorial/pdf/httpclient-tutorial.pdf}A PDF version}} is also available
+
+    [[6]] {{{./primer.html}HttpClient Primer}} - explains the scope of HttpClient.
+    Note that HttpClient is not a browser.  It lacks the UI, HTML renderer and a JavaScript
engine
+    that a browser will possess.   



Mime
View raw message