# 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 |
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 */
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 | };