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