| ~~ ==================================================================== |
| ~~ 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 remainingCapacity() { |
| return Integer.MAX_VALUE; |
| } |
| |
| @Override |
| protected int capacityIncrement() { |
| 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}} |
| |
| |