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 "HttpCoreTutorial" by OlegKalnichevski
Date Wed, 08 Oct 2008 18:10:20 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 OlegKalnichevski:
http://wiki.apache.org/HttpComponents/HttpCoreTutorial

------------------------------------------------------------------------------
  
  The content is sent in small chunks. Max entity length: unlimited.
  
+ The appropriate content stream class will be created automatically depending on properties
of the entity enclosed with the message.
+ 
  === 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.
@@ -805, +807 @@

  ioreactor.execute(eventDispatch);
  }}}
  
- There are several events methods of the !IOEventDispatch
+ Generic I/O events as defined by the !IOEventDispatch interface
  
   * connected: new session has been created
  
@@ -896, +898 @@

      
  == Non-blocking HTTP connections ==
  
- Effectively NHTTP connections are wrappers around !IOSession with HTTP specific functionality.
NHTTP connections are stateful and not threading safe. Input / output operations on NHTTP
connections should be restricted to the dispatch events triggered by the I/O event dispatch
thread. 
+ Effectively non-blocking HTTP connections are wrappers around !IOSession with HTTP specific
functionality. Non-blocking HTTP connections are stateful and not threading safe. Input /
output operations on non-blocking HTTP connections should be restricted to the dispatch events
triggered by the I/O event dispatch thread. 
  
  === Execution context of non-blocking HTTP connections ===
  
- NHTTP connections are not bound to a particular thread of execution and therefore they need
to maintain their own execution context. Each NHTTP connection has an !HttpContext instance
associated with it, which can be used to maintain a processing state. The !HttpContext instance
is threading safe and can be manipulated from multiple threads.
+ Non-blocking HTTP connections are not bound to a particular thread of execution and therefore
they need to maintain their own execution context. Each non-blocking HTTP connection has an
!HttpContext instance associated with it, which can be used to maintain a processing state.
The !HttpContext instance is threading safe and can be manipulated from multiple threads.
  
  {{{
- // Get NHTTP connection
+ // Get non-blocking HTTP connection
  DefaultNHttpClientConnection conn;
  // State
  Object myStateObject;
@@ -914, +916 @@

  
  === Interacting with non-blocking HTTP connections ===
  
- All NHTTP connections classes implement !IOControl interface, which represents a subset
of connection functionality for controlling interest in I/O even notifications. !IOControl
instances are expected to be fully threading safe. Therefore !IOControl can be used to request
/ suspend I/O event notifications from any thread. 
+ All non-blocking HTTP connections classes implement !IOControl interface, which represents
a subset of connection functionality for controlling interest in I/O even notifications. !IOControl
instances are expected to be fully threading safe. Therefore !IOControl can be used to request
/ suspend I/O event notifications from any thread. 
  
- One must take special precautions when interacting with NHTTP connections. Input / output
operations on a NHTTP connection may lead to unpredictable results if executed from any thread
other than the I/O event dispatch thread.   
+ One must take special precautions when interacting with non-blocking connections. Input
/ output operations on a non-blocking connection may lead to unpredictable results if executed
from any thread other than the I/O event dispatch thread.   
  
  The following pattern is recommended:
  
@@ -928, +930 @@

  
  Please note all operations that take place in the event methods should not block for too
long, because while the dispatch thread remains blocked in one session, it is unable to process
events for all other sessions. I/O operations with the underlying channel of the session are
not a problem as they are guaranteed to be non-blocking.  
  
- === Content codecs ===
+ === Non-blocking content transfer ===
  
-     ContentDecoder and ContentEncoder interfaces    
+ The process of content transfer for non-blocking connections works completely differently
compared to that of blocking connections, as non-blocking connections need to accommodate
to the asynchronous nature of the NIO model. The main distinction between two types of connections
is inability to use the usual, but inherently blocking !InputStream and !OutputStream classes
to represent streams of inbound and outbound content. HttpCore NIO provides !ContentEncoder
and !ContentDecoder interfaces to handle the process of asynchronous content transfer. Non-blocking
HTTP connections will instantiate the appropriate implementation of a content codec based
on properties of the entity enclosed with the message.   
+ 
+ Non-blocking HTTP connections will fire input events until the content entity is fully transferred.
+ 
+ {{{
+ //Obtain content decoder
+ ContentDecoder decoder;
+ //Read data in
+ ByteBuffer dst = ByteBuffer.allocate(2048); 
+ decoder.read(dst);
+ // Decode will be marked as complete when the content entity is fully transferred
+ if (decoder.isCompleted()) {
+     // Done
+ }
+ }}}
+ 
+ Non-blocking HTTP connections will fire output events until the content entity is marked
as fully transferred.
+ 
+ {{{
+ // Obtain content encoder
+ ContentEncoder encoder;
+ // Prepare output data 
+ ByteBuffer src = ByteBuffer.allocate(2048); 
+ // Write data out
+ encoder.write(src);
+ // Mark content entity as fully transferred when done
+ encoder.complete();
+ }}}
+ 
+ === Supported non-blocking content transfer mechanisms ===
+ 
+ Default implementations of the non-blocking HTTP connection interfaces support three content
transfer mechanisms defined by the HTTP/1.1 specification:
+ 
+  * Content-Length delimited
+ 
+ The end of the content entity is determined by the value of the !Content-Length header.
Maximum entity length: Long#MAX_VALUE.
+ 
+  * Identity coding
+ 
+ The end of the content entity is demarcated by closing the underlying connection (EOF condition).
For obvious reasons the identity encoding can only be used on the server side. Max entity
length: unlimited.
+     
+  * Chunk coding
+ 
+ The content is sent in small chunks. Max entity length: unlimited.
+ 
+ The appropriate content codec will be created automatically depending on properties of the
entity enclosed with the message.
+ 
+ === Direct channel I/O ===
+ 
+ Content codes are optimized to read data directly from or write data directly to the underlying
I/O session's channel, whenever possible avoiding intermediate buffering in a session buffer.
Moreover, those codecs that do not perform any content transformation such as !Content-Length
delimited and identity can leverage NIO !FileChannel methods for significantly improved performance
of file transfer operations both inbound and outbound.  
+ 
+ If the actual content decoder implements !FileContentDecoder one can make use of its methods
to read incoming content directly to a file bypassing an intermediate !ByteBuffer.
+ 
+ {{{
+ //Obtain content decoder
+ ContentDecoder decoder;
+ //Prepare file channel
+ FileChannel dst;
+ //Make use of direct file I/O if possible
+ if (decoder instanceof FileContentDecoder) {
+     long Bytesread = ((FileContentDecoder) decoder).transfer(dst, 0, 2048);
+      // Decode will be marked as complete when the content entity is fully transmitted
+      if (decoder.isCompleted()) {
+          // Done
-     
+      }
- === Direct transfer to and from file channels ===
+ }
+ }}}
  
-     FileContentDecoder and FileContentEncoder interfaces
+ If the actual content encoder implements !FileContentEncoder one can make use of its methods
to write outgoing content directly from a file bypassing an intermediate !ByteBuffer.
+ 
+ {{{
+ // Obtain content encoder
+ ContentEncoder encoder;
+ // Prepare file channel
+ FileChannel src;
+ // Make use of direct file I/O if possible
+ if (encoder instanceof FileContentEncoder) {
+     // Write data out
+     long bytesWritten = ((FileContentEncoder) encoder).transfer(src, 0, 2048); 
+     // Mark content entity as fully transferred when done
+     encoder.complete();
+ }
+ }}}
+ 
+ == HTTP I/O event dispatchers ==
+ 
+ HTTP I/O event dispatchers serve to convert generic I/O events triggered by an I/O reactor
to HTTP protocol specific events. They rely on !NHttpClientHandler and !NHttpServiceHandler
interfaces to propagate HTTP protocol events to a HTTP protocol handler.
+ 
+ Server side HTTP I/O events as defined by the !NHttpServiceHandler interface
+ 
+  * connected: triggered when a new incoming connection is created
+ 
+  * requestReceived: triggered when a new HTTP request is received. The connection passed
as a parameter to this method is guaranteed to return a valid HTTP request object. If the
request received encloses a request entity this method will be followed a series of inputReady
events to transfer the request content
+ 
+  * inputReady: triggered when the underlying channel is ready for reading a new portion
of the request entity through the corresponding content decoder. If the content consumer is
unable to process the incoming content, input event notifications can be temporarily suspended
using !IOControl interface.
+ 
+  * responseReady: triggered when the connection is ready to accept new HTTP response. The
protocol handler does not have to submit a response if it is not ready. 
+ 
+  * outputReady: triggered when the underlying channel is ready for writing a next portion
of the response entity through the corresponding content encoder. If the content producer
is unable to generate the outgoing content, output event notifications can be temporarily
suspended using !IOControl interface.
+ 
+  * exception: triggered when an I/O error occurrs while reading from or writing to the underlying
channel or when an HTTP protocol violation occurs while receiving an HTTP request.
+  
+  * timeout: triggered when no input is detected on this connection over the maximum period
of inactivity.
+ 
+  * closed: triggered when the connection is closed.
+ 
+ Client side HTTP I/O events as defined by the !NHttpClientHandler interface
+ 
+  * connected: triggered when a new outgoing connection is created. The attachment object
passed as a parameter to this event is an arbitrary object that was attached to the session
request.
+ 
+  * requestReady: triggered when the connection is ready to accept new HTTP request. The
protocol handler does not have to submit a request if it is not ready. 
+  
+  * outputReady: triggered when the underlying channel is ready for writing a next portion
of the request entity through the corresponding content encoder. If the content producer is
unable to generate the outgoing content, output event notifications can be temporarily suspended
using !IOControl interface.
+  
+  * responseReceived: triggered when an HTTP response is received. The connection passed
as a parameter to this method is guaranteed to return a valid HTTP response object. If the
response received encloses a response entity this method will be followed a series of inputReady
events to transfer the response content.
+ 
+  * inputReady: triggered when the underlying channel is ready for reading a new portion
of the response entity through the corresponding content decoder. If the content consumer
is unable to process the incoming content, input event notifications can be temorarily suspended
using !IOControl interface.
+ 
+  * exception: triggered when an I/O error occurrs while reading from or writing to the underlying
channel or when an HTTP protocol violation occurs while receiving an HTTP response.
+  
+  * timeout: triggered when no input is detected on this connection over the maximum period
of inactivity.
+ 
+  * closed: triggered when the connection is closed.
  
  == NHTTP entities ==
  

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


Mime
View raw message