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 ------------------------------------------------------------------------------ == HTTP connections == - 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. + 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. - 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 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(). - === Using blocking HTTP connections === + === Blocking HTTP connections === - !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. + !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. {{{ + Socket socket = new Socket(); + // Initialize socket BasicHttpParams params = new BasicHttpParams(); DefaultHttpClientConnection conn = new DefaultHttpClientConnection(); - conn.bind(mySocket, params); + conn.bind(socket, params); conn.isOpen(); HttpConnectionMetrics metrics = conn.getMetrics(); metrics.getRequestCount(); @@ -374, +376 @@ metrics.getSentBytesCount(); }}} + === Transferring messages over HTTP connections === + + 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. + + Over-simplified client side request execution code may look like that + + {{{ + Socket socket = new Socket(); + // Initialize socket + HttpParams params = new BasicHttpParams(); + DefaultHttpClientConnection conn = new DefaultHttpClientConnection(); + conn.bind(socket, params); + HttpRequest request = new BasicHttpRequest("GET", "/"); + conn.sendRequestHeader(request); + HttpResponse response = conn.receiveResponseHeader(); + conn.receiveResponseEntity(response); + HttpEntity entity = response.getEntity(); + if (entity != null) { + // Do something useful with the entity and, when done, call + // consumeContent() to make sure the connection can be re-used + entity.consumeContent(); + } + }}} + + Over-simplified server side request handling code may look like that + + {{{ + Socket socket = new Socket(); + // Initialize socket + HttpParams params = new BasicHttpParams(); + DefaultHttpServerConnection conn = new DefaultHttpServerConnection(); + conn.bind(socket, params); + HttpRequest request = conn.receiveRequestHeader(); + if (request instanceof HttpEntityEnclosingRequest) { + conn.receiveRequestEntity((HttpEntityEnclosingRequest) request); + HttpEntity entity = ((HttpEntityEnclosingRequest) request).getEntity(); + if (entity != null) { + // Do something useful with the entity and, when done, call + // consumeContent() to make sure the connection can be re-used + entity.consumeContent(); + } + } + HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, 200, "OK"); + response.setEntity(new StringEntity("Got it")); + conn.sendResponseHeader(response); + conn.sendResponseEntity(response); + }}} + + Please note that one should rerely need to transmit messages using these low level methods and should use appropriate higher level HTTP service implementations instead. + + === 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. + + === Supported content transfer mechanisms === + + Default implementations of the 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 underying connection (EOF condition). For obvious reasons the identity encoing 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. + === 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 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. - - === Content transfer === - - * Content-Length delimited - - * Identity coding - - * Chunk coding - - === Parsing and formatting of HTTP messages === - - HttpMessageParser / HttpMessageWriter interfaces == HTTP protocol processors == --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
