pkg/logging: BREAKING: move to stream-based event model

pkg/logging/lib/logging.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * Provides APIs for debugging and error logging. This library introduces
  * abstractions similar to those used in other languages, such as the Closure JS
  * Logger and java.util.logging.Logger.
  */
 library logging;
 
+import 'dart:async';
+
+import 'package:meta/meta.dart';
+
 /**
  * Whether to allow fine-grain logging and configuration of loggers in a
  * hierarchy. When false, all logging is merged in the root logger.
  */
 bool hierarchicalLoggingEnabled = false;
 
 /**
  * Level for the root-logger. This will be the level of all loggers if
  * [hierarchicalLoggingEnabled] is false.
  */
@@ skipping 14 matching lines @@
 
   /** Parent of this logger in the hierarchy of loggers. */
   final Logger parent;
 
   /** Logging [Level] used for entries generated on this logger. */
   Level _level;
 
   /** Children in the hierarchy of loggers, indexed by their simple names. */
   Map<String, Logger> children;
 
   /** Handlers used to process log entries in this logger. */

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

fix comment

-  List<LoggerHandler> _handlers;
+  StreamController<LogRecord> _controller;
+
+  @deprecated

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

If you don't mind - let's remove this one here. We mainly need it in the public
APIs.

This technically shouldn't matter, but turns out that the dart_analyzer right
now is printing deprecation warnings that occur anywhere. Ideally it should only
report warnings when a user makes use of something deprecated from their
package, but currently the analyzer doesn't work that way today. By removing
this @deprecated here, I think we'll get less noise if someone calls the
analyzer from the command line.

Here is the relevant bug for the analyzer
https://code.google.com/p/dart/issues/detail?id=8691

+  Map<LoggerHandler, StreamSubscription> _deprecatedSubscriptions;
 
   /**
    * Singleton constructor. Calling `new Logger(name)` will return the same
    * actual instance whenever it is called with the same string name.
    */
   factory Logger(String name) {
     if (name.startsWith('.')) {
       throw new ArgumentError("name shouldn't start with a '.'");
     }
     if (_loggers == null) _loggers = <String, Logger>{};
@@ skipping 43 matching lines @@
             'change the level on a non-root logger.');
       }
       _rootLevel = value;
     }
   }
 
   /**
    * Returns an event manager for this [Logger]. You can listen for log messages
    * by adding a [LoggerHandler] to an event from the event manager, for
    * instance:
    *    logger.on.record.add((record) { ... });

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

+ let's add a small comment here, like:

Deprecated. Use [onRecord] instead. 

    */
+  @deprecated
   LoggerEvents get on => new LoggerEvents(this);
 
-  /** Adds a handler to listen whenever a log record is added to this logger. */
-  void _addHandler(LoggerHandler handler) {
-    if (hierarchicalLoggingEnabled || parent == null) {
-      if (_handlers == null) {
-        _handlers = new List<LoggerHandler>();
+  Stream<LogRecord> get onRecord => _getStream();
+
+  void clearListeners() {
+    if(hierarchicalLoggingEnabled || parent == null) {

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

style: add space after 'if' (same here below)

+      if(_controller != null) {
+        _controller.close();
+        _controller = null;
       }
-      _handlers.add(handler);
     } else {
-      root._addHandler(handler);
+      root.clearListeners();
     }
   }
 
-  /** Remove a previously added handler. */
-  void _removeHandler(LoggerHandler handler) {
-    if (hierarchicalLoggingEnabled || parent == null) {
-      if (_handlers == null) return;
-      int index = _handlers.indexOf(handler);
-      if (index != -1) _handlers.removeRange(index, 1);
-    } else {
-      root._removeHandler(handler);
-    }
-  }
-
-  /** Removes all handlers previously added to this logger. */
-  void _clearHandlers() {
-    if (hierarchicalLoggingEnabled || parent == null) {
-      _handlers = null;
-    } else {
-      root._clearHandlers();
-    }
-  }
-
   /** Whether a message for [value]'s level is loggable in this logger. */
   bool isLoggable(Level value) => (value >= level);
 
   /**
    * Adds a log record for a [message] at a particular [logLevel] if
    * `isLoggable(logLevel)` is true. Use this method to create log entries for
    * user-defined levels. To record a message at a predefined level (e.g.
    * [Level.INFO], [Level.WARNING], etc) you can use their specialized methods
    * instead (e.g. [info], [warning], etc).
    */
@@ skipping 30 matching lines @@
 
   /** Log message at level [Level.WARNING]. */
   void warning(String message) => log(Level.WARNING, message);
 
   /** Log message at level [Level.SEVERE]. */
   void severe(String message) => log(Level.SEVERE, message);
 
   /** Log message at level [Level.SHOUT]. */
   void shout(String message) => log(Level.SHOUT, message);
 
-  void _publish(LogRecord record) {
-    if (_handlers != null) {
-      _handlers.forEach((h) => h(record));
+  /** Adds a handler to listen whenever a log record is added to this logger. */

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

move this comment down to _addHandler?

+  Stream<LogRecord> _getStream() {
+    if (hierarchicalLoggingEnabled || parent == null) {
+      if (_controller == null) {
+        _controller = new StreamController<LogRecord>.broadcast();
+      }
+      return _controller.stream;
+    } else {
+      return root._getStream();
     }
   }
 
+  @deprecated

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

same here and all the ones below (the user had to use 'on' to get to these APIs,
so they will get a warning anyways).

+  void _addHandler(LoggerHandler handler) {
+    if(_deprecatedSubscriptions == null) {

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

style: missing space after 'if'

+      _deprecatedSubscriptions = new Map<LoggerHandler, StreamSubscription>();
+    }
+
+    final sub = onRecord.listen(handler);

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

style: even thought it's final, we use 'var' for these local variables. 

Given that this might fit in one line with the next line, consider just merging
them.

+    _deprecatedSubscriptions[handler] = sub;
+  }
+
+  @deprecated
+  void _removeHandler(LoggerHandler handler) {
+    if(_deprecatedSubscriptions != null) {

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

style: space after if (same below)

+      final sub = _deprecatedSubscriptions.remove(handler);

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

style: final -> var

+      if(sub != null) {
+        sub.cancel();
+      }
+      if(_deprecatedSubscriptions.isEmpty) {
+        _deprecatedSubscriptions = null;
+      }
+    }
+  }
+
+  void _publish(LogRecord record) {
+    if (_controller != null) {
+      _controller.add(record);
+    }
+  }
+
   /** Top-level root [Logger]. */
   static get root => new Logger('');
 
   /** All [Logger]s in the system. */
   static Map<String, Logger> _loggers;
 }
 
 
 /** Handler callback to process log entries as they are added to a [Logger]. */
+@deprecated
 typedef void LoggerHandler(LogRecord);
 
 
 /** Event manager for a [Logger] (holds events that a [Logger] can fire). */
+@deprecated
 class LoggerEvents {
   final Logger _logger;
 
   LoggerEvents(this._logger);
 
   /** Event fired when a log record is added to a [Logger]. */
   LoggerHandlerList get record => new LoggerHandlerList(_logger);
 }
 
 
 /** List of handlers that will be called on a logger event. */
+@deprecated

[Siggi Cherem (dart-lang), 2013/02/26 21:11:24]

I doubt anyone will allocate these types directly (other than the APIs that are
already marked deprecated above), but if that's the reason to add these, then
let's move them to the actual methods below ('add', 'remove', 'clear', and
'record')

That way our code in logger doesn't use any deprecated API. 

 class LoggerHandlerList {
   Logger _logger;
 
   LoggerHandlerList(this._logger);
 
   void add(LoggerHandler handler) => _logger._addHandler(handler);
   void remove(LoggerHandler handler) => _logger._removeHandler(handler);
-  void clear() => _logger._clearHandlers();
+  void clear() => _logger.clearListeners();
 }
 
 
 /**
  * [Level]s to control logging output. Logging can be enabled to include all
  * levels above certain [Level]. [Level]s are ordered using an integer
  * value [Level.value]. The predefined [Level] constants below are sorted as
  * follows (in descending order): [Level.SHOUT], [Level.SEVERE],
  * [Level.WARNING], [Level.INFO], [Level.CONFIG], [Level.FINE], [Level.FINER],
  * [Level.FINEST], and [Level.ALL].
@@ skipping 80 matching lines @@
 
   /** Associated exception message (if any) when recording errors messages. */
   String exceptionText;
 
   LogRecord(
       this.level, this.message, this.loggerName,
       [time, this.exception, this.exceptionText]) :
     this.time = (time == null) ? new DateTime.now() : time,
     this.sequenceNumber = LogRecord._nextNumber++;
 }