src/site/apt/quickstart.apt

~~ ====================================================================
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~ 
~~   http://www.apache.org/licenses/LICENSE-2.0
~~ 
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~ ====================================================================
~~ 
~~ This software consists of voluntary contributions made by many
~~ individuals on behalf of the Apache Software Foundation.  For more
~~ information on the Apache Software Foundation, please see
~~ <http://www.apache.org/>.

    ----------
    HttpClient Quick Start
    ----------
    ----------
    ----------

HttpClient Quick Start

    [[1]] Download 'Binary' package of the latest official release from 
    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) on the classpath.
  
    * commons-logging-<x.x.x>.jar
  
    * commons-codec-<x.x.x>.jar
  
    * httpcore-<x.x.x>.jar
  
    * httpclient-<x.x.x>.jar
  
    * httpmime-<x.x.x>.jar (*)
    
    * httpclient-cache-<x.x.x>.jar (*)

    * fluent-hc-<x.x.x>.jar (*)

    []

    [[2]] The below code fragment illustrates the execution of HTTP GET and POST requests using the 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 httpPost = new HttpPost("http://targethost/login");
List <NameValuePair> nvps = new ArrayList <NameValuePair>();
nvps.add(new BasicNameValuePair("username", "vip"));
nvps.add(new BasicNameValuePair("password", "secret"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps));
HttpResponse response2 = httpclient.execute(httpPost);

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 {
    httpPost.releaseConnection();
}

-------------    

    Source can be downloaded 
    {{{./httpclient/examples/org/apache/http/examples/client/QuickStart.java}here}}

    [[3]] The same requests can be executed using a simpler, albeit less flexible, 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();

-------------    
    
    Source can be downloaded 
    {{{./httpclient/examples/org/apache/http/examples/client/fuent/FluentQuickStart.java}here}}
    
    [[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.