Dear Wiki user, You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.
The following page has been changed by OlegKalnichevski: http://wiki.apache.org/HttpComponents/HttpClientTutorial ------------------------------------------------------------------------------ === Ensuring release of low level resources === - When finished with a response entity, it's important to execute the HttpEntity#consumeContent() method, so as to consume any available content on the stream, so the connection could be released to the connection pool and re-used by the connection manager for subsequent requests. + When finished with a response entity, it's important to ensure that all entity content has been fully consumed. The easiers way to do so is to call the HttpEntity#consumeContent() method to consume any available content on the stream, so the connection could be safely released to the connection pool and re-used by the connection manager for subsequent requests. There can be situations, however, when only a small portion of the entire response content needs to be retrieved and the performance penalty for consuming the remaining content and making the connection reusable is too high, one can simply terminate the request by calling HttpUriRequest#abort() method. @@ -297, +297 @@ === Producing entity content === + HttpClient provides several classes that can be used to efficiently stream out content though HTTP connections. Instances of those classes can be associated with entity enclosing requests such as POST and PUT in order to enclose entity content into outgoing HTTP requests. HttpClient provides several classes for most common data containers such as string, byte array, input stream, and file: StringEntity, ByteArrayEntity, InputStreamEntity, and FileEntity. + + {{{ + File file = new File("somefile.txt"); + FileEntity entity = new FileEntity(file, "text/plain; charset=\"UTF-8\""); + + HttpPost httppost = new HttpPost("http://localhost/action.do";); + httppost.setEntity(entity); + }}} + + Please note InputStreamEntity is not repeatable, because it can only read from the underlying data stream once. Generally it is recommended to implement a custom HttpEntity class which is self-contained instead of using generic InputStreamEntity. FileEntity can be a good starting point. + + ==== Dynamic content entities ==== + + Often HTTP entities need to be generated dynamically based a particular execution context. HttpClient provides support for dynamic entities by using EntityTemplate entity class and ContentProducer interface. Content producers are objects which produce their content on demand, by writing it out to an output stream. They are expected to be able produce their content every time they are requested to do so. So entities created with EntityTemplate are generally self-contained and repeatable. + + {{{ + ContentProducer cp = new ContentProducer() { + public void writeTo(OutputStream outstream) throws IOException { + Writer writer = new OutputStreamWriter(outstream, "UTF-8"); + writer.write("<response>"); + writer.write("<content>"); + writer.write("important stuff"); + writer.write("<c/ontent>"); + writer.write("</response>"); + writer.flush(); + } + }; + HttpEntity entity = new EntityTemplate(cp); + HttpPost httppost = new HttpPost("http://localhost/handler.do";); + httppost.setEntity(entity); + }}} + + ==== HTML forms ==== + + Many applications frequently need to simulate the process of submitting an HTML form, for instance, in order to log in to a web application or submit input data. HttpClient provides special entity class UrlEncodedFormEntity to facilitate the process. + + {{{ + List<NameValuePair> formparams = new ArrayList<NameValuePair>(); + formparams.add(new BasicNameValuePair("param1", "value1")); + formparams.add(new BasicNameValuePair("param2", "value2")); + UrlEncodedFormEntity entity = new UrlEncodedFormEntity(formparams, "UTF-8"); + HttpPost httppost = new HttpPost("http://localhost/handler.do";); + httppost.setEntity(entity); + }}} + + This UrlEncodedFormEntity instance will use the so called URL encoding to encode parameters and produce the following content: + + {{{ + param1=value1¶m2=value2 + }}} + ==== Content chunking ==== + Generally it is recommended to let HttpClient choose the most appropriate transfer encoding based on the properties of the HTTP message being transferred. It is possible, however, to inform HttpClient that the chunk coding is preferred by setting HttpEntity#setChunked() to true. Please note that HttpClient will use this flag as a hint only. This value well be ignored when using HTTP protocol versions that do not support chunk coding, such as HTTP/1.0. + + {{{ + StringEntity entity = new StringEntity("important message", "text/plain; charset=\"UTF-8\""); + entity.setChunked(true); + HttpPost httppost = new HttpPost("http://localhost/acrtion.do";); + httppost.setEntity(entity); + }}} + === Response handlers === - The simplest and the most convenient way to handle responses. + The simplest and the most convenient way to handle responses is by using ResponseHandler interface. This method completely relieves the user from having to worry about connection management. When using a ResponseHandler HttpClient will automatically take care of ensuring release of the connection back to the connection manager regardless whether the request execution succeeds or causes an exception. + + {{{ + HttpClient httpclient = new DefaultHttpClient(); + HttpGet httpget = new HttpGet("http://localhost/";); + + ResponseHandler<byte[]> handler = new ResponseHandler<byte[]>() { + public byte[] handleResponse( + HttpResponse response) throws ClientProtocolException,IOException { + HttpEntity entity = response.getEntity(); + if (entity != null) { + return EntityUtils.toByteArray(entity); + } else { + return null; + } + } + }; + + byte[] response = httpclient.execute(httpget, handler); + }}} === Exception handling === --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
