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] Trivial Update of "HttpCoreTutorial" by SebastianBazley
Date Sat, 29 Nov 2008 23:33:11 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 SebastianBazley:
http://wiki.apache.org/HttpComponents/HttpCoreTutorial

The comment on the change is:
Fixed a few typos

------------------------------------------------------------------------------
  
  === Basic operations ===
  
- ==== HTTP request properties ====
+ ==== HTTP request message ====
  
  HTTP request is a message sent from the client to the server. The first line of that message
includes the method to be applied to the resource, the identifier of the resource, and the
protocol version in use.
  
@@ -55, +55 @@

  GET / HTTP/1.1
  }}}
  
- ==== HTTP response properties ====
+ ==== HTTP response message ====
  
  HTTP response is a message sent by the server back to the client after having received and
interpreted a request message. The first line of that message consists of the protocol version
followed by a numeric status code and its associated textual phrase.
  
@@ -166, +166 @@

  
  === 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 its content can be read more than once. This is only
possible with self contained entities (like !ByteArrayEntity or !StringEntity).
  
  === Using HTTP entities ===
  
@@ -178, +178 @@

  
  The !EntityUtils class exposes several static methods to more easily read the content or
information from an entity. Instead of reading the !InputStream directly, one can retrieve
the whole content body in a String/byte array by using the methods from this class.
  
- When the entity was received with an incoming message, the methods !HttpEntity#getContentType()
and !HttpEntity#getContentLength() methods can be used for reading the common metadata such
as Content-Type and Content-Length headers (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 !HttpEntity#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 the entity has been received with an incoming message, the methods !HttpEntity#getContentType()
and !HttpEntity#getContentLength() methods can be used for reading the common metadata such
as Content-Type and Content-Length headers (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 !HttpEntity#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 outgoing message, this meta data has to be supplied by the
creator of the entity.
  
@@ -226, +226 @@

  [[Anchor(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 is exactly as the name implies, a basic entity that represents an underlying stream.
This is generally used for the entities received from HTTP responses.
  
- This entity has an empty constructor. After constructor it represents no content, and has
a negative content length.
+ This entity has an empty constructor. After construction it represents no content, and has
a negative content length.
  
  One needs to set the content stream, and optionally the length. This can be done with the
!BasicHttpEntity#setContent(!InputStream) and !BasicHttpEntity#setContentLength(long) methods
respectively.
  
@@ -241, +241 @@

  [[Anchor(ByteArrayEntity)]]
  === ByteArrayEntity ===
  
- 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.
+ This is a simple self contained repeatable entity, which receives its content from a given
byte array. This byte array is supplied to the constructor.
  
  {{{
  String myData = "Hello world on the other side!!";
@@ -251, +251 @@

  [[Anchor(StringEntity)]]
  === StringEntity ===
  
- Very simple entity. It's is a self contained, repeatable entity that retrieves it's data
from a String object.
+ Very simple entity. It's is a self contained, repeatable entity that retrieves its data
from a String object.
  
- It has 2 constructors, one simply constructs with a given String object where the other
also takes a character encoding for the data in the String.
+ It has 2 constructors, one simply constructs with a given String object; the other also
takes a character encoding for the data in the String.
  
  {{{
  StringBuffer sb = new StringBuffer();
@@ -272, +272 @@

  [[Anchor(EntityTemplate)]]
  === EntityTemplate ===
  
- 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, one is expected to supply a reference to a content producer,
which effectively creates a repeatable entity.
+ This is an entity which receives its 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, one is expected to supply a reference to a content producer,
which effectively creates a repeatable entity.
  
  There are no standard !ContentProducers in !HttpCore. It's basically just a convenience
interface to allow wrapping up complex logic into an entity. To use this entity one needs
to create a class that implements !ContentProducer and override the !ContentProducer#writeTo(!OutputStream)
method. Then, an instance of custom !ContentProducer will be used to write the full content
body to the output stream. For instance, an HTTP server would serve static files with the
!FileEntity, but running CGI programs could be done with a !ContentProducer, inside which
one could implement custom logic to supply the content as it becomes available. This way one
doesn't need to buffer it in a string and then use a !StringEntity or !ByteArrayEntity.
  
@@ -298, +298 @@

  [[Anchor(FileEntity)]]
  === FileEntity ===
  
- This entity reads it's content body from a file. Since this is mostly used to stream large
files of different types, one needs to supply the content type of the file, for instance,
sending a zip one would supply the content type "application/zip", for XML "application/xml".
+ This entity reads its content body from a file. Since this is mostly used to stream large
files of different types, one needs to supply the content type of the file, for instance,
sending a zip one would supply the content type "application/zip", for XML "application/xml".
  
  {{{File staticFile = new File("/path/to/myapp.jar");
  HttpEntity entity = new FileEntity(staticFile, "application/java-archive");
@@ -307, +307 @@

  [[Anchor(InputStreamEntity)]]
  === InputStreamEntity ===
  
- An entity that reads it's content from an input stream. It is constructed by supplied the
input stream as well as the content length.
+ An entity that reads its content from an input stream. It is constructed by supplying the
input stream and the content length.
  
  The content length is used to limit the amount of data read from the !InputStream. If the
length matches the content length available on the input stream, then all data will be sent.
Alternatively a negative content length will read all data from the input stream, which is
the same as supplying the exact content length, so the length is most often used to limit
the length.
  
@@ -342, +342 @@

  
  HTTP connections are responsible for HTTP message serialization and deserialization. One
should rarely need to use HTTP connection objects directly. There are higher level protocol
components intended for execution and processing of HTTP requests. However, in some cases
direct interaction with HTTP connections may be necessary, for instance, to access properties
such as the connection status, the socket timeout or the local and remote addresses.
  
- It is important to bear in mind that HTTP connections are not threading safe. It is strongly
recommended to limit all interactions with HTTP connection objects to one thread. The only
method of !HttpConnection interface and its sub-interfaces, which is safe to invoke from another
thread, is !HttpConnection#shutdown().
+ It is important to bear in mind that HTTP connections are not thread-safe. It is strongly
recommended to limit all interactions with HTTP connection objects to one thread. The only
method of !HttpConnection interface and its sub-interfaces, which is safe to invoke from another
thread, is !HttpConnection#shutdown().
  
  === Working with blocking HTTP connections ===
  
@@ -362, +362 @@

  metrics.getSentBytesCount();
  }}}
  
- HTTP connection interfaces, both client and server, send and receive messages in two stages.
Message head is transmitted first. Depending on properties of the message head it may be followed
by a message body. Please note it is very important to call !HttpEntity#consumeContent() to
signal that the processing of the message is complete. HTTP entities that stream out their
content directly from the input stream of the underlying connection must ensure the content
of the message body is fully consumed for that connection to be potentially re-usable.
+ HTTP connection interfaces, both client and server, send and receive messages in two stages.
The message head is transmitted first. Depending on properties of the message head it may
be followed by a message body. Please note it is very important to call !HttpEntity#consumeContent()
to signal that the processing of the message is complete. HTTP entities that stream out their
content directly from the input stream of the underlying connection must ensure the content
of the message body is fully consumed for that connection to be potentially re-usable.
  
  Over-simplified process of client side request execution may look like that:
  
@@ -412, +412 @@

  
  === Content transfer ===
  
- HTTP connections manage the process of the content transfer using the functionality!HttpEntity
interface. HTTP connections generate an entity object that encapsulates the content stream
of the incoming message. Please note that !HttpServerConnection#receiveRequestEntity() and
!HttpClientConnection#receiveResponseEntity() do not retrieve or buffer any incoming data.
They merely inject an appropriate content codec based on the properties of the incoming message.
The content can be retrieved by reading from the content input stream of the enclosed entity
using !HttpEntity#getContent(). The incoming data will be decoded automatically completely
transparently for the data consumer. Likewise, HTTP connections rely on !HttpEntity#writeTo(!OutputStream)
method to generate the content of an outgoing message. if an outgoing messages encloses an
entity, the content will be encoded automatically based on the properties of the message.
+ HTTP connections manage the process of the content transfer using the !HttpEntity interface.
HTTP connections generate an entity object that encapsulates the content stream of the incoming
message. Please note that !HttpServerConnection#receiveRequestEntity() and !HttpClientConnection#receiveResponseEntity()
do not retrieve or buffer any incoming data. They merely inject an appropriate content codec
based on the properties of the incoming message. The content can be retrieved by reading from
the content input stream of the enclosed entity using !HttpEntity#getContent(). The incoming
data will be decoded automatically completely transparently for the data consumer. Likewise,
HTTP connections rely on !HttpEntity#writeTo(!OutputStream) method to generate the content
of an outgoing message. if an outgoing messages encloses an entity, the content will be encoded
automatically based on the properties of the message.
  
  === Supported content transfer mechanisms ===
  
@@ -434, +434 @@

  
  === Terminating HTTP connections ===
  
- HTTP connections can be terminated either gracefully by calling !HttpConnection#close()
or forcibly by calling !HttpConnection#shutdown(). The former tries to flush all buffered
data prior to terminating the connection and may block indefinitely. The !HttpConnection#close()
method is not threading safe. The latter terminates the connection without flushing internal
buffers and returns control to the caller as soon as possible without blocking for long. The
!HttpConnection#shutdown() method is expected to be threading safe.
+ HTTP connections can be terminated either gracefully by calling !HttpConnection#close()
or forcibly by calling !HttpConnection#shutdown(). The former tries to flush all buffered
data prior to terminating the connection and may block indefinitely. The !HttpConnection#close()
method is not thread-safe. The latter terminates the connection without flushing internal
buffers and returns control to the caller as soon as possible without blocking for long. The
!HttpConnection#shutdown() method is expected to be thread-safe.
  
  == HTTP exception handling ==
  
- All !HttpCore components throw two types of exceptions: !IOException in case of an I/O failure
such as socket timeout or an socket reset and !HttpException that signals an HTTP failure
such as a violation of the HTTP protocol. Usually I/O errors are considered non-fatal and
recoverable, whereas HTTP protocol errors are considered fatal and cannot be automatically
recovered from. 
+ All !HttpCore components potentially throw two types of exceptions: !IOException in case
of an I/O failure such as socket timeout or an socket reset and !HttpException that signals
an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are considered
non-fatal and recoverable, whereas HTTP protocol errors are considered fatal and cannot be
automatically recovered from. 
  
  === Protocol exception ===
  
@@ -450, +450 @@

  
  HTTP protocol processor is a collection of protocol interceptors that implements the 'Chain
of Responsibility' pattern, where each individual protocol interceptor is expected to work
on a particular aspect of the HTTP protocol the interceptor is responsible for. 
  
- Protocol interceptors must be implemented threading safe. Similarly to servlets, protocol
interceptors should not use instance variables unless access to those variables is synchronized.
+ Protocol interceptors must be implemented as thread-safe. Similarly to servlets, protocol
interceptors should not use instance variables unless access to those variables is synchronized.
  
  === Standard protocol interceptors ===
  
@@ -523, +523 @@

  
  === HTTP context ===
  
- Protocol interceptors can collaborate by sharing information such as a processing state
through an HTTP execution context. HTTP context is a structure that can be used to map an
attribute name to an attribute value. Internally HTTP context implementations are usually
backed by a HashMap. The primary purpose of the HTTP context is to facilitate information
sharing among various logically related components. HTTP context can be used to store a processing
state for one message or several consecutive messages. Multiple logically related messages
can participate in a logical session if the same context is reused between consecutive messages.
+ Protocol interceptors can collaborate by sharing information - such as a processing state
- through an HTTP execution context. HTTP context is a structure that can be used to map an
attribute name to an attribute value. Internally HTTP context implementations are usually
backed by a HashMap. The primary purpose of the HTTP context is to facilitate information
sharing among various logically related components. HTTP context can be used to store a processing
state for one message or several consecutive messages. Multiple logically related messages
can participate in a logical session if the same context is reused between consecutive messages.
  
  {{{
  BasicHttpProcessor httpproc = new BasicHttpProcessor();
@@ -606, +606 @@

  
  === HTTP parameter beans ===
  
- !HttpParams interface allows for a great deal of flexibility in handling configuration of
components. Most importantly, new parameters can be introduced without affecting binary compatibility
with older versions. However, !HttpParams also has a certain disadvantage compared to regular
java beans: !HttpParams cannot be assembled using a DI framework. To mitigate the limitation,
!HttpCore includes a number of bean classes that cab used in order to initialize !HttpParams
objects using standard java bean conventions. 
+ !HttpParams interface allows for a great deal of flexibility in handling configuration of
components. Most importantly, new parameters can be introduced without affecting binary compatibility
with older versions. However, !HttpParams also has a certain disadvantage compared to regular
Java beans: !HttpParams cannot be assembled using a DI framework. To mitigate the limitation,
!HttpCore includes a number of bean classes that can used in order to initialize !HttpParams
objects using standard Java bean conventions. 
  
  {{{
  HttpParams params = new BasicHttpParams();
@@ -745, +745 @@

  
  === Connection persistence / re-use ===
  
- !ConnectionReuseStrategy interface is intended to determine whether the underlying connection
can be reused for processing of consecutive messages after the transmission of the current
one has been completed. The default connection re-use strategy attempts to keep connection
alive whenever possible. Firstly, it examines the version of the HTTP protocol used to transmit
the message. HTTP/1.1 connections are persistent per default, HTTP/1.0 are not. Secondly,
it examines the value of the !Connection header. The peer can indicate whether it intends
to re-use the connection on the opposite side by sending !Keep-Alive or !Close values in the
!Connection header. Thirdly, the strategy makes the decision whether the connection is safe
to re-use based on the properties of the enclosed entity, if available.  
+ The !ConnectionReuseStrategy interface is intended to determine whether the underlying connection
can be re-used for processing of further messages after the transmission of the current one
has been completed. The default connection re-use strategy attempts to keep connection alive
whenever possible. Firstly, it examines the version of the HTTP protocol used to transmit
the message. HTTP/1.1 connections are persistent per default, HTTP/1.0 are not. Secondly,
it examines the value of the !Connection header. The peer can indicate whether it intends
to re-use the connection on the opposite side by sending !Keep-Alive or !Close values in the
!Connection header. Thirdly, the strategy makes the decision whether the connection is safe
to re-use based on the properties of the enclosed entity, if available.  
      
  = NIO extensions =
   
@@ -753, +753 @@

  
  Contrary to the popular belief, the performance of NIO in terms of raw data throughput is
significantly lower than than of the blocking I/O. NIO does not necessarily fit all use cases
and should be used only where appropriate: 
      
-  * handling of thousands of connections, significant number of which can be idle 
+  * handling of thousands of connections, a significant number of which can be idle 
  
   * handling high latency connections
      
@@ -761, +761 @@

  
  == Differences from other NIO frameworks ==
  
- Solves similar problems as other frameworks, but has certain distinct features
+ Solves similar problems as other frameworks, but has certain distinct features:
      
   * minimalistic, optimized for data volume intensive protocols such as HTTP
  
@@ -773, +773 @@

  
  !HttpCore NIO is based on the Reactor pattern as described by Doug Lea. The purpose of I/O
reactors is to react to I/O events and to dispatch event notifications to individual I/O sessions.
The main idea of I/O reactor pattern is to break away from one thread per connection model
imposed by the classic blocking I/O model. !IOReactor interface represents an abstract object
implementing the Reactor pattern. Internally, !IOReactor implementations encapsulate functionality
of the NIO !Selector.
  
- I/O reactors usually employ a small number of worker threads (often as few as one) to dispatch
I/O event notifications to a much greater number (often as many as several thousands) of I/O
sessions or connections. It is generally recommended to have one dispatch thread per CPU core.
+ I/O reactors usually employ a small number of dispatch threads (often as few as one) to
dispatch I/O event notifications to a much greater number (often as many as several thousands)
of I/O sessions or connections. It is generally recommended to have one dispatch thread per
CPU core.
  
  {{{
  HttpParams params = new BasicHttpParams();
@@ -783, +783 @@

  
  === I/O dispatchers ===
  
- !IOReactor implementations make use of the !IOEventDispatch interface to notify of events
pending for a particular session. All methods of the !IOEventDispatch are executed on a dispatch
thread of the I/O reactor. Therefore, it is important that processing that takes place in
the event methods will not block the dispatch thread for too long, as the I/O reactor will
be unable to react to other events. 
+ !IOReactor implementations make use of the !IOEventDispatch interface to notify clients
of events pending for a particular session. All methods of the !IOEventDispatch are executed
on a dispatch thread of the I/O reactor. Therefore, it is important that processing that takes
place in the event methods will not block the dispatch thread for too long, as the I/O reactor
will be unable to react to other events. 
  
  {{{
  HttpParams params = new BasicHttpParams();
@@ -810, +810 @@

  The shutdown of I/O reactors is a complex process and may usually take a while to complete.
I/O reactors will attempt to gracefully terminate all active I/O sessions and dispatch threads
approximately within the specified grace period. If any of the I/O sessions fails to terminate
correctly, the I/O reactor will forcibly shut down remaining sessions.    
  
  {{{
- int gracePeriod = 3000; // milliseconds
+ long gracePeriod = 3000L; // milliseconds
  ioreactor.shutdown(gracePeriod);
  }}}
  
@@ -838, +838 @@

  Object currentState = iosession.getAttribute("state");
  }}}
  
- Please note if several sessions make use of shared objects, access to those objects must
be synchronized or threading safe. 
+ Please note if several sessions make use of shared objects, access to those objects must
be thread-safe. 
  
  === I/O session event mask ===
  
@@ -891, +891 @@

  ep3.waitFor();
  }}}
  
- Once an enpoint is fully intialized it starts accepting incoming connections and propagate
I/O activity notifications to the !IOEventDispatch instance.
+ Once an endpoint is fully intialized it starts accepting incoming connections and propagates
I/O activity notifications to the !IOEventDispatch instance.
      
  One can obtain a set of registered endpoints at runtime, query the status of an endpoint
at runtime, and close it if desired.
      
@@ -1028, +1028 @@

  });
  }}}
  
- One ought to be very careful about discarding exceptions indiscriminately. It is often much
better to let the I/O reactor shut down itself cleanly and restart it rather than leaving
it in an inconsistent or unstable state.
+ One needs to be very careful about discarding exceptions indiscriminately. It is often much
better to let the I/O reactor shut down itself cleanly and restart it rather than leaving
it in an inconsistent or unstable state.
  
  === I/O reactor audit log ===
  
@@ -1384, +1384 @@

  [[Anchor(NByteArrayEntity)]]
  === NByteArrayEntity ===
  
- 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.
+ This is a simple self contained repeatable entity, which receives its content from a given
byte array. This byte array is supplied to the constructor.
  
  {{{
  String myData = "Hello world on the other side!!";
@@ -1394, +1394 @@

  [[Anchor(NStringEntity)]]
  === NStringEntity ===
  
- It's is a simple, self contained, repeatable entity that retrieves it's data from a String
object.
+ It's is a simple, self contained, repeatable entity that retrieves its data from a String
object.
  
  It has 2 constructors, one simply constructs with a given String object where the other
also takes a character encoding for the data in the String.
  
@@ -1409, +1409 @@

  [[Anchor(NFileEntity)]]
  === NFileEntity ===
  
- This entity reads it's content body from a file. This class is mostly used to stream large
files of different types, so one needs to supply the content type of the file to make sure
the content can be correctly recognized and processed by the recipient.
+ This entity reads its content body from a file. This class is mostly used to stream large
files of different types, so one needs to supply the content type of the file to make sure
the content can be correctly recognized and processed by the recipient.
  
  {{{File staticFile = new File("/path/to/myapp.jar");
  NHttpEntity entity = new NFileEntity(staticFile, "application/java-archive");

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


Mime
View raw message