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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
