hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Httpcomponents Wiki] Update of "HttpEntity" by QuintinBeukes
Date Mon, 16 Jun 2008 12:52:28 GMT
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


Mime
View raw message