hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Httpcomponents Wiki] Update of "HttpCoreTutorial" by OlegKalnichevski
Date Thu, 09 Oct 2008 18:31:59 GMT
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: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org


Mime
View raw message