1
// Copyright 2006 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Definition of the Logger class. Please minimize dependencies
17
 * this file has on other closure classes as any dependency it takes won't be
18
 * able to use the logging infrastructure.
19
 *
20
 * @see ../demos/debug.html
21
 */
22

23
goog.provide('goog.debug.LogManager');
24
goog.provide('goog.debug.Loggable');
25
goog.provide('goog.debug.Logger');
26
goog.provide('goog.debug.Logger.Level');
27

28
goog.require('goog.array');
29
goog.require('goog.asserts');
30
goog.require('goog.debug');
31
goog.require('goog.debug.LogBuffer');
32
goog.require('goog.debug.LogRecord');
33

34

35
/**
36
 * A message value that can be handled by a Logger.
37
 *
38
 * Functions are treated like callbacks, but are only called when the event's
39
 * log level is enabled. This is useful for logging messages that are expensive
40
 * to construct.
41
 *
42
 * @typedef {string|function(): string}
43
 */
44
goog.debug.Loggable;
45

46

47

48
/**
49
 * The Logger is an object used for logging debug messages. Loggers are
50
 * normally named, using a hierarchical dot-separated namespace. Logger names
51
 * can be arbitrary strings, but they should normally be based on the package
52
 * name or class name of the logged component, such as goog.net.BrowserChannel.
53
 *
54
 * The Logger object is loosely based on the java class
55
 * java.util.logging.Logger. It supports different levels of filtering for
56
 * different loggers.
57
 *
58
 * The logger object should never be instantiated by application code. It
59
 * should always use the goog.debug.Logger.getLogger function.
60
 *
61
 * @constructor
62
 * @param {string} name The name of the Logger.
63
 * @final
64
 */
65
goog.debug.Logger = function(name) {
66
  /**
67
   * Name of the Logger. Generally a dot-separated namespace
68
   * @private {string}
69
   */
70
  this.name_ = name;
71

72
  /**
73
   * Parent Logger.
74
   * @private {goog.debug.Logger}
75
   */
76
  this.parent_ = null;
77

78
  /**
79
   * Level that this logger only filters above. Null indicates it should
80
   * inherit from the parent.
81
   * @private {goog.debug.Logger.Level}
82
   */
83
  this.level_ = null;
84

85
  /**
86
   * Map of children loggers. The keys are the leaf names of the children and
87
   * the values are the child loggers.
88
   * @private {Object}
89
   */
90
  this.children_ = null;
91

92
  /**
93
   * Handlers that are listening to this logger.
94
   * @private {Array<Function>}
95
   */
96
  this.handlers_ = null;
97
};
98

99

100
/** @const */
101
goog.debug.Logger.ROOT_LOGGER_NAME = '';
102

103

104
/**
105
 * @define {boolean} Toggles whether loggers other than the root logger can have
106
 *     log handlers attached to them and whether they can have their log level
107
 *     set. Logging is a bit faster when this is set to false.
108
 */
109
goog.define('goog.debug.Logger.ENABLE_HIERARCHY', true);
110

111

112
if (!goog.debug.Logger.ENABLE_HIERARCHY) {
113
  /**
114
   * @type {!Array<Function>}
115
   * @private
116
   */
117
  goog.debug.Logger.rootHandlers_ = [];
118

119

120
  /**
121
   * @type {goog.debug.Logger.Level}
122
   * @private
123
   */
124
  goog.debug.Logger.rootLevel_;
125
}
126

127

128

129
/**
130
 * The Level class defines a set of standard logging levels that
131
 * can be used to control logging output.  The logging Level objects
132
 * are ordered and are specified by ordered integers.  Enabling logging
133
 * at a given level also enables logging at all higher levels.
134
 * <p>
135
 * Clients should normally use the predefined Level constants such
136
 * as Level.SEVERE.
137
 * <p>
138
 * The levels in descending order are:
139
 * <ul>
140
 * <li>SEVERE (highest value)
141
 * <li>WARNING
142
 * <li>INFO
143
 * <li>CONFIG
144
 * <li>FINE
145
 * <li>FINER
146
 * <li>FINEST  (lowest value)
147
 * </ul>
148
 * In addition there is a level OFF that can be used to turn
149
 * off logging, and a level ALL that can be used to enable
150
 * logging of all messages.
151
 *
152
 * @param {string} name The name of the level.
153
 * @param {number} value The numeric value of the level.
154
 * @constructor
155
 * @final
156
 */
157
goog.debug.Logger.Level = function(name, value) {
158
  /**
159
   * The name of the level
160
   * @type {string}
161
   */
162
  this.name = name;
163

164
  /**
165
   * The numeric value of the level
166
   * @type {number}
167
   */
168
  this.value = value;
169
};
170

171

172
/**
173
 * @return {string} String representation of the logger level.
174
 * @override
175
 */
176
goog.debug.Logger.Level.prototype.toString = function() {
177
  return this.name;
178
};
179

180

181
/**
182
 * OFF is a special level that can be used to turn off logging.
183
 * This level is initialized to <CODE>Infinity</CODE>.
184
 * @type {!goog.debug.Logger.Level}
185
 */
186
goog.debug.Logger.Level.OFF = new goog.debug.Logger.Level('OFF', Infinity);
187

188

189
/**
190
 * SHOUT is a message level for extra debugging loudness.
191
 * This level is initialized to <CODE>1200</CODE>.
192
 * @type {!goog.debug.Logger.Level}
193
 */
194
goog.debug.Logger.Level.SHOUT = new goog.debug.Logger.Level('SHOUT', 1200);
195

196

197
/**
198
 * SEVERE is a message level indicating a serious failure.
199
 * This level is initialized to <CODE>1000</CODE>.
200
 * @type {!goog.debug.Logger.Level}
201
 */
202
goog.debug.Logger.Level.SEVERE = new goog.debug.Logger.Level('SEVERE', 1000);
203

204

205
/**
206
 * WARNING is a message level indicating a potential problem.
207
 * This level is initialized to <CODE>900</CODE>.
208
 * @type {!goog.debug.Logger.Level}
209
 */
210
goog.debug.Logger.Level.WARNING = new goog.debug.Logger.Level('WARNING', 900);
211

212

213
/**
214
 * INFO is a message level for informational messages.
215
 * This level is initialized to <CODE>800</CODE>.
216
 * @type {!goog.debug.Logger.Level}
217
 */
218
goog.debug.Logger.Level.INFO = new goog.debug.Logger.Level('INFO', 800);
219

220

221
/**
222
 * CONFIG is a message level for static configuration messages.
223
 * This level is initialized to <CODE>700</CODE>.
224
 * @type {!goog.debug.Logger.Level}
225
 */
226
goog.debug.Logger.Level.CONFIG = new goog.debug.Logger.Level('CONFIG', 700);
227

228

229
/**
230
 * FINE is a message level providing tracing information.
231
 * This level is initialized to <CODE>500</CODE>.
232
 * @type {!goog.debug.Logger.Level}
233
 */
234
goog.debug.Logger.Level.FINE = new goog.debug.Logger.Level('FINE', 500);
235

236

237
/**
238
 * FINER indicates a fairly detailed tracing message.
239
 * This level is initialized to <CODE>400</CODE>.
240
 * @type {!goog.debug.Logger.Level}
241
 */
242
goog.debug.Logger.Level.FINER = new goog.debug.Logger.Level('FINER', 400);
243

244
/**
245
 * FINEST indicates a highly detailed tracing message.
246
 * This level is initialized to <CODE>300</CODE>.
247
 * @type {!goog.debug.Logger.Level}
248
 */
249

250
goog.debug.Logger.Level.FINEST = new goog.debug.Logger.Level('FINEST', 300);
251

252

253
/**
254
 * ALL indicates that all messages should be logged.
255
 * This level is initialized to <CODE>0</CODE>.
256
 * @type {!goog.debug.Logger.Level}
257
 */
258
goog.debug.Logger.Level.ALL = new goog.debug.Logger.Level('ALL', 0);
259

260

261
/**
262
 * The predefined levels.
263
 * @type {!Array<!goog.debug.Logger.Level>}
264
 * @final
265
 */
266
goog.debug.Logger.Level.PREDEFINED_LEVELS = [
267
  goog.debug.Logger.Level.OFF, goog.debug.Logger.Level.SHOUT,
268
  goog.debug.Logger.Level.SEVERE, goog.debug.Logger.Level.WARNING,
269
  goog.debug.Logger.Level.INFO, goog.debug.Logger.Level.CONFIG,
270
  goog.debug.Logger.Level.FINE, goog.debug.Logger.Level.FINER,
271
  goog.debug.Logger.Level.FINEST, goog.debug.Logger.Level.ALL
272
];
273

274

275
/**
276
 * A lookup map used to find the level object based on the name or value of
277
 * the level object.
278
 * @type {Object}
279
 * @private
280
 */
281
goog.debug.Logger.Level.predefinedLevelsCache_ = null;
282

283

284
/**
285
 * Creates the predefined levels cache and populates it.
286
 * @private
287
 */
288
goog.debug.Logger.Level.createPredefinedLevelsCache_ = function() {
289
  goog.debug.Logger.Level.predefinedLevelsCache_ = {};
290
  for (var i = 0, level; level = goog.debug.Logger.Level.PREDEFINED_LEVELS[i];
291
       i++) {
292
    goog.debug.Logger.Level.predefinedLevelsCache_[level.value] = level;
293
    goog.debug.Logger.Level.predefinedLevelsCache_[level.name] = level;
294
  }
295
};
296

297

298
/**
299
 * Gets the predefined level with the given name.
300
 * @param {string} name The name of the level.
301
 * @return {goog.debug.Logger.Level} The level, or null if none found.
302
 */
303
goog.debug.Logger.Level.getPredefinedLevel = function(name) {
304
  if (!goog.debug.Logger.Level.predefinedLevelsCache_) {
305
    goog.debug.Logger.Level.createPredefinedLevelsCache_();
306
  }
307

308
  return goog.debug.Logger.Level.predefinedLevelsCache_[name] || null;
309
};
310

311

312
/**
313
 * Gets the highest predefined level <= #value.
314
 * @param {number} value Level value.
315
 * @return {goog.debug.Logger.Level} The level, or null if none found.
316
 */
317
goog.debug.Logger.Level.getPredefinedLevelByValue = function(value) {
318
  if (!goog.debug.Logger.Level.predefinedLevelsCache_) {
319
    goog.debug.Logger.Level.createPredefinedLevelsCache_();
320
  }
321

322
  if (value in /** @type {!Object} */ (
323
          goog.debug.Logger.Level.predefinedLevelsCache_)) {
324
    return goog.debug.Logger.Level.predefinedLevelsCache_[value];
325
  }
326

327
  for (var i = 0; i < goog.debug.Logger.Level.PREDEFINED_LEVELS.length; ++i) {
328
    var level = goog.debug.Logger.Level.PREDEFINED_LEVELS[i];
329
    if (level.value <= value) {
330
      return level;
331
    }
332
  }
333
  return null;
334
};
335

336

337
/**
338
 * Finds or creates a logger for a named subsystem. If a logger has already been
339
 * created with the given name it is returned. Otherwise a new logger is
340
 * created. If a new logger is created its log level will be configured based
341
 * on the LogManager configuration and it will configured to also send logging
342
 * output to its parent's handlers. It will be registered in the LogManager
343
 * global namespace.
344
 *
345
 * @param {string} name A name for the logger. This should be a dot-separated
346
 * name and should normally be based on the package name or class name of the
347
 * subsystem, such as goog.net.BrowserChannel.
348
 * @return {!goog.debug.Logger} The named logger.
349
 * @deprecated use {@link goog.log} instead.
350
 */
351
goog.debug.Logger.getLogger = function(name) {
352
  return goog.debug.LogManager.getLogger(name);
353
};
354

355

356
/**
357
 * Logs a message to profiling tools, if available.
358
 * {@see https://developers.google.com/web-toolkit/speedtracer/logging-api}
359
 * {@see http://msdn.microsoft.com/en-us/library/dd433074(VS.85).aspx}
360
 * @param {string} msg The message to log.
361
 */
362
goog.debug.Logger.logToProfilers = function(msg) {
363
  // Using goog.global, as loggers might be used in window-less contexts.
364
  if (goog.global['console']) {
365
    if (goog.global['console']['timeStamp']) {
366
      // Logs a message to Firebug, Web Inspector, SpeedTracer, etc.
367
      goog.global['console']['timeStamp'](msg);
368
    } else if (goog.global['console']['markTimeline']) {
369
      // TODO(user): markTimeline is deprecated. Drop this else clause entirely
370
      // after Chrome M14 hits stable.
371
      goog.global['console']['markTimeline'](msg);
372
    }
373
  }
374

375
  if (goog.global['msWriteProfilerMark']) {
376
    // Logs a message to the Microsoft profiler
377
    goog.global['msWriteProfilerMark'](msg);
378
  }
379
};
380

381

382
/**
383
 * Gets the name of this logger.
384
 * @return {string} The name of this logger.
385
 */
386
goog.debug.Logger.prototype.getName = function() {
387
  return this.name_;
388
};
389

390

391
/**
392
 * Adds a handler to the logger. This doesn't use the event system because
393
 * we want to be able to add logging to the event system.
394
 * @param {Function} handler Handler function to add.
395
 */
396
goog.debug.Logger.prototype.addHandler = function(handler) {
397
  if (goog.debug.LOGGING_ENABLED) {
398
    if (goog.debug.Logger.ENABLE_HIERARCHY) {
399
      if (!this.handlers_) {
400
        this.handlers_ = [];
401
      }
402
      this.handlers_.push(handler);
403
    } else {
404
      goog.asserts.assert(
405
          !this.name_, 'Cannot call addHandler on a non-root logger when ' +
406
              'goog.debug.Logger.ENABLE_HIERARCHY is false.');
407
      goog.debug.Logger.rootHandlers_.push(handler);
408
    }
409
  }
410
};
411

412

413
/**
414
 * Removes a handler from the logger. This doesn't use the event system because
415
 * we want to be able to add logging to the event system.
416
 * @param {Function} handler Handler function to remove.
417
 * @return {boolean} Whether the handler was removed.
418
 */
419
goog.debug.Logger.prototype.removeHandler = function(handler) {
420
  if (goog.debug.LOGGING_ENABLED) {
421
    var handlers = goog.debug.Logger.ENABLE_HIERARCHY ?
422
        this.handlers_ :
423
        goog.debug.Logger.rootHandlers_;
424
    return !!handlers && goog.array.remove(handlers, handler);
425
  } else {
426
    return false;
427
  }
428
};
429

430

431
/**
432
 * Returns the parent of this logger.
433
 * @return {goog.debug.Logger} The parent logger or null if this is the root.
434
 */
435
goog.debug.Logger.prototype.getParent = function() {
436
  return this.parent_;
437
};
438

439

440
/**
441
 * Returns the children of this logger as a map of the child name to the logger.
442
 * @return {!Object} The map where the keys are the child leaf names and the
443
 *     values are the Logger objects.
444
 */
445
goog.debug.Logger.prototype.getChildren = function() {
446
  if (!this.children_) {
447
    this.children_ = {};
448
  }
449
  return this.children_;
450
};
451

452

453
/**
454
 * Set the log level specifying which message levels will be logged by this
455
 * logger. Message levels lower than this value will be discarded.
456
 * The level value Level.OFF can be used to turn off logging. If the new level
457
 * is null, it means that this node should inherit its level from its nearest
458
 * ancestor with a specific (non-null) level value.
459
 *
460
 * @param {goog.debug.Logger.Level} level The new level.
461
 */
462
goog.debug.Logger.prototype.setLevel = function(level) {
463
  if (goog.debug.LOGGING_ENABLED) {
464
    if (goog.debug.Logger.ENABLE_HIERARCHY) {
465
      this.level_ = level;
466
    } else {
467
      goog.asserts.assert(
468
          !this.name_, 'Cannot call setLevel() on a non-root logger when ' +
469
              'goog.debug.Logger.ENABLE_HIERARCHY is false.');
470
      goog.debug.Logger.rootLevel_ = level;
471
    }
472
  }
473
};
474

475

476
/**
477
 * Gets the log level specifying which message levels will be logged by this
478
 * logger. Message levels lower than this value will be discarded.
479
 * The level value Level.OFF can be used to turn off logging. If the level
480
 * is null, it means that this node should inherit its level from its nearest
481
 * ancestor with a specific (non-null) level value.
482
 *
483
 * @return {goog.debug.Logger.Level} The level.
484
 */
485
goog.debug.Logger.prototype.getLevel = function() {
486
  return goog.debug.LOGGING_ENABLED ? this.level_ : goog.debug.Logger.Level.OFF;
487
};
488

489

490
/**
491
 * Returns the effective level of the logger based on its ancestors' levels.
492
 * @return {goog.debug.Logger.Level} The level.
493
 */
494
goog.debug.Logger.prototype.getEffectiveLevel = function() {
495
  if (!goog.debug.LOGGING_ENABLED) {
496
    return goog.debug.Logger.Level.OFF;
497
  }
498

499
  if (!goog.debug.Logger.ENABLE_HIERARCHY) {
500
    return goog.debug.Logger.rootLevel_;
501
  }
502
  if (this.level_) {
503
    return this.level_;
504
  }
505
  if (this.parent_) {
506
    return this.parent_.getEffectiveLevel();
507
  }
508
  goog.asserts.fail('Root logger has no level set.');
509
  return null;
510
};
511

512

513
/**
514
 * Checks if a message of the given level would actually be logged by this
515
 * logger. This check is based on the Loggers effective level, which may be
516
 * inherited from its parent.
517
 * @param {goog.debug.Logger.Level} level The level to check.
518
 * @return {boolean} Whether the message would be logged.
519
 */
520
goog.debug.Logger.prototype.isLoggable = function(level) {
521
  return goog.debug.LOGGING_ENABLED &&
522
      level.value >= this.getEffectiveLevel().value;
523
};
524

525

526
/**
527
 * Logs a message. If the logger is currently enabled for the
528
 * given message level then the given message is forwarded to all the
529
 * registered output Handler objects.
530
 * @param {goog.debug.Logger.Level} level One of the level identifiers.
531
 * @param {goog.debug.Loggable} msg The message to log.
532
 * @param {Error|Object=} opt_exception An exception associated with the
533
 *     message.
534
 */
535
goog.debug.Logger.prototype.log = function(level, msg, opt_exception) {
536
  // java caches the effective level, not sure it's necessary here
537
  if (goog.debug.LOGGING_ENABLED && this.isLoggable(level)) {
538
    // Message callbacks can be useful when a log message is expensive to build.
539
    if (goog.isFunction(msg)) {
540
      msg = msg();
541
    }
542

543
    this.doLogRecord_(this.getLogRecord(level, msg, opt_exception));
544
  }
545
};
546

547

548
/**
549
 * Creates a new log record and adds the exception (if present) to it.
550
 * @param {goog.debug.Logger.Level} level One of the level identifiers.
551
 * @param {string} msg The string message.
552
 * @param {Error|Object=} opt_exception An exception associated with the
553
 *     message.
554
 * @return {!goog.debug.LogRecord} A log record.
555
 * @suppress {es5Strict}
556
 */
557
goog.debug.Logger.prototype.getLogRecord = function(level, msg, opt_exception) {
558
  if (goog.debug.LogBuffer.isBufferingEnabled()) {
559
    var logRecord =
560
        goog.debug.LogBuffer.getInstance().addRecord(level, msg, this.name_);
561
  } else {
562
    logRecord = new goog.debug.LogRecord(level, String(msg), this.name_);
563
  }
564
  if (opt_exception) {
565
    logRecord.setException(opt_exception);
566
  }
567
  return logRecord;
568
};
569

570

571
/**
572
 * Logs a message at the Logger.Level.SHOUT level.
573
 * If the logger is currently enabled for the given message level then the
574
 * given message is forwarded to all the registered output Handler objects.
575
 * @param {goog.debug.Loggable} msg The message to log.
576
 * @param {Error=} opt_exception An exception associated with the message.
577
 */
578
goog.debug.Logger.prototype.shout = function(msg, opt_exception) {
579
  if (goog.debug.LOGGING_ENABLED) {
580
    this.log(goog.debug.Logger.Level.SHOUT, msg, opt_exception);
581
  }
582
};
583

584

585
/**
586
 * Logs a message at the Logger.Level.SEVERE level.
587
 * If the logger is currently enabled for the given message level then the
588
 * given message is forwarded to all the registered output Handler objects.
589
 * @param {goog.debug.Loggable} msg The message to log.
590
 * @param {Error=} opt_exception An exception associated with the message.
591
 */
592
goog.debug.Logger.prototype.severe = function(msg, opt_exception) {
593
  if (goog.debug.LOGGING_ENABLED) {
594
    this.log(goog.debug.Logger.Level.SEVERE, msg, opt_exception);
595
  }
596
};
597

598

599
/**
600
 * Logs a message at the Logger.Level.WARNING level.
601
 * If the logger is currently enabled for the given message level then the
602
 * given message is forwarded to all the registered output Handler objects.
603
 * @param {goog.debug.Loggable} msg The message to log.
604
 * @param {Error=} opt_exception An exception associated with the message.
605
 */
606
goog.debug.Logger.prototype.warning = function(msg, opt_exception) {
607
  if (goog.debug.LOGGING_ENABLED) {
608
    this.log(goog.debug.Logger.Level.WARNING, msg, opt_exception);
609
  }
610
};
611

612

613
/**
614
 * Logs a message at the Logger.Level.INFO level.
615
 * If the logger is currently enabled for the given message level then the
616
 * given message is forwarded to all the registered output Handler objects.
617
 * @param {goog.debug.Loggable} msg The message to log.
618
 * @param {Error=} opt_exception An exception associated with the message.
619
 */
620
goog.debug.Logger.prototype.info = function(msg, opt_exception) {
621
  if (goog.debug.LOGGING_ENABLED) {
622
    this.log(goog.debug.Logger.Level.INFO, msg, opt_exception);
623
  }
624
};
625

626

627
/**
628
 * Logs a message at the Logger.Level.CONFIG level.
629
 * If the logger is currently enabled for the given message level then the
630
 * given message is forwarded to all the registered output Handler objects.
631
 * @param {goog.debug.Loggable} msg The message to log.
632
 * @param {Error=} opt_exception An exception associated with the message.
633
 */
634
goog.debug.Logger.prototype.config = function(msg, opt_exception) {
635
  if (goog.debug.LOGGING_ENABLED) {
636
    this.log(goog.debug.Logger.Level.CONFIG, msg, opt_exception);
637
  }
638
};
639

640

641
/**
642
 * Logs a message at the Logger.Level.FINE level.
643
 * If the logger is currently enabled for the given message level then the
644
 * given message is forwarded to all the registered output Handler objects.
645
 * @param {goog.debug.Loggable} msg The message to log.
646
 * @param {Error=} opt_exception An exception associated with the message.
647
 */
648
goog.debug.Logger.prototype.fine = function(msg, opt_exception) {
649
  if (goog.debug.LOGGING_ENABLED) {
650
    this.log(goog.debug.Logger.Level.FINE, msg, opt_exception);
651
  }
652
};
653

654

655
/**
656
 * Logs a message at the Logger.Level.FINER level.
657
 * If the logger is currently enabled for the given message level then the
658
 * given message is forwarded to all the registered output Handler objects.
659
 * @param {goog.debug.Loggable} msg The message to log.
660
 * @param {Error=} opt_exception An exception associated with the message.
661
 */
662
goog.debug.Logger.prototype.finer = function(msg, opt_exception) {
663
  if (goog.debug.LOGGING_ENABLED) {
664
    this.log(goog.debug.Logger.Level.FINER, msg, opt_exception);
665
  }
666
};
667

668

669
/**
670
 * Logs a message at the Logger.Level.FINEST level.
671
 * If the logger is currently enabled for the given message level then the
672
 * given message is forwarded to all the registered output Handler objects.
673
 * @param {goog.debug.Loggable} msg The message to log.
674
 * @param {Error=} opt_exception An exception associated with the message.
675
 */
676
goog.debug.Logger.prototype.finest = function(msg, opt_exception) {
677
  if (goog.debug.LOGGING_ENABLED) {
678
    this.log(goog.debug.Logger.Level.FINEST, msg, opt_exception);
679
  }
680
};
681

682

683
/**
684
 * Logs a LogRecord. If the logger is currently enabled for the
685
 * given message level then the given message is forwarded to all the
686
 * registered output Handler objects.
687
 * @param {goog.debug.LogRecord} logRecord A log record to log.
688
 */
689
goog.debug.Logger.prototype.logRecord = function(logRecord) {
690
  if (goog.debug.LOGGING_ENABLED && this.isLoggable(logRecord.getLevel())) {
691
    this.doLogRecord_(logRecord);
692
  }
693
};
694

695

696
/**
697
 * Logs a LogRecord.
698
 * @param {goog.debug.LogRecord} logRecord A log record to log.
699
 * @private
700
 */
701
goog.debug.Logger.prototype.doLogRecord_ = function(logRecord) {
702
  goog.debug.Logger.logToProfilers('log:' + logRecord.getMessage());
703
  if (goog.debug.Logger.ENABLE_HIERARCHY) {
704
    var target = this;
705
    while (target) {
706
      target.callPublish_(logRecord);
707
      target = target.getParent();
708
    }
709
  } else {
710
    for (var i = 0, handler; handler = goog.debug.Logger.rootHandlers_[i++];) {
711
      handler(logRecord);
712
    }
713
  }
714
};
715

716

717
/**
718
 * Calls the handlers for publish.
719
 * @param {goog.debug.LogRecord} logRecord The log record to publish.
720
 * @private
721
 */
722
goog.debug.Logger.prototype.callPublish_ = function(logRecord) {
723
  if (this.handlers_) {
724
    for (var i = 0, handler; handler = this.handlers_[i]; i++) {
725
      handler(logRecord);
726
    }
727
  }
728
};
729

730

731
/**
732
 * Sets the parent of this logger. This is used for setting up the logger tree.
733
 * @param {goog.debug.Logger} parent The parent logger.
734
 * @private
735
 */
736
goog.debug.Logger.prototype.setParent_ = function(parent) {
737
  this.parent_ = parent;
738
};
739

740

741
/**
742
 * Adds a child to this logger. This is used for setting up the logger tree.
743
 * @param {string} name The leaf name of the child.
744
 * @param {goog.debug.Logger} logger The child logger.
745
 * @private
746
 */
747
goog.debug.Logger.prototype.addChild_ = function(name, logger) {
748
  this.getChildren()[name] = logger;
749
};
750

751

752
/**
753
 * There is a single global LogManager object that is used to maintain a set of
754
 * shared state about Loggers and log services. This is loosely based on the
755
 * java class java.util.logging.LogManager.
756
 * @const
757
 */
758
goog.debug.LogManager = {};
759

760

761
/**
762
 * Map of logger names to logger objects.
763
 *
764
 * @type {!Object<string, !goog.debug.Logger>}
765
 * @private
766
 */
767
goog.debug.LogManager.loggers_ = {};
768

769

770
/**
771
 * The root logger which is the root of the logger tree.
772
 * @type {goog.debug.Logger}
773
 * @private
774
 */
775
goog.debug.LogManager.rootLogger_ = null;
776

777

778
/**
779
 * Initializes the LogManager if not already initialized.
780
 */
781
goog.debug.LogManager.initialize = function() {
782
  if (!goog.debug.LogManager.rootLogger_) {
783
    goog.debug.LogManager.rootLogger_ =
784
        new goog.debug.Logger(goog.debug.Logger.ROOT_LOGGER_NAME);
785
    goog.debug.LogManager.loggers_[goog.debug.Logger.ROOT_LOGGER_NAME] =
786
        goog.debug.LogManager.rootLogger_;
787
    goog.debug.LogManager.rootLogger_.setLevel(goog.debug.Logger.Level.CONFIG);
788
  }
789
};
790

791

792
/**
793
 * Returns all the loggers.
794
 * @return {!Object<string, !goog.debug.Logger>} Map of logger names to logger
795
 *     objects.
796
 */
797
goog.debug.LogManager.getLoggers = function() {
798
  return goog.debug.LogManager.loggers_;
799
};
800

801

802
/**
803
 * Returns the root of the logger tree namespace, the logger with the empty
804
 * string as its name.
805
 *
806
 * @return {!goog.debug.Logger} The root logger.
807
 */
808
goog.debug.LogManager.getRoot = function() {
809
  goog.debug.LogManager.initialize();
810
  return /** @type {!goog.debug.Logger} */ (goog.debug.LogManager.rootLogger_);
811
};
812

813

814
/**
815
 * Finds a named logger.
816
 *
817
 * @param {string} name A name for the logger. This should be a dot-separated
818
 * name and should normally be based on the package name or class name of the
819
 * subsystem, such as goog.net.BrowserChannel.
820
 * @return {!goog.debug.Logger} The named logger.
821
 */
822
goog.debug.LogManager.getLogger = function(name) {
823
  goog.debug.LogManager.initialize();
824
  var ret = goog.debug.LogManager.loggers_[name];
825
  return ret || goog.debug.LogManager.createLogger_(name);
826
};
827

828

829
/**
830
 * Creates a function that can be passed to goog.debug.catchErrors. The function
831
 * will log all reported errors using the given logger.
832
 * @param {goog.debug.Logger=} opt_logger The logger to log the errors to.
833
 *     Defaults to the root logger.
834
 * @return {function(Object)} The created function.
835
 */
836
goog.debug.LogManager.createFunctionForCatchErrors = function(opt_logger) {
837
  return function(info) {
838
    var logger = opt_logger || goog.debug.LogManager.getRoot();
839
    logger.severe(
840
        'Error: ' + info.message + ' (' + info.fileName + ' @ Line: ' +
841
        info.line + ')');
842
  };
843
};
844

845

846
/**
847
 * Creates the named logger. Will also create the parents of the named logger
848
 * if they don't yet exist.
849
 * @param {string} name The name of the logger.
850
 * @return {!goog.debug.Logger} The named logger.
851
 * @private
852
 */
853
goog.debug.LogManager.createLogger_ = function(name) {
854
  // find parent logger
855
  var logger = new goog.debug.Logger(name);
856
  if (goog.debug.Logger.ENABLE_HIERARCHY) {
857
    var lastDotIndex = name.lastIndexOf('.');
858
    var parentName = name.substr(0, lastDotIndex);
859
    var leafName = name.substr(lastDotIndex + 1);
860
    var parentLogger = goog.debug.LogManager.getLogger(parentName);
861

862
    // tell the parent about the child and the child about the parent
863
    parentLogger.addChild_(leafName, logger);
864
    logger.setParent_(parentLogger);
865
  }
866

867
  goog.debug.LogManager.loggers_[name] = logger;
868
  return logger;
869
};
870

871