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, 26 Nov 2008 18:39:48 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

------------------------------------------------------------------------------
  
  === Asynchronous HTTP service handler ===
  
- !AsyncNHttpServiceHandler is a fully asynchronous HTTP server side protocol handler that
implements the essential requirements of the HTTP protocol for the server side message processing
as described by RFC 2616. !AsyncNHttpServiceHandler is capable of processin HTTP requests
with nearly constant memory footprint. Only HTTP message heads are stored in memory, while
content of message bodies is streamed directly from the entity to the underlying channel (and
vice versa) using !ConsumingNHttpEntity and !ProducingNHttpEntity interfaces. 
+ !AsyncNHttpServiceHandler is a fully asynchronous HTTP server side protocol handler that
implements the essential requirements of the HTTP protocol for the server side message processing
as described by RFC 2616. !AsyncNHttpServiceHandler is capable of processing HTTP requests
with nearly constant memory footprint for individual HTTP connections. The handler stores
headers of HTTP messages in memory, while content of message bodies is streamed directly from
the entity to the underlying channel (and vice versa) using !ConsumingNHttpEntity and !ProducingNHttpEntity
interfaces. 
  
  When using this implementation, it is important to ensure that entities supplied for writing
implement !ProducingNHttpEntity. Doing so will allow the entity to be written out asynchronously.
If entities supplied for writing do not implement the !ProducingNHttpEntity interface, a delegate
is added that buffers the entire contents in memory. Additionally, the buffering might take
place in the I/O dispatch thread, which could cause I/O to block temporarily. For best results,
one must ensure that all entities set on !HttpResponses from !NHttpRequestHandlers implement
!ProducingNHttpEntity.
  
@@ -1547, +1547 @@

  
  === Asynchronous HTTP client handler ===
  
- !AsyncNHttpClientHandler is a fully asynchronous HTTP client side protocol handler that
implements the essential requirements of the HTTP protocol for the client side message processing
as described by RFC 2616. !AsyncNHttpClientHandler is capable of executing HTTP requests with
nearly constant memory footprint. Only HTTP message heads are stored in memory, while content
of message bodies is streamed directly from the entity to the underlying channel (and vice
versa) using !ConsumingNHttpEntity and !ProducingNHttpEntity interfaces. 
+ !AsyncNHttpClientHandler is a fully asynchronous HTTP client side protocol handler that
implements the essential requirements of the HTTP protocol for the client side message processing
as described by RFC 2616. !AsyncNHttpClientHandler is capable of executing HTTP requests with
nearly constant memory footprint for individual HTTP connections. The handler stores headers
of HTTP messages in memory, while content of message bodies is streamed directly from the
entity to the underlying channel (and vice versa) using !ConsumingNHttpEntity and !ProducingNHttpEntity
interfaces. 
  
  When using this implementation, it is important to ensure that entities supplied for writing
implement !ProducingNHttpEntity. Doing so will allow the entity to be written out asynchronously.
If entities supplied for writing do not implement the !ProducingNHttpEntity interface, a delegate
is added that buffers the entire contents in memory. Additionally, the buffering might take
place in the I/O dispatch thread, which could cause I/O to block temporarily. For best results,
one must ensure that all entities set on !HttpRequests from !NHttpRequestExecutionHandler
implement !ProducingNHttpEntity.
  
@@ -1629, +1629 @@

  };
  }}}
  
+ === Compatibility with blocking I/O ===
+ 
+ In addition to asynchronous protocol handlers described above !HttpCore ships two variants
of HTTP protocol handlers that emulate blocking I/O model on top of non-blocking one and allow
message content to be produced and consumed using standard !OutputStream / !InputStream API.
Compatibilty protocol handlers can work with HTTP request handlers and request executors that
rely on blocking !HttpEntity implementations.
+ 
+ Compatibility protocol handlers rely on !HttpProcessor to generate mandatory protocol headers
for all outgoing messages and apply common, cross-cutting message transformations to all all
incoming and outgoing messages, whereas individual HTTP request executors / HTTP request processors
are expected to take care of application specific content generation and processing.
+ 
- === Buffering protocol handlers ===
+ ==== Buffering protocol handlers ====
  
+ !BufferingHttpServiceHandler and !BufferingHttpClientHandler are protocol handler implementations
that provide compatibility with the blocking I/O by storing the full content of HTTP messages
in memory. Request / response processing callbacks fire only when the entire message content
has been read into a in-memory buffer. Please note that request execution / request processing
take place the main I/O thread and therefore individual HTTP request exeutors / request handlers
must ensure they do not block indefinitely. 
-     Protocol handler implementations that buffer the content of HTTP messages 
-     entirely in memory and executes HTTP requests on the main I/O thread
  
+ Buffering  protocol handler should be used only when dealing with HTTP messages that are
known to be limited in length.
+ 
- === Throttling protocol handlers ===
+ ==== Throttling protocol handlers ====
  
-     Protocol handler implementations that operate with a content buffer of 
-     a constant length allocated at the initialization time and throttle I/O 
-     event rate to ensure the buffer does not get overflown
+ !ThrottlingHttpServiceHandler and !ThrottlingHttpClientHandler are protocol handler implementations
that provide compatibility with the blocking I/O by utilizing shared content buffers and a
fairly small pool of worker threads. The throttling protocol handlers allocate input / output
buffers of a constant length upon initialization and control the rate of I/O events in order
to ensure those content buffers do not ever get overflown. This helps ensure nearly constant
memory footprint for HTTP connections and avoid the out of memory condition while streaming
content in and out. Request / response processing callbacks fire immediately when a message
is received. The throttling protocol handlers delegate the task of processing requests and
generating response content to an !Executor, which is expected to perform those tasks using
dedicated worker threads in order to avoid blocking the I/O thread.
+ 
+ Usually throttling protocol handlers need only a modest number of worker threads, much fewer
than the number of concurrent connections. If the length of the message is smaller or about
the size of the shared content buffer worker thread will just store content in the buffer
and terminate almost immediately without blocking. The I/O dispatch thread in its turn will
take care of sending out the buffered content asynchronously. The worker thread will have
to block only when processing large messages and the shared buffer fills up. It is generally
advisable to allocate shared buffers of a size of an average content body for optimal performance.
+ 
+ === Connection event listener ===
+ 
+ Protocol handlers like the rest of !HttpCore classes do not do logging in order to not impose
a choice of a logging framework onto the users. However one can add logging of the most important
connection events by injecting a !EventListener implementation into the protocol handler.
+ 
+ Connection events as defined by the !EventListener interface:
+ 
+  * fatalIOException: triggered when an I/O error caused a connection to be terminated.
+ 
+  * fatalProtocolException: triggered when an HTTP protocol error caused a connection to
be terminated.
+ 
+  * connectionOpen: triggered when a new connection has been established.
+ 
+  * connectionClosed: triggered when a connection has been terminated.
+ 
+  * connectionTimeout: triggered when a connection has timed out.
  
  == Non-blocking TLS/SSL ==
  
-     SSLIOSession, SSLServerIOEventDispatch, SSLClientIOEventDispatch classes
+ === SSL I/O session ===
  
- == Customization of the HTTP message parsing / formatting ==
+ !SSLIOSession is a decorator class intended to transparently extend any arbitrary !IOSession
with transport layer security capabilities based on the SSL/TLS protocol. Individual protocol
handlers should be able to work with SSL sessions without special preconditions or modifications.
However, I/O dispatchers need to take some additional actions to ensure correct functioning
of the transport layer encryption.
  
-     LineParser / LineFormatter interfaces
+  * When the underlying I/O session has been  created, the I/O dispatch must call !SSLIOSession#bind()
method in order to put the SSL session either into a client or a server mode.
+  
+  * When the underlying I/O session is input ready the I/O dispatcher should check whether
the SSL I/O session is ready produce input data by calling !SSLIOSession#isAppInputReady(),
pass control the protocol handler if it is, and finally call !SSLIOSession#inboundTransport()
method in order to do the necessary SSL handshaking and decrypt input data.
+ 
+  * When the underlying I/O session is output ready the I/O dispatcher should check whether
the SSL I/O session is ready to accept output data by calling !SSLIOSession#isAppOutputReady(),
pass control the protocol handler if it is, and finally call !SSLIOSession#outboundTransport()
method in order to do the nessary SSL handshaking and encrypt application data.
+ 
+ ==== SSL I/O session handler ====
+ 
+ Applications can customize various aspects of the TLS/SSl protocol by passing a custom implementation
of the !SSLIOSessionHandler interface.
+ 
+ SSL events as defined by the !SSLIOSessionHandler interface:
+ 
+  * initalize: triggered when the SSL connection is being initialized. The handler can use
this callback to customize properties of the !SSLEngine used to establish the SSL session.
+ 
+  * verify: triggered when the SSL connection has been established and intial SSL handshake
has been successfully completed. The handler can use this callback to verify properties of
the !SSLSession. For instance this would the right place to enforce SSL cipher strength, validate
certificate chain and do hostname checks.
+ 
+ {{{
+ // Get hold of new I/O session
+ IOSession iosession; 
+ 
+ // Initialize default SSL context
+ SSLContext sslcontext = SSLContext.getInstance("SSL");
+ sslcontext.init(null, null, null);
+ 
+ SSLIOSession sslsession = new SSLIOSession(iosession, sslcontext, new SSLIOSessionHandler()
{
+ 
+     public void initalize(SSLEngine sslengine, HttpParams params) throws SSLException {
+         // Ask clients to authenticate
+         sslengine.setWantClientAuth(true);
+         // Enforce strong ciphers 
+         sslengine.setEnabledCipherSuites(new String[] {
+                 "TLS_RSA_WITH_AES_256_CBC_SHA",
+                 "TLS_DHE_RSA_WITH_AES_256_CBC_SHA",
+                 "TLS_DHE_DSS_WITH_AES_256_CBC_SHA" });
-     
+     }
-     HeaderValueParser / HeaderValueFormatter interfaces
  
+     public void verify(SocketAddress remoteAddress, SSLSession session) throws SSLException
{
+         X509Certificate[] certs = session.getPeerCertificateChain();
+         // Examine peer certificate chain
+         for (X509Certificate cert: certs) {
+             System.out.println(cert.toString());
+         }
+     }
+     
+ }); 
+ }}}
+ 
+ === SSL I/O event dispatches ===
+ 
+ !HttpCore provides !SSLClientIOEventDispatch and !SSLServerIOEventDispatch I/O dispatch
implementations that can be used to SSL enable connections managed by any arbitrary I/O reactor.
The dispatches take all the necessary actions to wrap active I/O sessions with the SSL I/O
session decorator and ensure correct handling of the SSL protocol handshaking.
+ 

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


Mime
View raw message