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 ------------------------------------------------------------------------------ BufferedHttpEntity myBufferedEntity = new BufferedHttpEntity(myNonRepeatableEntity); }}} - == HTTP connections == + == Blocking 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. 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(). - === Blocking HTTP connections === + === 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. @@ -376, +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 + Over-simplified process of client side request execution may look like that: {{{ Socket socket = new Socket(); @@ -400, +398 @@ } }}} - Over-simplified server side request handling code may look like that + Over-simplified process of server side request handling may look like that: {{{ Socket socket = new Socket(); @@ -424, +422 @@ 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. + Please note that one should rarely need to transmit messages using these low level methods and should use appropriate higher level HTTP service implementations instead. === Content transfer === @@ -914, +912 @@ context.setAttribute("state", myStateObject); }}} - === Interacting with non-blocking HTTP connections === + === 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. + + {{{ + NHttpConnection conn; + + HttpRequest request = conn.getHttpRequest(); + if (request != null) { + System.out.println("Transferring request: " + request.getRequestLine()); + } + HttpResponse response = conn.getHttpResponse(); + if (response != null) { + System.out.println("Transferring response: " + response.getStatusLine()); + } + }}} + + 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: + + {{{ + // Obtain HTTP connection + NHttpClientConnection conn; + + // Obtain execution context + HttpContext context = conn.getContext(); + + // Obtain processing state + Object state = context.getAttribute("state"); + + // Generate a request based on the state information + HttpRequest request = new BasicHttpRequest("GET", "/"); + + conn.submitRequest(request); + System.out.println(conn.isRequestSubmitted()); + }}} + + Over-simplified process of submitting a response on the server side may look like that: + + {{{ + // Obtain HTTP connection + NHttpServerConnection conn; + + // Obtain execution context + HttpContext context = conn.getContext(); + + // Obtain processing state + Object state = context.getAttribute("state"); + + // Generate a response based on the state information + HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, HttpStatus.SC_OK, "OK"); + BasicHttpEntity entity = new BasicHttpEntity(); + entity.setContentType("text/plain"); + entity.setChunked(true); + response.setEntity(entity); + + conn.submitResponse(response); + System.out.println(conn.isResponseSubmitted()); + }}} + + Please note that one should rarely need to transmit messages using these low level methods and should use appropriate higher level HTTP service implementations instead. + + === 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. - 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. + 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. The following pattern is recommended: @@ -959, +1020 @@ encoder.write(src); // Mark content entity as fully transferred when done encoder.complete(); + }}} + + Please note, one still has to provide an !HttpEntity instance when submitting an entity enclosing message to the non-blocking HTTP connection. Properties of that entity will be used to initialize an !ContentEncoder instance to be used for transferring entity content. Non-blocking HTTP connections, however, ignore inherently blocking !HttpEntity#getContent() and !HttpEntity#writeTo() methods of the enclosed entities. + + {{{ + // Obtain HTTP connection + NHttpServerConnection conn; + + HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, HttpStatus.SC_OK, "OK"); + BasicHttpEntity entity = new BasicHttpEntity(); + entity.setContentType("text/plain"); + entity.setChunked(true); + entity.setContent(null); + response.setEntity(entity); + + conn.submitResponse(response); + }}} + + Likewise, incoming entity enclosing message will have an !HttpEntity instance associated with them, but an attempt to call !HttpEntity#getContent() or !HttpEntity#writeTo() methods will cause an !IllegalStateException. The !HttpEntity instance can be used to determine properties of the incoming entity such as content length. + + {{{ + // Obtain HTTP connection + NHttpClientConnection conn; + + HttpResponse response = conn.getHttpResponse(); + HttpEntity entity = response.getEntity(); + if (entity != null) { + System.out.println(entity.getContentType()); + System.out.println(entity.getContentLength()); + System.out.println(entity.isChunked()); + } }}} === Supported non-blocking content transfer mechanisms === --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
