~~ ====================================================================
~~ 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 HttpClient 5.0 release or configure
    dependency on {{{./httpclient5/dependency-info.html}HttpClient}} and 
    {{{./httpclient5-fluent/dependency-info.html}Fluent HC}} modules using a dependency 
    manager of your choice as described {{{./download.html}here}}. 

    [[1]] HttpClient 5.0 requires Java 1.7 or newer. 

    [[1]] The below code fragment illustrates the execution of HTTP GET and POST requests using 
    HttpClient classic API.

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

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpGet = new HttpGet("http://targethost/homepage");
CloseableHttpResponse 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 call CloseableHttpResponse#close() from a finally clause.
// Please note that if response content is not fully consumed the underlying
// connection cannot be safely re-used and will be shut down and discarded
// by the connection manager. 
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 {
    response1.close();
}

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));
CloseableHttpResponse 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 {
    response2.close();
}
-------------    

    Source can be downloaded 
    {{{./httpclient5/examples/org/apache/hc/client5/http/examples/QuickStart.java}here}}

    [[1]] 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 
    {{{./httpclient5-fluent/examples/org/apache/hc/client5/http/examples/fluent/FluentQuickStart.java}here}}

    [[1]] The below code fragment illustrates the execution of HTTP requests using 
    HttpClient async API.

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

CloseableHttpAsyncClient httpclient = HttpAsyncClients.createDefault();
// Start the client
httpclient.start();

// Execute request
final SimpleHttpRequest request1 = SimpleHttpRequest.get("http://httpbin.org/get");
Future<SimpleHttpResponse> future = httpclient.execute(request1, null);
// and wait until response is received
final SimpleHttpResponse response1 = future.get();
System.out.println(request1.getRequestUri() + "->" + response1.getCode());

// One most likely would want to use a callback for operation result
final CountDownLatch latch1 = new CountDownLatch(1);
final SimpleHttpRequest request2 = SimpleHttpRequest.get("http://httpbin.org/get");
httpclient.execute(request2, new FutureCallback<SimpleHttpResponse>() {

    @Override
    public void completed(final SimpleHttpResponse response2) {
        latch1.countDown();
        System.out.println(request2.getRequestUri() + "->" + response2.getCode());
    }

    @Override
    public void failed(final Exception ex) {
        latch1.countDown();
        System.out.println(request2.getRequestUri() + "->" + ex);
    }

    @Override
    public void cancelled() {
        latch1.countDown();
        System.out.println(request2.getRequestUri() + " cancelled");
    }

});
latch1.await();

// In real world one most likely would want also want to stream
// request and response body content
final CountDownLatch latch2 = new CountDownLatch(1);
AsyncRequestProducer producer3 = AsyncRequestBuilder.get("http://httpbin.org/get").build();
AbstractCharResponseConsumer<HttpResponse> consumer3 = new AbstractCharResponseConsumer<HttpResponse>() {

    HttpResponse response;

    @Override
    protected void start(final HttpResponse response, final ContentType contentType) throws HttpException, IOException {
        this.response = response;
    }

    @Override
    protected int capacity() {
        return Integer.MAX_VALUE;
    }

    @Override
    protected void data(final CharBuffer data, final boolean endOfStream) throws IOException {
        // Do something useful
    }

    @Override
    protected HttpResponse buildResult() throws IOException {
        return response;
    }

    @Override
    public HttpResponse getResult() {
        return response;
    }

    @Override
    public void releaseResources() {
    }

};
httpclient.execute(producer3, consumer3, new FutureCallback<HttpResponse>() {

    @Override
    public void completed(final HttpResponse response3) {
        latch2.countDown();
        System.out.println(request2.getRequestUri() + "->" + response3.getCode());
    }

    @Override
    public void failed(final Exception ex) {
        latch2.countDown();
        System.out.println(request2.getRequestUri() + "->" + ex);
    }

    @Override
    public void cancelled() {
        latch2.countDown();
        System.out.println(request2.getRequestUri() + " cancelled");
    }

});
latch2.await();
---
    
    Source can be downloaded 
    {{{./httpclient5/examples/org/apache/hc/client5/http/examples/AsyncQuickStart.java}here}}