OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 library client; | 5 library client; |
6 | 6 |
7 import 'dart:io'; | 7 import 'dart:io'; |
8 | 8 |
9 import 'base_client.dart'; | 9 import 'base_client.dart'; |
10 import 'base_request.dart'; | 10 import 'base_request.dart'; |
| 11 import 'io_client.dart'; |
11 import 'streamed_response.dart'; | 12 import 'streamed_response.dart'; |
12 import 'utils.dart'; | 13 import 'utils.dart'; |
13 | 14 |
14 /// An HTTP client which takes care of maintaining persistent connections across | 15 /// The interface for HTTP clients that take care of maintaining persistent |
15 /// multiple requests to the same server. If you only need to send a single | 16 /// connections across multiple requests to the same server. If you only need to |
16 /// request, it's usually easier to use [head], [get], [post], | 17 /// send a single request, it's usually easier to use [head], [get], [post], |
17 /// [put], or [delete] instead. | 18 /// [put], or [delete] instead. |
18 /// | 19 /// |
19 /// When creating an HTTP client class with additional functionality, it's | 20 /// When creating an HTTP client class with additional functionality, you must |
20 /// recommended that you subclass [BaseClient] and wrap another instance of | 21 /// extend [BaseClient] rather than [Client]. In most cases, you can wrap |
21 /// [BaseClient] rather than subclassing [Client] directly. This allows all | 22 /// another instance of [Client] and add functionality on top of that. This |
22 /// subclasses of [BaseClient] to be mutually composable. | 23 /// allows all classes implementing [Client] to be mutually composable. |
23 class Client extends BaseClient { | 24 abstract class Client { |
24 /// The underlying `dart:io` HTTP client. | 25 /// Creates a new Client using the default implementation. This implementation |
25 HttpClient _inner; | 26 /// uses an underlying `dart:io` [HttpClient] to make requests. |
| 27 factory Client() => new IOClient(); |
26 | 28 |
27 /// Creates a new HTTP client. | 29 /// Sends an HTTP HEAD request with the given headers to the given URL, which |
28 Client() : _inner = new HttpClient(); | 30 /// can be a [Uri] or a [String]. |
| 31 /// |
| 32 /// For more fine-grained control over the request, use [send] instead. |
| 33 Future<Response> head(url, {Map<String, String> headers}); |
| 34 |
| 35 /// Sends an HTTP GET request with the given headers to the given URL, which |
| 36 /// can be a [Uri] or a [String]. |
| 37 /// |
| 38 /// For more fine-grained control over the request, use [send] instead. |
| 39 Future<Response> get(url, {Map<String, String> headers}); |
| 40 |
| 41 /// Sends an HTTP POST request with the given headers and fields to the given |
| 42 /// URL, which can be a [Uri] or a [String]. If any fields are specified, the |
| 43 /// content-type is automatically set to |
| 44 /// `"application/x-www-form-urlencoded"`. |
| 45 /// |
| 46 /// For more fine-grained control over the request, use [send] instead. |
| 47 Future<Response> post(url, |
| 48 {Map<String, String> headers, |
| 49 Map<String, String> fields}); |
| 50 |
| 51 /// Sends an HTTP PUT request with the given headers and fields to the given |
| 52 /// URL, which can be a [Uri] or a [String]. If any fields are specified, the |
| 53 /// content-type is automatically set to |
| 54 /// `"application/x-www-form-urlencoded"`. |
| 55 /// |
| 56 /// For more fine-grained control over the request, use [send] instead. |
| 57 Future<Response> put(url, |
| 58 {Map<String, String> headers, |
| 59 Map<String, String> fields}); |
| 60 |
| 61 /// Sends an HTTP DELETE request with the given headers to the given URL, |
| 62 /// which can be a [Uri] or a [String]. |
| 63 /// |
| 64 /// For more fine-grained control over the request, use [send] instead. |
| 65 Future<Response> delete(url, {Map<String, String> headers}); |
| 66 |
| 67 /// Sends an HTTP GET request with the given headers to the given URL, which |
| 68 /// can be a [Uri] or a [String], and returns a Future that completes to the |
| 69 /// body of the response as a String. |
| 70 /// |
| 71 /// The Future will emit an [HttpException] if the response doesn't have a |
| 72 /// success status code. |
| 73 /// |
| 74 /// For more fine-grained control over the request and response, use [send] or |
| 75 /// [get] instead. |
| 76 Future<String> read(url, {Map<String, String> headers}); |
| 77 |
| 78 /// Sends an HTTP GET request with the given headers to the given URL, which |
| 79 /// can be a [Uri] or a [String], and returns a Future that completes to the |
| 80 /// body of the response as a list of bytes. |
| 81 /// |
| 82 /// The Future will emit an [HttpException] if the response doesn't have a |
| 83 /// success status code. |
| 84 /// |
| 85 /// For more fine-grained control over the request and response, use [send] or |
| 86 /// [get] instead. |
| 87 Future<Uint8List> readBytes(url, {Map<String, String> headers}); |
29 | 88 |
30 /// Sends an HTTP request and asynchronously returns the response. | 89 /// Sends an HTTP request and asynchronously returns the response. |
31 Future<StreamedResponse> send(BaseRequest request) { | 90 Future<StreamedResponse> send(BaseRequest request); |
32 var stream = request.finalize(); | |
33 | 91 |
34 var completer = new Completer<StreamedResponse>(); | 92 /// Closes the client and cleans up any resources associated with it. It's |
35 var connection = _inner.openUrl(request.method, request.url); | 93 /// important to close each client when it's done being used; failing to do so |
36 connection.onError = (e) { | 94 /// can cause the Dart process to hang. |
37 async.then((_) { | 95 void close(); |
38 // TODO(nweiz): remove this when issue 4974 is fixed | |
39 if (completer.future.isComplete) throw e; | |
40 | |
41 completer.completeException(e); | |
42 }); | |
43 }; | |
44 | |
45 connection.onRequest = (underlyingRequest) { | |
46 underlyingRequest.contentLength = request.contentLength; | |
47 underlyingRequest.persistentConnection = request.persistentConnection; | |
48 request.headers.forEach((name, value) { | |
49 underlyingRequest.headers.set(name, value); | |
50 }); | |
51 | |
52 if (stream.closed) { | |
53 underlyingRequest.outputStream.close(); | |
54 } else { | |
55 stream.pipe(underlyingRequest.outputStream); | |
56 } | |
57 }; | |
58 | |
59 connection.onResponse = (response) { | |
60 var headers = <String>{}; | |
61 response.headers.forEach((key, value) => headers[key] = value); | |
62 | |
63 completer.complete(new StreamedResponse( | |
64 response.inputStream, | |
65 response.statusCode, | |
66 response.contentLength, | |
67 headers: headers, | |
68 isRedirect: response.isRedirect, | |
69 persistentConnection: response.persistentConnection, | |
70 reasonPhrase: response.reasonPhrase)); | |
71 }; | |
72 | |
73 return completer.future; | |
74 } | |
75 | |
76 /// Closes the client. This terminates all active connections. If a client | |
77 /// remains unclosed, the Dart process may not terminate. | |
78 void close() { | |
79 if (_inner != null) _inner.shutdown(); | |
80 _inner = null; | |
81 } | |
82 } | 96 } |
OLD | NEW |