Merge pull request #114 from dart-lang/add_close_method

add a close method; prep for publishing 3.3.0

analysis_options.yaml

@@ -3,5 +3,6 @@ analyzer:
 linter:
   rules:
     - annotate_overrides
+    - directives_ordering
     - empty_constructor_bodies
     - empty_statements

changelog.md

@@ -1,6 +1,7 @@
 # Changelog
 
-## unreleased
+## 3.3.0
+- added a `close()` method to the `Analytics` class
 - change our minimum SDK from `1.24.0-dev` to `1.24.0` stable
 
 ## 3.2.0

example/ga.dart

@@ -28,4 +28,8 @@ main(List args) async {
   await ga.sendTiming('writeDuration', 123);
   await ga.sendEvent('create', 'consoleapp', label: 'Console App');
   print('pinged ${ua}');
+
+  await ga.waitForLastPing();
+
+  ga.close();
 }

lib/src/usage_impl.dart

@@ -214,6 +214,9 @@ class AnalyticsImpl implements Analytics {
     return f;
   }
 
+  @override
+  void close() => postHandler.close();
+
   @override
   String get clientId => properties['clientId'] ??= new Uuid().generateV4();
 
@@ -291,4 +294,7 @@ abstract class PersistentProperties {
  */
 abstract class PostHandler {
   Future sendPost(String url, Map<String, dynamic> parameters);
+
+  /// Free any used resources.
+  void close();
 }

lib/src/usage_impl_html.dart

@@ -30,10 +30,13 @@ class AnalyticsHtml extends AnalyticsImpl {
   }
 }
 
+typedef Future<HttpRequest> HttpRequestor(String url,
+    {String method, sendData});
+
 class HtmlPostHandler extends PostHandler {
-  final Function mockRequestor;
+  final HttpRequestor mockRequestor;
 
-  HtmlPostHandler({Function this.mockRequestor});
+  HtmlPostHandler({this.mockRequestor});
 
   @override
   Future sendPost(String url, Map<String, dynamic> parameters) {
@@ -43,12 +46,16 @@ class HtmlPostHandler extends PostHandler {
     parameters['vp'] = '${viewportWidth}x$viewportHeight';
 
     String data = postEncode(parameters);
-    var request = mockRequestor == null ? HttpRequest.request : mockRequestor;
-    return request(url, method: 'POST', sendData: data).catchError((e) {
+    HttpRequestor requestor =
+        mockRequestor == null ? HttpRequest.request : mockRequestor;
+    return requestor(url, method: 'POST', sendData: data).catchError((e) {
       // Catch errors that can happen during a request, but that we can't do
       // anything about, e.g. a missing internet connection.
     });
   }
+
+  @override
+  void close() {}
 }
 
 class HtmlPersistentProperties extends PersistentProperties {

lib/src/usage_impl_io.dart

@@ -77,16 +77,21 @@ class IOPostHandler extends PostHandler {
   final String _userAgent;
   final HttpClient mockClient;
 
-  IOPostHandler({HttpClient this.mockClient}) : _userAgent = _createUserAgent();
+  HttpClient _client;
+
+  IOPostHandler({this.mockClient}) : _userAgent = _createUserAgent();
 
   @override
   Future sendPost(String url, Map<String, dynamic> parameters) async {
     String data = postEncode(parameters);
 
-    HttpClient client = mockClient != null ? mockClient : new HttpClient();
-    client.userAgent = _userAgent;
+    if (_client == null) {
+      _client = mockClient != null ? mockClient : new HttpClient();
+      _client.userAgent = _userAgent;
+    }
+
     try {
-      HttpClientRequest req = await client.postUrl(Uri.parse(url));
+      HttpClientRequest req = await _client.postUrl(Uri.parse(url));
       req.write(data);
       HttpClientResponse response = await req.close();
       response.drain();
@@ -95,6 +100,9 @@ class IOPostHandler extends PostHandler {
       // anything about, e.g. a missing internet connection.
     }
   }
+
+  @override
+  void close() => _client?.close();
 }
 
 JsonEncoder _jsonEncoder = new JsonEncoder.withIndent('  ');

lib/usage.dart

@@ -164,9 +164,15 @@ abstract class Analytics {
    * users won't want their CLI app to pause at the end of the process waiting
    * for Google analytics requests to complete. This method allows CLI apps to
    * delay for a short time waiting for GA requests to complete, and then do
-   * something like call `exit()` explicitly themselves.
+   * something like call `dart:io`'s `exit()` explicitly themselves (or the
+   * [close] method below).
    */
   Future waitForLastPing({Duration timeout});
+
+  /// Free any used resources.
+  ///
+  /// The [Analytics] instance should not be used after this call.
+  void close();
 }
 
 enum AnalyticsOpt {
@@ -313,6 +319,9 @@ class AnalyticsMock implements Analytics {
   @override
   Future waitForLastPing({Duration timeout}) => new Future.value();
 
+  @override
+  void close() {}
+
   Future _log(String hitType, Map m) {
     if (logCalls) {
       print('analytics: ${hitType} ${m}');

pubspec.yaml

@@ -3,7 +3,7 @@
 # BSD-style license that can be found in the LICENSE file.
 
 name: usage
-version: 3.2.0+1
+version: 3.3.0
 description: A Google Analytics wrapper for both command-line, web, and Flutter apps.
 homepage: https://github.com/dart-lang/usage
 author: Dart Team <misc@dartlang.org>

readme.md

@@ -52,9 +52,15 @@ have completed, or until the specified duration has elapsed. So, CLI apps can do
 something like:
 
 ```dart
-analytics.waitForLastPing(timeout: new Duration(milliseconds: 500)).then((_) {
-  exit(0);
-});
+await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200));
+analytics.close();
+```
+
+or:
+
+```dart
+await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200));
+exit(0);
 ```
 
 ## Using the API

test/all.dart

@@ -5,15 +5,15 @@
 library usage.all_test;
 
 import 'hit_types_test.dart' as hit_types_test;
-import 'usage_test.dart' as usage_test;
-import 'usage_impl_test.dart' as usage_impl_test;
 import 'usage_impl_io_test.dart' as usage_impl_io_test;
+import 'usage_impl_test.dart' as usage_impl_test;
+import 'usage_test.dart' as usage_test;
 import 'uuid_test.dart' as uuid_test;
 
 void main() {
   hit_types_test.defineTests();
-  usage_test.defineTests();
-  usage_impl_test.defineTests();
   usage_impl_io_test.defineTests();
+  usage_impl_test.defineTests();
+  usage_test.defineTests();
   uuid_test.defineTests();
 }

test/src/common.dart

@@ -57,4 +57,7 @@ class MockPostHandler extends PostHandler {
   }
 
   Map<String, dynamic> get last => sentValues.last;
+
+  @override
+  void close() {}
 }

test/web_test.dart

@@ -6,6 +6,7 @@
 library usage.web_test;
 
 import 'dart:async';
+import 'dart:html';
 
 import 'package:test/test.dart';
 import 'package:usage/src/usage_impl_html.dart';
@@ -61,7 +62,7 @@ void defineWebTests() {
 class MockRequestor {
   int sendCount = 0;
 
-  Future request(String url, {String method, String sendData}) {
+  Future<HttpRequest> request(String url, {String method, sendData}) {
     expect(url, isNotEmpty);
     expect(method, isNotEmpty);
     expect(sendData, isNotEmpty);