From faef016a2c1334fc5370dead6b034c87800f7f84 Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Mon, 25 Jun 2012 15:43:28 +0000 Subject: [PATCH] HTTPCLIENT-1201: Quick start doc improvements Contributed by miles zarathustra git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1353605 13f79535-47bb-0310-9956-ffa450edef68 --- fluent-hc/src/site/site.xml | 2 +- httpclient-cache/src/site/site.xml | 2 +- httpclient/src/site/site.xml | 2 +- httpmime/src/site/site.xml | 2 +- src/site/apt/index.apt | 17 +++++-- src/site/apt/quickstart.apt | 80 ++++++++++++++++++++++++++---- 6 files changed, 89 insertions(+), 16 deletions(-) diff --git a/fluent-hc/src/site/site.xml b/fluent-hc/src/site/site.xml index b8e29d3af..cc8f29389 100644 --- a/fluent-hc/src/site/site.xml +++ b/fluent-hc/src/site/site.xml @@ -33,7 +33,7 @@ - + diff --git a/httpclient-cache/src/site/site.xml b/httpclient-cache/src/site/site.xml index b8e29d3af..cc8f29389 100644 --- a/httpclient-cache/src/site/site.xml +++ b/httpclient-cache/src/site/site.xml @@ -33,7 +33,7 @@ - + diff --git a/httpclient/src/site/site.xml b/httpclient/src/site/site.xml index 463453f34..02ea59075 100644 --- a/httpclient/src/site/site.xml +++ b/httpclient/src/site/site.xml @@ -30,7 +30,7 @@ - + diff --git a/httpmime/src/site/site.xml b/httpmime/src/site/site.xml index 463453f34..02ea59075 100644 --- a/httpmime/src/site/site.xml +++ b/httpmime/src/site/site.xml @@ -30,7 +30,7 @@ - + diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index a57048d4e..a7a1c11c1 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -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 diff --git a/src/site/apt/quickstart.apt b/src/site/apt/quickstart.apt index 5665e7539..0687808e0 100644 --- a/src/site/apt/quickstart.apt +++ b/src/site/apt/quickstart.apt @@ -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-.jar @@ -51,13 +51,75 @@ HttpClient Quick Start * fluent-hc-.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 nvps = new ArrayList (); +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. + Please note fluent facade API requires an optional module 'fluent-hc'. - [[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}}. - - [[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.