lib/goog/log/log.js

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 johnlenz@google.com (John Lenz)
20 */
21
22goog.provide('goog.log');
23goog.provide('goog.log.Level');
24goog.provide('goog.log.LogRecord');
25goog.provide('goog.log.Logger');
26
27goog.require('goog.debug');
28goog.require('goog.debug.LogManager');
29goog.require('goog.debug.LogRecord');
30goog.require('goog.debug.Logger');
31
32
33/** @define {boolean} Whether logging is enabled. */
34goog.define('goog.log.ENABLED', goog.debug.LOGGING_ENABLED);
35
36
37/** @const */
38goog.log.ROOT_LOGGER_NAME = goog.debug.Logger.ROOT_LOGGER_NAME;
39
40
41
42/**
43 * @constructor
44 * @final
45 */
46goog.log.Logger = goog.debug.Logger;
47
48
49
50/**
51 * @constructor
52 * @final
53 */
54goog.log.Level = goog.debug.Logger.Level;
55
56
57
58/**
59 * @constructor
60 * @final
61 */
62goog.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 */
80goog.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 */
100goog.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 */
114goog.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 */
133goog.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 */
148goog.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 */
163goog.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 */
178goog.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 */
193goog.log.fine = function(logger, msg, opt_exception) {
194 if (goog.log.ENABLED && logger) {
195 logger.fine(msg, opt_exception);
196 }
197};