[Httpcomponents Wiki] Update of "HttpEntity" by QuintinBeukes

[Apache Wiki <wi...@apache.org>]

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 QuintinBeukes:
http://wiki.apache.org/HttpComponents/HttpEntity

New page:
= HttpEntity =

The HttpEntity is an interface which represents the body of a request/response. 

== Description for HttpEntity ==
An entity that can be sent or received with an HTTP message. Entities can be found in some requests and in responses, where they are optional. Requests that use entities are POST/PUT, responses that don't use entities, are HEAD.

In some places, the JavaDoc distinguishes three kinds of entities, depending on where their content originates: 

a. streamed: The content is received from a stream, or generated on the fly. In particular, this category includes entities being received from a connection. Streamed entities are generally not repeatable. 
b. self-contained: The content is in memory or obtained by means that are independent from a connection or other entity. Self-contained entities are generally repeatable. 
c. wrapping: The content is obtained from another entity. 

This distinction is important for connection management with incoming entities. For entities that are created by an application and only sent using the HTTP components framework, the difference between streamed and self-contained is of little importance. In that case, it is suggested to consider non-repeatable entities as streamed, and those that are repeatable (without a huge effort) as self-contained.

== Using Response Entities ==
Since an entity can represent both binary and character content, it has support for character encodings (to support the latter, ie. character content).

The entity is created when the request was successful, and used to read the response.

To read the content from the entity, you can either retrieve the input stream via the !HttpEntity.getContent() method, which returns an InputStream, or you can supply an output stream to the !HttpEntity.writeTo(OutputStream) method, which will return once all content has been written to the given stream.

When the entity was received as a result of a response, the methods getContentType() and getContentLength() methods are for reading the common headers Content-Type and Content-Length respectively (if they are available). Since the Content-Type header can contain a character encoding for text mime-types like text/plain or text/html, the getContentEncoding() method is used to read this information. If the headers aren't available, a length of -1 will be returned, and NULL for the content-type. If the Content-Type header is available, a [Header] object will be returned.

When creating an entity for a request, this meta data has to be supplied by the creator of the entity.

Other headers from the response are read using the getHeaders() methods from the response object.

== EntityUtils ==
This is a utility class, that exposes 4 static methods to more easily read the content or information from an entity. Instead of reading the InputStream yourself, you can retrieve the whole content body in a String/byte array by using the methods from this class.

One of these static methods are for retrieving the content character set, where the other 3 are for reading the content itself.

|| byte[] toByteArray(HttpEntity) || Returns the content body in a byte[] ||;
|| String toString(HttpEntity) || Returns the content body in a String ||;
|| String toString(HttpEntity, String defaultCharset) || Returns the content body in a String, using the character set supplied as the second argument if the character set wasn't set upon creation. This will be the case if you didn't specify it when creating the Entity, or when the response didn't supply the character set in the response headers ||;

== Entities Content ==
=== Repeatable Entities ===
An entity can be repeatable, meaning it's content can be read more than once. 

-- more on this later --

=== Consuming Content ===
When you are finished with an entity that relies on an underlying input stream, it's important to execute the consumeContent() method, so as to clean up any available content on the stream so the connection be released to any connection pools. If you don't do this, other requests can't reuse this connection, since there are still available information on the buffer. 

Alernatively you can simple check the result of isStreaming(), and keep reading from the input stream until it returns false. 

Self contained entities will always return false with isStreaming(), as there is no underlying stream it depends on. For these entities consumeContent() will do nothing, and does not need to be called.

== Creating Entities ==
There are a few ways to create entities. You would want to do this when you implement custom responses, or send POST/PUT requests.

These classes include the following implementations provided by HttpComponents:
a. [#BasicHttpEntity]
b. [#BufferedHttpEntity]
c. [#ByteArrayEntity]
d. [#EntityTemplate]
e. [#FileEntity]
f. [#HttpEntityWrapper]
g. [#InputStreamEntity]
h. [#StringEntity]
i. [#AbstractHttpEntity] - For implementing custom entities

=== BasicHttpEntity === 
This is exactly as the name implies, a basic entity that represents an underlying stream. This is generally the entities received from HTTP responses.

This entity has an empty constructor. After constructor it represents no content, and has a negative content length.

You need to set the content stream, and optionally the length. You can do this with the setContent(java.io.InputStream) and setContentLength(long length) methods respectively.

=== BufferedHttpEntity ===
... To be completed ...

=== ByteArrayEntity ===
... To be completed ...

=== EntityTemplate ===
... To be completed ...

=== FileEntity ===
... To be completed ...

=== HttpEntityWrapper ===
... To be completed ...

=== InputStreamEntity ===
... To be completed ...

=== StringEntity ===
... To be completed ...

=== AbstractHttpEntity ===
... To be completed ...

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org