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 13:26:17 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

------------------------------------------------------------------------------
+ #format wiki
  = HttpEntity =
+ 
+ ----
+ [[TableOfContents]]
+ ----
  
  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: 
+ In some places, the [http://hc.apache.org/httpcomponents-core/httpcore/apidocs/index.html
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. 
@@ -33, +38 @@

  
  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[] ||;
+ ||<style="white-space:nowrap">byte[] toByteArray(HttpEntity)||Returns the content
body in a byte[]||
- || String toString(HttpEntity) || Returns the content body in a String ||;
+ ||<style="white-space:nowrap">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 ||;
+ ||<style="white-space:nowrap">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. This is only
possible with self contained entities (like ByteArrayEntity or StringEntity).
- 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. 
@@ -54, +57 @@

  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
+   a. [#BasicHttpEntity BasicHttpEntity]
+   a. [#BufferedHttpEntity BufferedHttpEntity]
+   a. [#ByteArrayEntity ByteArrayEntity]
+   a. [#EntityTemplate EntityTemplate]
+   a. [#FileEntity FileEntity]
+   a. [#HttpEntityWrapper HttpEntityWrapper]
+   a. [#InputStreamEntity InputStreamEntity]
+   a. [#StringEntity StringEntity]
+   a. [#AbstractHttpEntity AbstractHttpEntity]
  
+ [[Anchor(BasicHttpEntity)]]
- === BasicHttpEntity === 
+ === 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.
+ 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.
  
+ Example:
+ {{{#!java numbers=off
+   BasicHttpEntity myEntity = new BasicHttpEntity();
+   myEntity.setContent(someInputStream);
+   myEntity.setContentLength(340); // sets the length to 340
+ }}}
+ 
+ [[Anchor(BufferedHttpEntity)]]
  === BufferedHttpEntity ===
- ... To be completed ...
+ This is an entity wrapper. It is constructed by supplying another entity. It reads the content
from the supplied entity, and buffers it in memory.
  
+ This allows you to make a repeatable entity, from a non-repeatable entity. If the supplied
entity is already repeated, calls are simply passed through to the underlying entity.
+ 
+ {{{#!java numbers=off
+   BufferedHttpEntity myEntity = new BufferedHttpEntity(myNonRepeatableEntity);
+ }}}
+ 
+ [[Anchor(ByteArrayEntity)]]
  === ByteArrayEntity ===
- ... To be completed ...
+ This is a simple self contained repeatable entity, which receives it's content from a given
byte array. This byte array is supplied to the constructor.
  
+ {{{#!java numbers=off
+   String myData = "Hello world on the other side!!";
+   ByteArrayEntity myEntity = new ByteArrayEntity(myData.getBytes());
+ }}}
+ 
+ [[Anchor(EntityTemplate)]]
  === EntityTemplate ===
- ... To be completed ...
+ This is an entity which receives it's content from a !ContentProducer. 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 creating a !EntityTemplate, you supply a reference to a content producer, which effectively
creates a repeatable entity.
  
+ There are no standard !ContentProducers in HttpComponents. To use this entity you will need
to extend !ContentProducer and override the writeTo(OutputStream) method. Inside this method
you will write the full content body to the output stream.
+ 
+ [[Anchor(FileEntity)]]
  === FileEntity ===
  ... To be completed ...
  
+ [[Anchor(HttpEntityWrapper)]]
  === HttpEntityWrapper ===
  ... To be completed ...
  
+ [[Anchor(InputStreamEntity)]]
  === InputStreamEntity ===
  ... To be completed ...
  
+ [[Anchor(StringEntity)]]
  === StringEntity ===
  ... To be completed ...
  
+ [[Anchor(AbstractHttpEntity)]]
  === 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