Index: sdk/lib/io/http.dart |
diff --git a/sdk/lib/io/http.dart b/sdk/lib/io/http.dart |
index 9a54af20c27d0421de5a5aebcb119a3653b36218..32c00a64bbf3b82fa1692de31191b819fddfcda0 100644 |
--- a/sdk/lib/io/http.dart |
+++ b/sdk/lib/io/http.dart |
@@ -688,17 +688,17 @@ abstract class HttpRequest implements Stream<List<int>> { |
* will be determined from the "charset" parameter of the |
* "Content-Type" header. |
* |
- * HttpResponse response = ... |
- * response.headers.contentType |
- * = new ContentType("application", "json", charset: "utf-8"); |
- * response.write(...); // Strings written will be UTF-8 encoded. |
+ * HttpResponse response = ... |
+ * response.headers.contentType |
+ * = new ContentType("application", "json", charset: "utf-8"); |
+ * response.write(...); // Strings written will be UTF-8 encoded. |
* |
* If no charset is provided the default of ISO-8859-1 (Latin 1) will |
* be used. |
* |
- * HttpResponse response = ... |
- * response.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain"); |
- * response.write(...); // Strings written will be ISO-8859-1 encoded. |
+ * HttpResponse response = ... |
+ * response.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain"); |
+ * response.write(...); // Strings written will be ISO-8859-1 encoded. |
* |
* If an unsupported encoding is used an exception will be thrown if |
* using one of the write methods taking a string. |
@@ -762,13 +762,50 @@ abstract class HttpResponse implements IOSink<HttpResponse> { |
/** |
- * HTTP client factory. The [HttpClient] handles all the sockets associated |
- * with the [HttpClientConnection]s and when the endpoint supports it, it will |
- * try to reuse opened sockets for several requests to support HTTP 1.1 |
- * persistent connections. This means that sockets will be kept open for some |
- * time after a requests have completed, unless HTTP procedures indicate that it |
- * must be closed as part of completing the request. Use [:HttpClient.close:] |
- * to force close the idle sockets. |
+ * The [HttpClient] class implements the client side of the HTTP |
+ * protocol. It contains a number of methods to send a HTTP request |
+ * to a HTTP server and receive a HTTP response back. |
+ * |
+ * This is a two-step process, triggered by two futures. When the |
+ * first future completes with a [HttpClientRequest] the underlying |
+ * network connection has been established, but no data has yet been |
+ * sent. The HTTP headers and body can be set on the request, and |
+ * [:close:] is called to sent it to the server. |
+ * |
+ * The second future, is returned by [:close:], completes with an |
Bill Hesse
2013/04/12 08:26:00
future, which is returned ...
Søren Gjesse
2013/04/12 08:28:37
Done.
|
+ * [HttpClientResponse] object when the response is received from the |
+ * server. This object contains the headers and body of the response. |
+ |
+ * The future for [HttpClientRequest] is created by methods such as |
+ * [getUrl] and [open]. |
+ * |
+ * When the HTTP response is ready a [HttpClientResponse] object is |
+ * provided which provides access to the headers and body of the response. |
+ * |
+ * HttpClient client = new HttpClient(); |
+ * client.getUrl(new Uri.fromString("http://www.example.com/")) |
+ * .then((HttpClientRequest request) { |
+ * // Prepare the request then call close on it to send it. |
+ * return request.close(); |
+ * }) |
+ * .then((HttpClientResponse response) { |
+ * // Process the response. |
+ * }); |
+ * |
+ * All [HttpClient] requests set the following header by default: |
+ * |
+ * Accept-Encoding: gzip |
+ * |
+ * This allows the HTTP server to use gzip compression for the body if |
+ * possible. If this behavior is not desired set the |
+ * "Accept-Encoding" header to something else. |
+ * |
+ * The [HttpClient] supports persistent connections and caches network |
+ * connections to reuse then for multiple requests whenever |
+ * possible. This means that network connections can be kept open for |
+ * some time after a request have completed. Use [:HttpClient.close:] |
+ * to force shut down the [HttpClient] object and close the idle |
+ * network connections. |
*/ |
abstract class HttpClient { |
static const int DEFAULT_HTTP_PORT = 80; |
@@ -906,17 +943,17 @@ abstract class HttpClient { |
* To activate this way of resolving proxies assign this function to |
* the [findProxy] property on the [HttpClient]. |
* |
- * HttpClient client = new HttpClient(); |
- * client.findProxy = HttpClient.findProxyFromEnvironment; |
+ * HttpClient client = new HttpClient(); |
+ * client.findProxy = HttpClient.findProxyFromEnvironment; |
* |
* If you don't want to use the system environment you can use a |
* different one by wrapping the function. |
* |
- * HttpClient client = new HttpClient(); |
- * client.findProxy = (url) { |
- * return HttpClient.findProxyFromEnvironment( |
- * url, {"http_proxy": ..., "no_proxy": ...}); |
- * } |
+ * HttpClient client = new HttpClient(); |
+ * client.findProxy = (url) { |
+ * return HttpClient.findProxyFromEnvironment( |
+ * url, {"http_proxy": ..., "no_proxy": ...}); |
+ * } |
*/ |
static String findProxyFromEnvironment(Uri url, |
{Map<String, String> environment}) { |
@@ -951,17 +988,17 @@ abstract class HttpClient { |
* encoding used will be determined from the "charset" parameter of |
* the "Content-Type" header. |
* |
- * HttpClientRequest request = ... |
- * request.headers.contentType |
- * = new ContentType("application", "json", charset: "utf-8"); |
- * request.write(...); // Strings written will be UTF-8 encoded. |
+ * HttpClientRequest request = ... |
+ * request.headers.contentType |
+ * = new ContentType("application", "json", charset: "utf-8"); |
+ * request.write(...); // Strings written will be UTF-8 encoded. |
* |
* If no charset is provided the default of ISO-8859-1 (Latin 1) will |
* be used. |
* |
- * HttpClientRequest request = ... |
- * request.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain"); |
- * request.write(...); // Strings written will be ISO-8859-1 encoded. |
+ * HttpClientRequest request = ... |
+ * request.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain"); |
+ * request.write(...); // Strings written will be ISO-8859-1 encoded. |
* |
* If an unsupported encoding is used an exception will be thrown if |
* using one of the write methods taking a string. |