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 SebastianBazley: http://wiki.apache.org/HttpComponents/HttpCoreTutorial The comment on the change is: Fixed a few typos ------------------------------------------------------------------------------ === Basic operations === - ==== HTTP request properties ==== + ==== HTTP request message ==== HTTP request is a message sent from the client to the server. The first line of that message includes the method to be applied to the resource, the identifier of the resource, and the protocol version in use. @@ -55, +55 @@ GET / HTTP/1.1 }}} - ==== HTTP response properties ==== + ==== HTTP response message ==== HTTP response is a message sent by the server back to the client after having received and interpreted a request message. The first line of that message consists of the protocol version followed by a numeric status code and its associated textual phrase. @@ -166, +166 @@ === Repeatable entities === - An entity can be repeatable, meaning it's content can be read more than once. This is only possible with self contained entities (like !ByteArrayEntity or !StringEntity). + An entity can be repeatable, meaning its content can be read more than once. This is only possible with self contained entities (like !ByteArrayEntity or !StringEntity). === Using HTTP entities === @@ -178, +178 @@ The !EntityUtils class exposes several static methods to more easily read the content or information from an entity. Instead of reading the !InputStream directly, one can retrieve the whole content body in a String/byte array by using the methods from this class. - When the entity was received with an incoming message, the methods !HttpEntity#getContentType() and !HttpEntity#getContentLength() methods can be used for reading the common metadata such as Content-Type and Content-Length headers (if they are available). Since the Content-Type header can contain a character encoding for text mime-types like text/plain or text/html, the !HttpEntity#getContentEncoding() method is used to read this information. If the headers aren't available, a length of -1 will be returned, and NULL for the content-type. If the Content-Type header is available, a Header object will be returned. + When the entity has been received with an incoming message, the methods !HttpEntity#getContentType() and !HttpEntity#getContentLength() methods can be used for reading the common metadata such as Content-Type and Content-Length headers (if they are available). Since the Content-Type header can contain a character encoding for text mime-types like text/plain or text/html, the !HttpEntity#getContentEncoding() method is used to read this information. If the headers aren't available, a length of -1 will be returned, and NULL for the content-type. If the Content-Type header is available, a Header object will be returned. When creating an entity for a outgoing message, this meta data has to be supplied by the creator of the entity. @@ -226, +226 @@ [[Anchor(BasicHttpEntity)]] === BasicHttpEntity === - This is exactly as the name implies, a basic entity that represents an underlying stream. This is generally the entities received from HTTP responses. + This is exactly as the name implies, a basic entity that represents an underlying stream. This is generally used for the entities received from HTTP responses. - This entity has an empty constructor. After constructor it represents no content, and has a negative content length. + This entity has an empty constructor. After construction it represents no content, and has a negative content length. One needs to set the content stream, and optionally the length. This can be done with the !BasicHttpEntity#setContent(!InputStream) and !BasicHttpEntity#setContentLength(long) methods respectively. @@ -241, +241 @@ [[Anchor(ByteArrayEntity)]] === ByteArrayEntity === - This is a simple self contained repeatable entity, which receives it's content from a given byte array. This byte array is supplied to the constructor. + This is a simple self contained repeatable entity, which receives its content from a given byte array. This byte array is supplied to the constructor. {{{ String myData = "Hello world on the other side!!"; @@ -251, +251 @@ [[Anchor(StringEntity)]] === StringEntity === - Very simple entity. It's is a self contained, repeatable entity that retrieves it's data from a String object. + Very simple entity. It's is a self contained, repeatable entity that retrieves its data from a String object. - It has 2 constructors, one simply constructs with a given String object where the other also takes a character encoding for the data in the String. + It has 2 constructors, one simply constructs with a given String object; the other also takes a character encoding for the data in the String. {{{ StringBuffer sb = new StringBuffer(); @@ -272, +272 @@ [[Anchor(EntityTemplate)]] === EntityTemplate === - This is an entity which receives it's content from a !ContentProducer. Content producers are objects which produce their content on demand, by writing it out to an output stream. They are expected to be able produce their content every time they are requested to do so. So creating a !EntityTemplate, one is expected to supply a reference to a content producer, which effectively creates a repeatable entity. + This is an entity which receives its content from a !ContentProducer. Content producers are objects which produce their content on demand, by writing it out to an output stream. They are expected to be able produce their content every time they are requested to do so. So creating a !EntityTemplate, one is expected to supply a reference to a content producer, which effectively creates a repeatable entity. There are no standard !ContentProducers in !HttpCore. It's basically just a convenience interface to allow wrapping up complex logic into an entity. To use this entity one needs to create a class that implements !ContentProducer and override the !ContentProducer#writeTo(!OutputStream) method. Then, an instance of custom !ContentProducer will be used to write the full content body to the output stream. For instance, an HTTP server would serve static files with the !FileEntity, but running CGI programs could be done with a !ContentProducer, inside which one could implement custom logic to supply the content as it becomes available. This way one doesn't need to buffer it in a string and then use a !StringEntity or !ByteArrayEntity. @@ -298, +298 @@ [[Anchor(FileEntity)]] === FileEntity === - This entity reads it's 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 one would supply 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"); @@ -307, +307 @@ [[Anchor(InputStreamEntity)]] === InputStreamEntity === - An entity that reads it's content from an input stream. It is constructed by supplied the input stream as well as the content length. + An entity that reads its content from an input stream. It is constructed by supplying the input stream and the content length. The content length is used to limit the amount of data read from the !InputStream. If the length matches the content length available on the input stream, then all data will be sent. Alternatively a negative content length will read all data from the input stream, which is the same as supplying the exact content length, so the length is most often used to limit the length. @@ -342, +342 @@ HTTP connections are responsible for HTTP message serialization and deserialization. One should rarely need to use HTTP connection objects directly. There are higher level protocol components intended for execution and processing of HTTP requests. However, in some cases direct interaction with HTTP connections may be necessary, for instance, to access properties such as the connection status, the socket timeout or the local and remote addresses. - It is important to bear in mind that HTTP connections are not threading safe. It is strongly recommended to limit all interactions with HTTP connection objects to one thread. The only method of !HttpConnection interface and its sub-interfaces, which is safe to invoke from another thread, is !HttpConnection#shutdown(). + It is important to bear in mind that HTTP connections are not thread-safe. It is strongly recommended to limit all interactions with HTTP connection objects to one thread. The only method of !HttpConnection interface and its sub-interfaces, which is safe to invoke from another thread, is !HttpConnection#shutdown(). === Working with blocking HTTP connections === @@ -362, +362 @@ metrics.getSentBytesCount(); }}} - HTTP connection interfaces, both client and server, send and receive messages in two stages. 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. + 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: @@ -412, +412 @@ === Content transfer === - HTTP connections manage the process of the content transfer using the functionality!HttpEntity interface. HTTP connections generate an entity object that encapsulates the content stream of the incoming message. Please note that !HttpServerConnection#receiveRequestEntity() and !HttpClientConnection#receiveResponseEntity() do not retrieve or buffer any incoming data. They merely inject an appropriate content codec based on the properties of the incoming message. The content can be retrieved by reading from the content input stream of the enclosed entity using !HttpEntity#getContent(). The incoming data will be decoded automatically completely transparently for the data consumer. Likewise, HTTP connections rely on !HttpEntity#writeTo(!OutputStream) method to generate the content of an outgoing message. if an outgoing messages encloses an entity, the content will be encoded automatically based on the properties of the message. + HTTP connections manage the process of the content transfer using the !HttpEntity interface. HTTP connections generate an entity object that encapsulates the content stream of the incoming message. Please note that !HttpServerConnection#receiveRequestEntity() and !HttpClientConnection#receiveResponseEntity() do not retrieve or buffer any incoming data. They merely inject an appropriate content codec based on the properties of the incoming message. The content can be retrieved by reading from the content input stream of the enclosed entity using !HttpEntity#getContent(). The incoming data will be decoded automatically completely transparently for the data consumer. Likewise, HTTP connections rely on !HttpEntity#writeTo(!OutputStream) method to generate the content of an outgoing message. if an outgoing messages encloses an entity, the content will be encoded automatically based on the properties of the message. === Supported content transfer mechanisms === @@ -434, +434 @@ === 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. + 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 thread-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 thread-safe. == HTTP exception handling == - All !HttpCore components throw two types of exceptions: !IOException in case of an I/O failure such as socket timeout or an socket reset and !HttpException that signals an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are considered non-fatal and recoverable, whereas HTTP protocol errors are considered fatal and cannot be automatically recovered from. + All !HttpCore components potentially throw two types of exceptions: !IOException in case of an I/O failure such as socket timeout or an socket reset and !HttpException that signals an HTTP failure such as a violation of the HTTP protocol. Usually I/O errors are considered non-fatal and recoverable, whereas HTTP protocol errors are considered fatal and cannot be automatically recovered from. === Protocol exception === @@ -450, +450 @@ HTTP protocol processor is a collection of protocol interceptors that implements the 'Chain of Responsibility' pattern, where each individual protocol interceptor is expected to work on a particular aspect of the HTTP protocol the interceptor is responsible for. - Protocol interceptors must be implemented threading safe. Similarly to servlets, protocol interceptors should not use instance variables unless access to those variables is synchronized. + Protocol interceptors must be implemented as thread-safe. Similarly to servlets, protocol interceptors should not use instance variables unless access to those variables is synchronized. === Standard protocol interceptors === @@ -523, +523 @@ === HTTP context === - Protocol interceptors can collaborate by sharing information such as a processing state through an HTTP execution context. HTTP context is a structure that can be used to map an attribute name to an attribute value. Internally HTTP context implementations are usually backed by a HashMap. The primary purpose of the HTTP context is to facilitate information sharing among various logically related components. HTTP context can be used to store a processing state for one message or several consecutive messages. Multiple logically related messages can participate in a logical session if the same context is reused between consecutive messages. + Protocol interceptors can collaborate by sharing information - such as a processing state - through an HTTP execution context. HTTP context is a structure that can be used to map an attribute name to an attribute value. Internally HTTP context implementations are usually backed by a HashMap. The primary purpose of the HTTP context is to facilitate information sharing among various logically related components. HTTP context can be used to store a processing state for one message or several consecutive messages. Multiple logically related messages can participate in a logical session if the same context is reused between consecutive messages. {{{ BasicHttpProcessor httpproc = new BasicHttpProcessor(); @@ -606, +606 @@ === HTTP parameter beans === - !HttpParams interface allows for a great deal of flexibility in handling configuration of components. Most importantly, new parameters can be introduced without affecting binary compatibility with older versions. However, !HttpParams also has a certain disadvantage compared to regular java beans: !HttpParams cannot be assembled using a DI framework. To mitigate the limitation, !HttpCore includes a number of bean classes that cab used in order to initialize !HttpParams objects using standard java bean conventions. + !HttpParams interface allows for a great deal of flexibility in handling configuration of components. Most importantly, new parameters can be introduced without affecting binary compatibility with older versions. However, !HttpParams also has a certain disadvantage compared to regular Java beans: !HttpParams cannot be assembled using a DI framework. To mitigate the limitation, !HttpCore includes a number of bean classes that can used in order to initialize !HttpParams objects using standard Java bean conventions. {{{ HttpParams params = new BasicHttpParams(); @@ -745, +745 @@ === Connection persistence / re-use === - !ConnectionReuseStrategy interface is intended to determine whether the underlying connection can be reused for processing of consecutive 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 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. = NIO extensions = @@ -753, +753 @@ Contrary to the popular belief, the performance of NIO in terms of raw data throughput is significantly lower than than of the blocking I/O. NIO does not necessarily fit all use cases and should be used only where appropriate: - * handling of thousands of connections, significant number of which can be idle + * handling of thousands of connections, a significant number of which can be idle * handling high latency connections @@ -761, +761 @@ == Differences from other NIO frameworks == - Solves similar problems as other frameworks, but has certain distinct features + Solves similar problems as other frameworks, but has certain distinct features: * minimalistic, optimized for data volume intensive protocols such as HTTP @@ -773, +773 @@ !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. - I/O reactors usually employ a small number of worker 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. + 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. {{{ HttpParams params = new BasicHttpParams(); @@ -783, +783 @@ === I/O dispatchers === - !IOReactor implementations make use of the !IOEventDispatch interface to notify of events pending for a particular session. All methods of the !IOEventDispatch are executed on a dispatch thread of the I/O reactor. Therefore, it is important that processing that takes place in the event methods will not block the dispatch thread for too long, as the I/O reactor will be unable to react to other events. + !IOReactor implementations make use of the !IOEventDispatch interface to notify clients of events pending for a particular session. All methods of the !IOEventDispatch are executed on a dispatch thread of the I/O reactor. Therefore, it is important that processing that takes place in the event methods will not block the dispatch thread for too long, as the I/O reactor will be unable to react to other events. {{{ HttpParams params = new BasicHttpParams(); @@ -810, +810 @@ The shutdown of I/O reactors is a complex process and may usually take a while to complete. I/O reactors will attempt to gracefully terminate all active I/O sessions and dispatch threads approximately within the specified grace period. If any of the I/O sessions fails to terminate correctly, the I/O reactor will forcibly shut down remaining sessions. {{{ - int gracePeriod = 3000; // milliseconds + long gracePeriod = 3000L; // milliseconds ioreactor.shutdown(gracePeriod); }}} @@ -838, +838 @@ Object currentState = iosession.getAttribute("state"); }}} - Please note if several sessions make use of shared objects, access to those objects must be synchronized or threading safe. + Please note if several sessions make use of shared objects, access to those objects must be thread-safe. === I/O session event mask === @@ -891, +891 @@ ep3.waitFor(); }}} - Once an enpoint is fully intialized it starts accepting incoming connections and propagate I/O activity notifications to the !IOEventDispatch instance. + Once an endpoint is fully intialized 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. @@ -1028, +1028 @@ }); }}} - One ought to be very careful about discarding exceptions indiscriminately. It is often much better to let the I/O reactor shut down itself cleanly and restart it rather than leaving it in an inconsistent or unstable state. + One needs to be very careful about discarding exceptions indiscriminately. It is often much better to let the I/O reactor shut down itself cleanly and restart it rather than leaving it in an inconsistent or unstable state. === I/O reactor audit log === @@ -1384, +1384 @@ [[Anchor(NByteArrayEntity)]] === NByteArrayEntity === - This is a simple self contained repeatable entity, which receives it's content from a given byte array. This byte array is supplied to the constructor. + This is a simple self contained repeatable entity, which receives its content from a given byte array. This byte array is supplied to the constructor. {{{ String myData = "Hello world on the other side!!"; @@ -1394, +1394 @@ [[Anchor(NStringEntity)]] === NStringEntity === - It's is a simple, self contained, repeatable entity that retrieves it's data from a String object. + It's is a simple, self contained, repeatable entity that retrieves its data from a String object. It has 2 constructors, one simply constructs with a given String object where the other also takes a character encoding for the data in the String. @@ -1409, +1409 @@ [[Anchor(NFileEntity)]] === NFileEntity === - This entity reads it's content body from a file. This class is mostly used to stream large files of different types, so one needs to supply the content type of the file to make sure the content can be correctly recognized and processed by the recipient. + This entity reads its content body from a file. This class is mostly used to stream large files of different types, so one needs to supply the content type of the file to make sure the content can be correctly recognized and processed by the recipient. {{{File staticFile = new File("/path/to/myapp.jar"); NHttpEntity entity = new NFileEntity(staticFile, "application/java-archive"); --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
