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 AsankhaPerera: http://wiki.apache.org/HttpComponents/HttpCoreTutorial The comment on the change is: minor corrections - no changes to the primary content of the tutorial ------------------------------------------------------------------------------ = Goals = * Implementation of the most fundamental HTTP transport aspects - * Balance between good performance and clarify and expressiveness of API + * Balance between good performance and the clarity & expressiveness of API * Small (predictable) memory footprint * Self contained library (no external dependencies beyond JRE) @@ -30, +30 @@ A HTTP message consists of a head and an optional body. The message head of an HTTP request consists of a request line and a collection of header fields. The message head of an HTTP response consists of a status line and a collection of header fields. All HTTP messages must include the protocol version. Some HTTP messages can optionally enclose a content body. - !HttpCore defines HTTP message object model that closely follows the definition and provides an extensive support for serialization (formatting) and deserialization (parsing) of HTTP message elements. + !HttpCore defines the HTTP message object model that closely follows the definition and provides an extensive support for serialization (formatting) and deserialization (parsing) of HTTP message elements. === Basic operations === @@ -150, +150 @@ domain=localhost }}} - HTTP headers get tokenized into individual header elements on demand only. HTTP headers received over an HTTP connection are stored internally as an array of chars and parsed lazily only when their properties are accessed. + HTTP headers get tokenized into individual header elements only on demand. HTTP headers received over an HTTP connection are stored internally as an array of chars and parsed lazily only when their properties are accessed. == HTTP entity == - HTTP messages can carry a content entity associated with the request or response. Entities can be found in some requests and in some responses, where they are optional. Requests that use entities are referred to as entity enclosing requests. The HTTP specification defines two entity enclosing methods: POST and PUT. Responses are usually expected to enclose a content entity. There are exceptions to this rule such as responses to HEAD method and 204 No Content, 304 Not Modified, 205 Reset Content responses. + HTTP messages can carry a content entity associated with the request or response. Entities can be found in some requests and in some responses, as they are optional. Requests that use entities are referred to as entity enclosing requests. The HTTP specification defines two entity enclosing methods: POST and PUT. Responses are usually expected to enclose a content entity. There are exceptions to this rule such as responses to HEAD method and 204 No Content, 304 Not Modified, 205 Reset Content responses. !HttpCore distinguishes three kinds of entities, depending on where their content originates: @@ -298, +298 @@ [[Anchor(FileEntity)]] === FileEntity === - 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". + 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 file would require 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"); @@ -346, +346 @@ === Working with blocking HTTP connections === - !HttpCore does not provide full support for opening connections because the process of eatablishing a new connection especially on the client side can be very complex involving one or several authenticating or/and tunneling proxies. Instead, HTTP connection objects can be bound to an arbitrary network socket. + !HttpCore does not provide full support for opening connections because the process of establishing a new connection especially on the client side can be very complex involving one or several authenticating or/and tunneling proxies. Instead, HTTP connection objects can be bound to an arbitrary network socket. {{{ Socket socket = new Socket(); @@ -364, +364 @@ 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: + Over-simplified process of client side request execution may look like this: {{{ Socket socket = new Socket(); @@ -384, +384 @@ } }}} - Over-simplified process of server side request handling may look like that: + Over-simplified process of server side request handling may look like this: {{{ Socket socket = new Socket(); @@ -635, +635 @@ !HttpService is a server side HTTP protocol handler based in the blocking I/O model that implements the essential requirements of the HTTP protocol for the server side message processing as described by RFC 2616. - !HttpService relies 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 HTTP request executor is expected to take care of application specific content generation and processing. + !HttpService relies on !HttpProcessor to generate mandatory protocol headers for all outgoing messages and apply common, cross-cutting message transformations to all incoming and outgoing messages, whereas HTTP request executor is expected to take care of application specific content generation and processing. {{{ HttpParams params; @@ -652, +652 @@ ==== HTTP request handlers ==== - !HttpRequestHandler interface represents a routine for processing of a specific group of HTTP requests. !HttpService is designed to take care of protocol specific aspects, whereas individual request handlers are expected to take care of application specific HTTP processing. The main purpose of a request handler is to generate a response object with a content entity to be send back to the client in response to the given request. + !HttpRequestHandler interface represents a routine for processing of a specific group of HTTP requests. !HttpService is designed to take care of protocol specific aspects, whereas individual request handlers are expected to take care of application specific HTTP processing. The main purpose of a request handler is to generate a response object with a content entity to be sent back to the client in response to the given request. {{{ HttpRequestHandler myRequestHandler = new HttpRequestHandler() { @@ -669, +669 @@ }; }}} - Request handlers must be implemented threading safe. Similarly to servlets, request handlers should not use instance variables unless access to those variables is synchronized. + Request handlers must be implemented in a thread safe manner. Similarly to servlets, request handlers should not use instance variables unless access to those variables are synchronized. ==== Request handler resolver ==== @@ -692, +692 @@ ==== Using HTTP service to handle requests ==== - When fully initialized and configured !HttpService can be used to execute handle requests for active HTTP connections. !HttpService#!handleRequest() method reads an incoming requests, generates a response and sends it back to the client. This method can be executed in a loop to handle multiple requests on a persistent connection. The !HttpService#!handleRequest() is safe to execute from multiple threads to process requests on several connections simultaneously as long as protocol interceptors and requests handlers used by the !HttpService are threading safe. + When fully initialized and configured, the !HttpService can be used to execute and handle requests for active HTTP connections. !HttpService#!handleRequest() method reads an incoming request, generates a response and sends it back to the client. This method can be executed in a loop to handle multiple requests on a persistent connection. The !HttpService#!handleRequest() is safe to execute from multiple threads to process requests on several connections simultaneously as long as protocol interceptors and requests handlers used by the !HttpService are thread safe. {{{ HttpService httpService; @@ -741, +741 @@ } }}} - Methods of !HttpRequestExecutor are safe to execute from multiple threads to execute requests on several connections simultaneously as long as protocol interceptors used by the !HttpRequestExecutor are threading safe. + Methods of !HttpRequestExecutor are safe to execute from multiple threads to execute requests on several connections simultaneously as long as protocol interceptors used by the !HttpRequestExecutor are thread safe. === Connection persistence / re-use === - 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. + 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 message has been completed. The default connection re-use strategy attempts to keep connections alive whenever possible. Firstly, it examines the version of the HTTP protocol used to transmit the message. HTTP/1.1 connections are persistent by default, while HTTP/1.0 connections 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 = @@ -771, +771 @@ == I/O reactor == - !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. + !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 the 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 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. @@ -838, +838 @@ Object currentState = iosession.getAttribute("state"); }}} - Please note if several sessions make use of shared objects, access to those objects must be thread-safe. + Please note that if several sessions make use of shared objects, access to those objects must be made thread-safe. === I/O session event mask === @@ -860, +860 @@ === I/O session buffers === - Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel. Memory management in !HttpCore NIO is based on the fundamental principle that the data consumer can read only as much input data as it can process without having to allocate more memory. That means that quite often some input data may remain unread in one of the internal or external session buffers. The I/O reactor can query the status of the session buffers and make sure the consumer gets correctly notified of more data stored in one of the session buffers, thus allowing the consumer to read the remaining data once it is able to process it. I/O sessions can be made aware of the status of external session buffers using the !SessionBufferStatus interface. + Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel. Memory management in !HttpCore NIO is based on the fundamental principle that the data consumer can read only as much input data as it can process without having to allocate more memory. That means, quite often some input data may remain unread in one of the internal or external session buffers. The I/O reactor can query the status of these session buffers, and make sure the consumer gets notified correctly as more data gets stored in one of the session buffers, thus allowing the consumer to read the remaining data once it is able to process it. I/O sessions can be made aware of the status of external session buffers using the !SessionBufferStatus interface. {{{ IOSession iosession; @@ -891, +891 @@ ep3.waitFor(); }}} - Once an endpoint is fully intialized it starts accepting incoming connections and propagates I/O activity notifications to the !IOEventDispatch instance. + Once an endpoint is fully initialized 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. @@ -939, +939 @@ IOSession iosession = sessionRequest.getSession(); }}} - !SessionRequest implementations are expected to be threading safe. Session request can be aborted at any time by calling !IOSession#cancel() from another thread of execution. + !SessionRequest implementations are expected to be thread safe. Session request can be aborted at any time by calling !IOSession#cancel() from another thread of execution. {{{ if (!sessionRequest.isCompleted()) { @@ -959, +959 @@ new InetSocketAddress("192.168.0.10", 1234), null, null); }}} - One can provide a attachment object, which will be added to the new session's context upon initialization. This object can be used to pass an initial processing state to the protocol handler. + One can provide an attachment object, which will be added to the new session's context upon initialization. This object can be used to pass an initial processing state to the protocol handler. {{{ SessionRequest sessionRequest = ioreactor.connect( @@ -970, +970 @@ HttpHost virtualHost = (HttpHost) iosession.getAttribute(IOSession.ATTACHMENT_KEY); }}} - It is often desirable to be able to react to the completion of a session request asynchronously without having to wait for it blocking the current thread of execution. One can optionally provide an implementation !SessionRequestCallback interface to get notified of events related to session requests, such as request completion, cancellation, failure or timeout. + It is often desirable to be able to react to the completion of a session request asynchronously without having to wait for it, blocking the current thread of execution. One can optionally provide an implementation !SessionRequestCallback interface to get notified of events related to session requests, such as request completion, cancellation, failure or timeout. {{{ ConnectingIOReactor ioreactor; @@ -1032, +1032 @@ === I/O reactor audit log === - If an I/O reactor is unable to automatically recover from an I/O or a runtime exception it will enter the shutdown mode. First off, it will close all active listeners and cancel all pending new session requests. Then it will attempt to close all active I/O sessions gracefully giving them some time to flush pending output data and terminate cleanly. Lastly, it will forcibly shut down those I/O sessions that still remain active after the grace period. This is a fairly complex. Many things can fail at the same time and many different exceptions can be thrown in the course of the shutdown process. The I/O reactor will record all exceptions thrown during the shutdown process, including the original one that actually caused the shutdown in the first place, in an audit log. One can examine the audit log and decide whether it is safe to restart the I/O reactor. + If an I/O reactor is unable to automatically recover from an I/O or a runtime exception it will enter the shutdown mode. First off, it will close all active listeners and cancel all pending new session requests. Then it will attempt to close all active I/O sessions gracefully giving them some time to flush pending output data and terminate cleanly. Lastly, it will forcibly shut down those I/O sessions that still remain active after the grace period. This is a fairly complex process, where many things can fail at the same time and many different exceptions can be thrown in the course of the shutdown process. The I/O reactor will record all exceptions thrown during the shutdown process, including the original one that actually caused the shutdown in the first place, in an audit log. One can examine the audit log and decide whether it is safe to restart the I/O reactor. {{{ DefaultConnectingIOReactor ioreactor; @@ -1048, +1048 @@ == Non-blocking HTTP connections == - 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. + Effectively non-blocking HTTP connections are wrappers around !IOSession with HTTP specific functionality. Non-blocking HTTP connections are stateful and not thread 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 === - 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. + 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 thread safe and can be manipulated from multiple threads. {{{ // Get non-blocking HTTP connection @@ -1066, +1066 @@ === Working with non-blocking HTTP connections === - At any point of time one can obtain the request and reponse objects currently being transferred over the non-blocking HTTP connection. Any of these objects, or both, can be null if there is no incoming or outgoing message currently being transferred. + At any point of time one can obtain the request and response objects currently being transferred over the non-blocking HTTP connection. Any of these objects, or both, can be null if there is no incoming or outgoing message currently being transferred. {{{ NHttpConnection conn; @@ -1083, +1083 @@ However, please note that the current request and the current response may not necessarily represent the same message exchange! Non-blocking HTTP connections can operate in a full duplex mode. One can process incoming and outgoing messages completely independently from one another. This makes non-blocking HTTP connections fully pipelining capable, but at same time implies that this is the job of the protocol handler to match logically related request and the response messages. - Over-simplified process of submitting a request on the client side may look like that: + Over-simplified process of submitting a request on the client side may look like this: {{{ // Obtain HTTP connection @@ -1102, +1102 @@ System.out.println(conn.isRequestSubmitted()); }}} - Over-simplified process of submitting a response on the server side may look like that: + Over-simplified process of submitting a response on the server side may look like this: {{{ // Obtain HTTP connection @@ -1129, +1129 @@ === I/O control === - 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. + 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 thread safe. Therefore !IOControl can be used to request / suspend I/O event notifications from any thread. - One must take special precautions when interacting with non-blocking connections. !HttpRequest and !HttpResponse are not threading safe. It is generally advisable that all input / output operations on a non-blocking connection are executed from the I/O event dispatch thread. + One must take special precautions when interacting with non-blocking connections. !HttpRequest and !HttpResponse are not thread safe. It is generally advisable that all input / output operations on a non-blocking connection are executed from the I/O event dispatch thread. The following pattern is recommended: @@ -1292, +1292 @@ * 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. + * 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 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 response. + * exception: triggered when an I/O error occurs 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. @@ -1320, +1320 @@ [[Anchor(BufferingNHttpEntity)]] === BufferingNHttpEntity === - !BufferingNHttpEntity is a subclass of !HttpEntityWrapper that consumes all incoming content into a memeory memory. Once the content body has been fully received it can be retrieved as an InputStream via !HttpEntity#getContent(), or written to an output stream via !HttpEntity#writeTo(). + !BufferingNHttpEntity is a subclass of !HttpEntityWrapper that consumes all incoming content into memory. Once the content body has been fully received it can be retrieved as an InputStream via !HttpEntity#getContent(), or written to an output stream via !HttpEntity#writeTo(). [[Anchor(ConsumingNHttpEntityTemplate)]] === ConsumingNHttpEntityTemplate === @@ -1369, +1369 @@ === Content producing non-blocking HTTP entity === - !ProducingNHttpEntity interface represents a non-blocking allows content to be written to a content encoder. !ProducingNHttpEntity extends the base !HttpEntity interface with a number of NIO specific notification methods: + !ProducingNHttpEntity interface represents a non-blocking entity that allows content to be written to a content encoder. !ProducingNHttpEntity extends the base !HttpEntity interface with a number of NIO specific notification methods: - * produceContent: notification that content can be written to the encoder. !IOControl instance passed as a parameter to the method can be used to temporarily suspend output events if the entity is unable to produce more content. Please note one must call !ContentEncoder#complete() to inform the underyling connection that all content has been written. Failure to do so could result in the entity never being correctly delimited. + * produceContent: notification that content can be written to the encoder. !IOControl instance passed as a parameter to the method can be used to temporarily suspend output events if the entity is unable to produce more content. Please note one must call !ContentEncoder#complete() to inform the underlying connection that all content has been written. Failure to do so could result in the entity never being correctly delimited. * finish: notification that any resources allocated for writing can be released. @@ -1427, +1427 @@ If incoming requests enclose a content entity, !NHttpRequestHandlers are expected to return a !ConsumingNHttpEntity for reading the content. After the entity is finished reading the data, !NHttpRequestHandler#handle() method is called to generate a response. - !AsyncNHttpServiceHandler relies 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 handlers are expected to take care of application specific content generation amd processing. + !AsyncNHttpServiceHandler relies on !HttpProcessor to generate mandatory protocol headers for all outgoing messages and apply common, cross-cutting message transformations to all incoming and outgoing messages, whereas individual HTTP request handlers are expected to take care of application specific content generation and processing. {{{ HttpParams params; @@ -1472, +1472 @@ }; }}} - Request handlers must be implemented threading safe. Similarly to servlets, request handlers should not use instance variables unless access to those variables is synchronized. + Request handlers must be implemented in a thread safe manner. Similarly to servlets, request handlers should not use instance variables unless access to those variables are synchronized. ==== Asynchronous response trigger ==== @@ -1514, +1514 @@ }; }}} - Please note !HttpResponse objects are not threading safe and may not be modified concurrently. Non-blocking request handlers must ensure the HTTP response cannot be accessed by more than one thread at a time. + Please note !HttpResponse objects are not thread safe and may not be modified concurrently. Non-blocking request handlers must ensure the HTTP response cannot be accessed by more than one thread at a time. ==== Non-blocking request handler resolver ==== @@ -1540, +1540 @@ 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. - If incoming responses enclose a content entity, !NHttpRequestExecutionHandler are expected to return a !ConsumingNHttpEntity for reading the content. After the entity is finished reading the data, !NHttpRequestExecutionHandler#handleResponse() method is called to process the response. + If incoming responses enclose a content entity, !NHttpRequestExecutionHandler is expected to return a !ConsumingNHttpEntity for reading the content. After the entity is finished reading the data, !NHttpRequestExecutionHandler#handleResponse() method is called to process the response. - !AsyncNHttpClientHandler relies 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 HTTP request executor is expected to take care of application specific content generation and processing. + !AsyncNHttpClientHandler relies on !HttpProcessor to generate mandatory protocol headers for all outgoing messages and apply common, cross-cutting message transformations to all incoming and outgoing messages, whereas HTTP request executor is expected to take care of application specific content generation and processing. {{{ // Initialize HTTP parameters @@ -1565, +1565 @@ HTTP request execution exents as defined by the !NHttpRequestExecutionHandler interface: - * initalizeContext: triggered when a new connection has been established and the HTTP context needs to be initialized. The attachment object passed to this method is the same object which was passed to the connecting I/O reactor when the connection request was made. The attachment may optionally contain some state information required in order to correctly initalize the HTTP context. + * initalizeContext: triggered when a new connection has been established and the HTTP context needs to be initialized. The attachment object passed to this method is the same object which was passed to the connecting I/O reactor when the connection request was made. The attachment may optionally contain some state information required in order to correctly initialize the HTTP context. - * submitRequest: triggered when the underlying connection is ready to send a new HTTP request to the target host. This method may returt null if the client is not yet ready to send a request. In this case the connection will remain open and can be activated at a later point. If the request encloses an entity, the entity must be an instance of !ProducingNHttpEntity. + * submitRequest: triggered when the underlying connection is ready to send a new HTTP request to the target host. This method may return null if the client is not yet ready to send a request. In this case the connection will remain open and can be activated at a later point. If the request encloses an entity, the entity must be an instance of !ProducingNHttpEntity. * responseEntity: triggered when a response is received with an entity. This method should return a !ConsumingNHttpEntity that will be used to consume the entity. Null is a valid response value, and will indicate that the entity should be silently ignored. After the entity is fully consumed, #handleResponse method is called to notify a full response & entity are ready to be processed. * handleResponse: triggered when an HTTP response is ready to be processed. - * finalizeContext: tiggered when the connection is terminated. This event can be used to release objects stored in the context or perform some other kind of cleanup. + * finalizeContext: triggered when the connection is terminated. This event can be used to release objects stored in the context or perform some other kind of cleanup. {{{ NHttpRequestExecutionHandler execHandler = new NHttpRequestExecutionHandler() { @@ -1620, +1620 @@ === 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. + 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. Compatibility 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. + Compatibility protocol handlers rely on !HttpProcessor to generate mandatory protocol headers for all outgoing messages and apply common, cross-cutting message transformations to 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 ==== - !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. + !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 executors / request handlers must ensure they do not block indefinitely. Buffering protocol handler should be used only when dealing with HTTP messages that are known to be limited in length. ==== Throttling protocol handlers ==== - !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. + !ThrottlingHttpServiceHandler and !ThrottlingHttpClientHandler are protocol handler implementations that provide compatibility with the blocking I/O model 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 does not ever overflow. This helps ensure nearly constant memory footprint for HTTP connections and avoid out of memory conditions 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. @@ -1660, +1660 @@ * 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 input ready, the I/O dispatcher should check whether the SSL I/O session is ready to produce input data by calling !SSLIOSession#isAppInputReady(), pass control to 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. + * 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 to 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 ==== @@ -1672, +1672 @@ * 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. + * verify: triggered when the SSL connection has been established and initial SSL handshake has been successfully completed. The handler can use this callback to verify properties of the !SSLSession. For instance this would be the right place to enforce SSL cipher strength, validate certificate chain and do hostname checks. {{{ // Get hold of new I/O session @@ -1713, +1713 @@ == HTTP message parsing and formatting framework == - HTTP message processing framework is designed to be expressive and flexible while remaining memory efficient and fast. !HttpCore HTTP message processing code achieves near zero intermediate garbage and near zero-copy buffering for its parsing and formatting operations. The same HTTP message parsing and formatting API and implementations are used by both the blocking and non-blocking transport implementations, which helps ensure a consistent behaviour of HTTP services regardless of the I/O model. + HTTP message processing framework is designed to be expressive and flexible while remaining memory efficient and fast. !HttpCore HTTP message processing code achieves near zero intermediate garbage and near zero-copy buffering for its parsing and formatting operations. The same HTTP message parsing and formatting API and implementations are used by both the blocking and non-blocking transport implementations, which helps ensure a consistent behavior of HTTP services regardless of the I/O model. === HTTP line parsing and formatting === --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
