1
// Copyright 2013 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 Basic strippable logging definitions.
17
 * @see http://go/closurelogging
18
 *
19
 * @author [email protected] (John Lenz)
20
 */
21

22
goog.provide('goog.log');
23
goog.provide('goog.log.Level');
24
goog.provide('goog.log.LogRecord');
25
goog.provide('goog.log.Logger');
26

27
goog.require('goog.debug');
28
goog.require('goog.debug.LogManager');
29
goog.require('goog.debug.LogRecord');
30
goog.require('goog.debug.Logger');
31

32

33
/** @define {boolean} Whether logging is enabled. */
34
goog.define('goog.log.ENABLED', goog.debug.LOGGING_ENABLED);
35

36

37
/** @const {string} */
38
goog.log.ROOT_LOGGER_NAME = goog.debug.Logger.ROOT_LOGGER_NAME;
39

40

41

42
/**
43
 * @constructor
44
 * @final
45
 */
46
goog.log.Logger = goog.debug.Logger;
47

48

49

50
/**
51
 * @constructor
52
 * @final
53
 */
54
goog.log.Level = goog.debug.Logger.Level;
55

56

57

58
/**
59
 * @constructor
60
 * @final
61
 */
62
goog.log.LogRecord = goog.debug.LogRecord;
63

64

65
/**
66
 * Finds or creates a logger for a named subsystem. If a logger has already been
67
 * created with the given name it is returned. Otherwise a new logger is
68
 * created. If a new logger is created its log level will be configured based
69
 * on the goog.debug.LogManager configuration and it will configured to also
70
 * send logging output to its parent's handlers.
71
 * @see goog.debug.LogManager
72
 *
73
 * @param {string} name A name for the logger. This should be a dot-separated
74
 *     name and should normally be based on the package name or class name of
75
 *     the subsystem, such as goog.net.BrowserChannel.
76
 * @param {goog.log.Level=} opt_level If provided, override the
77
 *     default logging level with the provided level.
78
 * @return {goog.log.Logger} The named logger or null if logging is disabled.
79
 */
80
goog.log.getLogger = function(name, opt_level) {
81
  if (goog.log.ENABLED) {
82
    var logger = goog.debug.LogManager.getLogger(name);
83
    if (opt_level && logger) {
84
      logger.setLevel(opt_level);
85
    }
86
    return logger;
87
  } else {
88
    return null;
89
  }
90
};
91

92

93
// TODO(johnlenz): try to tighten the types to these functions.
94
/**
95
 * Adds a handler to the logger. This doesn't use the event system because
96
 * we want to be able to add logging to the event system.
97
 * @param {goog.log.Logger} logger
98
 * @param {Function} handler Handler function to add.
99
 */
100
goog.log.addHandler = function(logger, handler) {
101
  if (goog.log.ENABLED && logger) {
102
    logger.addHandler(handler);
103
  }
104
};
105

106

107
/**
108
 * Removes a handler from the logger. This doesn't use the event system because
109
 * we want to be able to add logging to the event system.
110
 * @param {goog.log.Logger} logger
111
 * @param {Function} handler Handler function to remove.
112
 * @return {boolean} Whether the handler was removed.
113
 */
114
goog.log.removeHandler = function(logger, handler) {
115
  if (goog.log.ENABLED && logger) {
116
    return logger.removeHandler(handler);
117
  } else {
118
    return false;
119
  }
120
};
121

122

123
/**
124
 * Logs a message. If the logger is currently enabled for the
125
 * given message level then the given message is forwarded to all the
126
 * registered output Handler objects.
127
 * @param {goog.log.Logger} logger
128
 * @param {goog.log.Level} level One of the level identifiers.
129
 * @param {goog.debug.Loggable} msg The message to log.
130
 * @param {Error|Object=} opt_exception An exception associated with the
131
 *     message.
132
 */
133
goog.log.log = function(logger, level, msg, opt_exception) {
134
  if (goog.log.ENABLED && logger) {
135
    logger.log(level, msg, opt_exception);
136
  }
137
};
138

139

140
/**
141
 * Logs a message at the Level.SEVERE level.
142
 * If the logger is currently enabled for the given message level then the
143
 * given message is forwarded to all the registered output Handler objects.
144
 * @param {goog.log.Logger} logger
145
 * @param {goog.debug.Loggable} msg The message to log.
146
 * @param {Error=} opt_exception An exception associated with the message.
147
 */
148
goog.log.error = function(logger, msg, opt_exception) {
149
  if (goog.log.ENABLED && logger) {
150
    logger.severe(msg, opt_exception);
151
  }
152
};
153

154

155
/**
156
 * Logs a message at the Level.WARNING level.
157
 * If the logger is currently enabled for the given message level then the
158
 * given message is forwarded to all the registered output Handler objects.
159
 * @param {goog.log.Logger} logger
160
 * @param {goog.debug.Loggable} msg The message to log.
161
 * @param {Error=} opt_exception An exception associated with the message.
162
 */
163
goog.log.warning = function(logger, msg, opt_exception) {
164
  if (goog.log.ENABLED && logger) {
165
    logger.warning(msg, opt_exception);
166
  }
167
};
168

169

170
/**
171
 * Logs a message at the Level.INFO level.
172
 * If the logger is currently enabled for the given message level then the
173
 * given message is forwarded to all the registered output Handler objects.
174
 * @param {goog.log.Logger} logger
175
 * @param {goog.debug.Loggable} msg The message to log.
176
 * @param {Error=} opt_exception An exception associated with the message.
177
 */
178
goog.log.info = function(logger, msg, opt_exception) {
179
  if (goog.log.ENABLED && logger) {
180
    logger.info(msg, opt_exception);
181
  }
182
};
183

184

185
/**
186
 * Logs a message at the Level.Fine level.
187
 * If the logger is currently enabled for the given message level then the
188
 * given message is forwarded to all the registered output Handler objects.
189
 * @param {goog.log.Logger} logger
190
 * @param {goog.debug.Loggable} msg The message to log.
191
 * @param {Error=} opt_exception An exception associated with the message.
192
 */
193
goog.log.fine = function(logger, msg, opt_exception) {
194
  if (goog.log.ENABLED && logger) {
195
    logger.fine(msg, opt_exception);
196
  }
197
};
198

199