2 * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
27 package java.util.logging;
29 import java.util.HashMap;
31 import org.apidesign.bck2brwsr.core.JavaScriptBody;
34 * A Logger object is used to log messages for a specific
35 * system or application component. Loggers are normally named,
36 * using a hierarchical dot-separated namespace. Logger names
37 * can be arbitrary strings, but they should normally be based on
38 * the package name or class name of the logged component, such
39 * as java.net or javax.swing. In addition it is possible to create
40 * "anonymous" Loggers that are not stored in the Logger namespace.
42 * Logger objects may be obtained by calls on one of the getLogger
43 * factory methods. These will either create a new Logger or
44 * return a suitable existing Logger. It is important to note that
45 * the Logger returned by one of the {@code getLogger} factory methods
46 * may be garbage collected at any time if a strong reference to the
49 * Logging messages will be forwarded to registered Handler
50 * objects, which can forward the messages to a variety of
51 * destinations, including consoles, files, OS logs, etc.
53 * Each Logger keeps track of a "parent" Logger, which is its
54 * nearest existing ancestor in the Logger namespace.
56 * Each Logger has a "Level" associated with it. This reflects
57 * a minimum Level that this logger cares about. If a Logger's
58 * level is set to <tt>null</tt>, then its effective level is inherited
59 * from its parent, which may in turn obtain it recursively from its
60 * parent, and so on up the tree.
62 * The log level can be configured based on the properties from the
63 * logging configuration file, as described in the description
64 * of the LogManager class. However it may also be dynamically changed
65 * by calls on the Logger.setLevel method. If a logger's level is
66 * changed the change may also affect child loggers, since any child
67 * logger that has <tt>null</tt> as its level will inherit its
68 * effective level from its parent.
70 * On each logging call the Logger initially performs a cheap
71 * check of the request level (e.g., SEVERE or FINE) against the
72 * effective log level of the logger. If the request level is
73 * lower than the log level, the logging call returns immediately.
75 * After passing this initial (cheap) test, the Logger will allocate
76 * a LogRecord to describe the logging message. It will then call a
77 * Filter (if present) to do a more detailed check on whether the
78 * record should be published. If that passes it will then publish
79 * the LogRecord to its output Handlers. By default, loggers also
80 * publish to their parent's Handlers, recursively up the tree.
82 * Each Logger may have a ResourceBundle name associated with it.
83 * The named bundle will be used for localizing logging messages.
84 * If a Logger does not have its own ResourceBundle name, then
85 * it will inherit the ResourceBundle name from its parent,
86 * recursively up the tree.
88 * Most of the logger output methods take a "msg" argument. This
89 * msg argument may be either a raw value or a localization key.
90 * During formatting, if the logger has (or inherits) a localization
91 * ResourceBundle and if the ResourceBundle has a mapping for the msg
92 * string, then the msg string is replaced by the localized value.
93 * Otherwise the original msg string is used. Typically, formatters use
94 * java.text.MessageFormat style formatting to format parameters, so
95 * for example a format string "{0} {1}" would format two parameters
98 * When mapping ResourceBundle names to ResourceBundles, the Logger
99 * will first try to use the Thread's ContextClassLoader. If that
100 * is null it will try the SystemClassLoader instead. As a temporary
101 * transition feature in the initial implementation, if the Logger is
102 * unable to locate a ResourceBundle from the ContextClassLoader or
103 * SystemClassLoader the Logger will also search up the class stack
104 * and use successive calling ClassLoaders to try to locate a ResourceBundle.
105 * (This call stack search is to allow containers to transition to
106 * using ContextClassLoaders and is likely to be removed in future
109 * Formatting (including localization) is the responsibility of
110 * the output Handler, which will typically call a Formatter.
112 * Note that formatting need not occur synchronously. It may be delayed
113 * until a LogRecord is actually written to an external sink.
115 * The logging methods are grouped in five main categories:
118 * There are a set of "log" methods that take a log level, a message
119 * string, and optionally some parameters to the message string.
121 * There are a set of "logp" methods (for "log precise") that are
122 * like the "log" methods, but also take an explicit source class name
125 * There are a set of "logrb" method (for "log with resource bundle")
126 * that are like the "logp" method, but also take an explicit resource
127 * bundle name for use in localizing the log message.
129 * There are convenience methods for tracing method entries (the
130 * "entering" methods), method returns (the "exiting" methods) and
131 * throwing exceptions (the "throwing" methods).
133 * Finally, there are a set of convenience methods for use in the
134 * very simplest cases, when a developer simply wants to log a
135 * simple string at a given log level. These methods are named
136 * after the standard Level names ("severe", "warning", "info", etc.)
137 * and take a single argument, a message string.
140 * For the methods that do not take an explicit source name and
141 * method name, the Logging framework will make a "best effort"
142 * to determine which class and method called into the logging method.
143 * However, it is important to realize that this automatically inferred
144 * information may only be approximate (or may even be quite wrong!).
145 * Virtual machines are allowed to do extensive optimizations when
146 * JITing and may entirely remove stack frames, making it impossible
147 * to reliably locate the calling class and method.
149 * All methods on Logger are multi-thread safe.
151 * <b>Subclassing Information:</b> Note that a LogManager class may
152 * provide its own implementation of named Loggers for any point in
153 * the namespace. Therefore, any subclasses of Logger (unless they
154 * are implemented in conjunction with a new LogManager class) should
155 * take care to obtain a Logger instance from the LogManager class and
156 * should delegate operations such as "isLoggable" and "log(LogRecord)"
157 * to that instance. Note that in order to intercept all logging
158 * output, subclasses need only override the log(LogRecord) method.
159 * All the other logging methods are implemented as calls on this
160 * log(LogRecord) method.
166 public class Logger {
167 private static int offValue = Level.OFF.intValue();
168 private static final Map<String,Logger> ALL = new HashMap<>();
171 private volatile int levelValue; // current effective level value
172 private Level levelObject;
175 * GLOBAL_LOGGER_NAME is a name for the global logger.
179 public static final String GLOBAL_LOGGER_NAME = "global";
182 * Return global logger object with the name Logger.GLOBAL_LOGGER_NAME.
184 * @return global logger object
187 public static final Logger getGlobal() {
192 * The "global" Logger object is provided as a convenience to developers
193 * who are making casual use of the Logging package. Developers
194 * who are making serious use of the logging package (for example
195 * in products) should create and use their own Logger objects,
196 * with appropriate names, so that logging can be controlled on a
197 * suitable per-Logger granularity. Developers also need to keep a
198 * strong reference to their Logger objects to prevent them from
199 * being garbage collected.
201 * @deprecated Initialization of this field is prone to deadlocks.
202 * The field must be initialized by the Logger class initialization
203 * which may cause deadlocks with the LogManager class initialization.
204 * In such cases two class initialization wait for each other to complete.
205 * The preferred way to get the global logger object is via the call
206 * <code>Logger.getGlobal()</code>.
207 * For compatibility with old JDK versions where the
208 * <code>Logger.getGlobal()</code> is not available use the call
209 * <code>Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)</code>
210 * or <code>Logger.getLogger("global")</code>.
213 public static final Logger global = new Logger(GLOBAL_LOGGER_NAME);
216 * Protected method to construct a logger for a named subsystem.
218 * The logger will be initially configured with a null Level
219 * and with useParentHandlers set to true.
221 * @param name A name for the logger. This should
222 * be a dot-separated name and should normally
223 * be based on the package name or class name
224 * of the subsystem, such as java.net
225 * or javax.swing. It may be null for anonymous Loggers.
226 * @param resourceBundleName name of ResourceBundle to be used for localizing
227 * messages for this logger. May be null if none
228 * of the messages require localization.
229 * @throws MissingResourceException if the resourceBundleName is non-null and
230 * no corresponding resource can be found.
232 protected Logger(String name, String resourceBundleName) {
234 levelValue = Level.INFO.intValue();
237 // This constructor is used only to create the global Logger.
238 // It is needed to break a cyclic dependence between the LogManager
239 // and Logger static initializers causing deadlocks.
240 private Logger(String name) {
241 // The manager field is not initialized here.
243 levelValue = Level.INFO.intValue();
246 private void checkAccess() throws SecurityException {
247 throw new SecurityException();
251 * Find or create a logger for a named subsystem. If a logger has
252 * already been created with the given name it is returned. Otherwise
253 * a new logger is created.
255 * If a new logger is created its log level will be configured
256 * based on the LogManager configuration and it will configured
257 * to also send logging output to its parent's Handlers. It will
258 * be registered in the LogManager global namespace.
260 * Note: The LogManager may only retain a weak reference to the newly
261 * created Logger. It is important to understand that a previously
262 * created Logger with the given name may be garbage collected at any
263 * time if there is no strong reference to the Logger. In particular,
264 * this means that two back-to-back calls like
265 * {@code getLogger("MyLogger").log(...)} may use different Logger
266 * objects named "MyLogger" if there is no strong reference to the
267 * Logger named "MyLogger" elsewhere in the program.
269 * @param name A name for the logger. This should
270 * be a dot-separated name and should normally
271 * be based on the package name or class name
272 * of the subsystem, such as java.net
274 * @return a suitable Logger
275 * @throws NullPointerException if the name is null.
278 // Synchronization is not required here. All synchronization for
279 // adding a new Logger object is handled by LogManager.addLogger().
280 public static Logger getLogger(String name) {
281 return getLogger(name, null);
285 * Find or create a logger for a named subsystem. If a logger has
286 * already been created with the given name it is returned. Otherwise
287 * a new logger is created.
289 * If a new logger is created its log level will be configured
290 * based on the LogManager and it will configured to also send logging
291 * output to its parent's Handlers. It will be registered in
292 * the LogManager global namespace.
294 * Note: The LogManager may only retain a weak reference to the newly
295 * created Logger. It is important to understand that a previously
296 * created Logger with the given name may be garbage collected at any
297 * time if there is no strong reference to the Logger. In particular,
298 * this means that two back-to-back calls like
299 * {@code getLogger("MyLogger", ...).log(...)} may use different Logger
300 * objects named "MyLogger" if there is no strong reference to the
301 * Logger named "MyLogger" elsewhere in the program.
303 * If the named Logger already exists and does not yet have a
304 * localization resource bundle then the given resource bundle
305 * name is used. If the named Logger already exists and has
306 * a different resource bundle name then an IllegalArgumentException
309 * @param name A name for the logger. This should
310 * be a dot-separated name and should normally
311 * be based on the package name or class name
312 * of the subsystem, such as java.net
314 * @param resourceBundleName name of ResourceBundle to be used for localizing
315 * messages for this logger. May be <CODE>null</CODE> if none of
316 * the messages require localization.
317 * @return a suitable Logger
318 * @throws MissingResourceException if the resourceBundleName is non-null and
319 * no corresponding resource can be found.
320 * @throws IllegalArgumentException if the Logger already exists and uses
321 * a different resource bundle name.
322 * @throws NullPointerException if the name is null.
325 // Synchronization is not required here. All synchronization for
326 // adding a new Logger object is handled by LogManager.addLogger().
327 public static Logger getLogger(String name, String resourceBundleName) {
328 Logger l = ALL.get(name);
330 l = new Logger(name, resourceBundleName);
338 * Create an anonymous Logger. The newly created Logger is not
339 * registered in the LogManager namespace. There will be no
340 * access checks on updates to the logger.
342 * This factory method is primarily intended for use from applets.
343 * Because the resulting Logger is anonymous it can be kept private
344 * by the creating class. This removes the need for normal security
345 * checks, which in turn allows untrusted applet code to update
346 * the control state of the Logger. For example an applet can do
347 * a setLevel or an addHandler on an anonymous Logger.
349 * Even although the new logger is anonymous, it is configured
350 * to have the root logger ("") as its parent. This means that
351 * by default it inherits its effective level and handlers
352 * from the root logger.
355 * @return a newly created private Logger
357 public static Logger getAnonymousLogger() {
358 return getAnonymousLogger(null);
362 * Create an anonymous Logger. The newly created Logger is not
363 * registered in the LogManager namespace. There will be no
364 * access checks on updates to the logger.
366 * This factory method is primarily intended for use from applets.
367 * Because the resulting Logger is anonymous it can be kept private
368 * by the creating class. This removes the need for normal security
369 * checks, which in turn allows untrusted applet code to update
370 * the control state of the Logger. For example an applet can do
371 * a setLevel or an addHandler on an anonymous Logger.
373 * Even although the new logger is anonymous, it is configured
374 * to have the root logger ("") as its parent. This means that
375 * by default it inherits its effective level and handlers
376 * from the root logger.
378 * @param resourceBundleName name of ResourceBundle to be used for localizing
379 * messages for this logger.
380 * May be null if none of the messages require localization.
381 * @return a newly created private Logger
382 * @throws MissingResourceException if the resourceBundleName is non-null and
383 * no corresponding resource can be found.
386 // Synchronization is not required here. All synchronization for
387 // adding a new anonymous Logger object is handled by doSetParent().
388 public static Logger getAnonymousLogger(String resourceBundleName) {
389 return new Logger(null, resourceBundleName);
393 * Retrieve the localization resource bundle for this
394 * logger for the current default locale. Note that if
395 * the result is null, then the Logger will use a resource
396 * bundle inherited from its parent.
398 * @return localization bundle (may be null)
400 // public ResourceBundle getResourceBundle() {
401 // return findResourceBundle(getResourceBundleName());
405 * Retrieve the localization resource bundle name for this
406 * logger. Note that if the result is null, then the Logger
407 * will use a resource bundle name inherited from its parent.
409 * @return localization bundle name (may be null)
411 public String getResourceBundleName() {
416 * Set a filter to control output on this Logger.
418 * After passing the initial "level" check, the Logger will
419 * call this Filter to check if a log record should really
422 * @param newFilter a filter object (may be null)
423 * @exception SecurityException if a security manager exists and if
424 * the caller does not have LoggingPermission("control").
426 // public void setFilter(Filter newFilter) throws SecurityException {
431 * Get the current filter for this Logger.
433 * @return a filter object (may be null)
435 // public Filter getFilter() {
442 * All the other logging methods in this class call through
443 * this method to actually perform any logging. Subclasses can
444 * override this single method to capture all log activity.
446 * @param record the LogRecord to be published
448 public void log(LogRecord record) {
449 if (record.getLevel().intValue() < levelValue) {
454 switch (record.getLevel().toString()) {
455 case "INFO": method = "info"; break;
456 case "SEVERE": method = "error"; break;
457 case "WARNING": method = "warn"; break;
458 default: method = "log"; break;
461 String msg = record.getMessage();
462 final Object[] params = record.getParameters();
463 if (params != null && params.length != 0) {
464 for (int i = 0; i < params.length; i++) {
465 msg = msg.replace("{" + i + "}", params[i] == null ? "null" : params[i].toString());
471 record.getLoggerName(), msg);
474 @JavaScriptBody(args = { "method", "logger", "msg" }, body =
475 "if (typeof console !== 'undefined') console[method]('[' + logger + ']: ' + msg);"
477 private static native void consoleLog(
478 String method, String logger, String msg
481 // private support method for logging.
482 // We fill in the logger name, resource bundle name, and
483 // resource bundle and then call "void log(LogRecord)".
484 private void doLog(LogRecord lr) {
485 doLog(lr, lr.getResourceBundleName());
487 private void doLog(LogRecord lr, String bundleName) {
488 lr.setLoggerName(name);
493 //================================================================
494 // Start of convenience methods WITHOUT className and methodName
495 //================================================================
498 * Log a message, with no arguments.
500 * If the logger is currently enabled for the given message
501 * level then the given message is forwarded to all the
502 * registered output Handler objects.
504 * @param level One of the message level identifiers, e.g., SEVERE
505 * @param msg The string message (or a key in the message catalog)
507 public void log(Level level, String msg) {
508 if (level.intValue() < levelValue || levelValue == offValue) {
511 LogRecord lr = new LogRecord(level, msg);
516 * Log a message, with one object parameter.
518 * If the logger is currently enabled for the given message
519 * level then a corresponding LogRecord is created and forwarded
520 * to all the registered output Handler objects.
522 * @param level One of the message level identifiers, e.g., SEVERE
523 * @param msg The string message (or a key in the message catalog)
524 * @param param1 parameter to the message
526 public void log(Level level, String msg, Object param1) {
527 if (level.intValue() < levelValue || levelValue == offValue) {
530 LogRecord lr = new LogRecord(level, msg);
531 Object params[] = { param1 };
532 lr.setParameters(params);
537 * Log a message, with an array of object arguments.
539 * If the logger is currently enabled for the given message
540 * level then a corresponding LogRecord is created and forwarded
541 * to all the registered output Handler objects.
543 * @param level One of the message level identifiers, e.g., SEVERE
544 * @param msg The string message (or a key in the message catalog)
545 * @param params array of parameters to the message
547 public void log(Level level, String msg, Object params[]) {
548 if (level.intValue() < levelValue || levelValue == offValue) {
551 LogRecord lr = new LogRecord(level, msg);
552 lr.setParameters(params);
557 * Log a message, with associated Throwable information.
559 * If the logger is currently enabled for the given message
560 * level then the given arguments are stored in a LogRecord
561 * which is forwarded to all registered output handlers.
563 * Note that the thrown argument is stored in the LogRecord thrown
564 * property, rather than the LogRecord parameters property. Thus is it
565 * processed specially by output Formatters and is not treated
566 * as a formatting parameter to the LogRecord message property.
568 * @param level One of the message level identifiers, e.g., SEVERE
569 * @param msg The string message (or a key in the message catalog)
570 * @param thrown Throwable associated with log message.
572 public void log(Level level, String msg, Throwable thrown) {
573 if (level.intValue() < levelValue || levelValue == offValue) {
576 LogRecord lr = new LogRecord(level, msg);
577 lr.setThrown(thrown);
581 //================================================================
582 // Start of convenience methods WITH className and methodName
583 //================================================================
586 * Log a message, specifying source class and method,
589 * If the logger is currently enabled for the given message
590 * level then the given message is forwarded to all the
591 * registered output Handler objects.
593 * @param level One of the message level identifiers, e.g., SEVERE
594 * @param sourceClass name of class that issued the logging request
595 * @param sourceMethod name of method that issued the logging request
596 * @param msg The string message (or a key in the message catalog)
598 public void logp(Level level, String sourceClass, String sourceMethod, String msg) {
599 if (level.intValue() < levelValue || levelValue == offValue) {
602 LogRecord lr = new LogRecord(level, msg);
603 lr.setSourceClassName(sourceClass);
604 lr.setSourceMethodName(sourceMethod);
609 * Log a message, specifying source class and method,
610 * with a single object parameter to the log message.
612 * If the logger is currently enabled for the given message
613 * level then a corresponding LogRecord is created and forwarded
614 * to all the registered output Handler objects.
616 * @param level One of the message level identifiers, e.g., SEVERE
617 * @param sourceClass name of class that issued the logging request
618 * @param sourceMethod name of method that issued the logging request
619 * @param msg The string message (or a key in the message catalog)
620 * @param param1 Parameter to the log message.
622 public void logp(Level level, String sourceClass, String sourceMethod,
623 String msg, Object param1) {
624 if (level.intValue() < levelValue || levelValue == offValue) {
627 LogRecord lr = new LogRecord(level, msg);
628 lr.setSourceClassName(sourceClass);
629 lr.setSourceMethodName(sourceMethod);
630 Object params[] = { param1 };
631 lr.setParameters(params);
636 * Log a message, specifying source class and method,
637 * with an array of object arguments.
639 * If the logger is currently enabled for the given message
640 * level then a corresponding LogRecord is created and forwarded
641 * to all the registered output Handler objects.
643 * @param level One of the message level identifiers, e.g., SEVERE
644 * @param sourceClass name of class that issued the logging request
645 * @param sourceMethod name of method that issued the logging request
646 * @param msg The string message (or a key in the message catalog)
647 * @param params Array of parameters to the message
649 public void logp(Level level, String sourceClass, String sourceMethod,
650 String msg, Object params[]) {
651 if (level.intValue() < levelValue || levelValue == offValue) {
654 LogRecord lr = new LogRecord(level, msg);
655 lr.setSourceClassName(sourceClass);
656 lr.setSourceMethodName(sourceMethod);
657 lr.setParameters(params);
662 * Log a message, specifying source class and method,
663 * with associated Throwable information.
665 * If the logger is currently enabled for the given message
666 * level then the given arguments are stored in a LogRecord
667 * which is forwarded to all registered output handlers.
669 * Note that the thrown argument is stored in the LogRecord thrown
670 * property, rather than the LogRecord parameters property. Thus is it
671 * processed specially by output Formatters and is not treated
672 * as a formatting parameter to the LogRecord message property.
674 * @param level One of the message level identifiers, e.g., SEVERE
675 * @param sourceClass name of class that issued the logging request
676 * @param sourceMethod name of method that issued the logging request
677 * @param msg The string message (or a key in the message catalog)
678 * @param thrown Throwable associated with log message.
680 public void logp(Level level, String sourceClass, String sourceMethod,
681 String msg, Throwable thrown) {
682 if (level.intValue() < levelValue || levelValue == offValue) {
685 LogRecord lr = new LogRecord(level, msg);
686 lr.setSourceClassName(sourceClass);
687 lr.setSourceMethodName(sourceMethod);
688 lr.setThrown(thrown);
693 //=========================================================================
694 // Start of convenience methods WITH className, methodName and bundle name.
695 //=========================================================================
699 * Log a message, specifying source class, method, and resource bundle name
702 * If the logger is currently enabled for the given message
703 * level then the given message is forwarded to all the
704 * registered output Handler objects.
706 * The msg string is localized using the named resource bundle. If the
707 * resource bundle name is null, or an empty String or invalid
708 * then the msg string is not localized.
710 * @param level One of the message level identifiers, e.g., SEVERE
711 * @param sourceClass name of class that issued the logging request
712 * @param sourceMethod name of method that issued the logging request
713 * @param bundleName name of resource bundle to localize msg,
715 * @param msg The string message (or a key in the message catalog)
718 public void logrb(Level level, String sourceClass, String sourceMethod,
719 String bundleName, String msg) {
720 if (level.intValue() < levelValue || levelValue == offValue) {
723 LogRecord lr = new LogRecord(level, msg);
724 lr.setSourceClassName(sourceClass);
725 lr.setSourceMethodName(sourceMethod);
726 doLog(lr, bundleName);
730 * Log a message, specifying source class, method, and resource bundle name,
731 * with a single object parameter to the log message.
733 * If the logger is currently enabled for the given message
734 * level then a corresponding LogRecord is created and forwarded
735 * to all the registered output Handler objects.
737 * The msg string is localized using the named resource bundle. If the
738 * resource bundle name is null, or an empty String or invalid
739 * then the msg string is not localized.
741 * @param level One of the message level identifiers, e.g., SEVERE
742 * @param sourceClass name of class that issued the logging request
743 * @param sourceMethod name of method that issued the logging request
744 * @param bundleName name of resource bundle to localize msg,
746 * @param msg The string message (or a key in the message catalog)
747 * @param param1 Parameter to the log message.
749 public void logrb(Level level, String sourceClass, String sourceMethod,
750 String bundleName, String msg, Object param1) {
751 if (level.intValue() < levelValue || levelValue == offValue) {
754 LogRecord lr = new LogRecord(level, msg);
755 lr.setSourceClassName(sourceClass);
756 lr.setSourceMethodName(sourceMethod);
757 Object params[] = { param1 };
758 lr.setParameters(params);
759 doLog(lr, bundleName);
763 * Log a message, specifying source class, method, and resource bundle name,
764 * with an array of object arguments.
766 * If the logger is currently enabled for the given message
767 * level then a corresponding LogRecord is created and forwarded
768 * to all the registered output Handler objects.
770 * The msg string is localized using the named resource bundle. If the
771 * resource bundle name is null, or an empty String or invalid
772 * then the msg string is not localized.
774 * @param level One of the message level identifiers, e.g., SEVERE
775 * @param sourceClass name of class that issued the logging request
776 * @param sourceMethod name of method that issued the logging request
777 * @param bundleName name of resource bundle to localize msg,
779 * @param msg The string message (or a key in the message catalog)
780 * @param params Array of parameters to the message
782 public void logrb(Level level, String sourceClass, String sourceMethod,
783 String bundleName, String msg, Object params[]) {
784 if (level.intValue() < levelValue || levelValue == offValue) {
787 LogRecord lr = new LogRecord(level, msg);
788 lr.setSourceClassName(sourceClass);
789 lr.setSourceMethodName(sourceMethod);
790 lr.setParameters(params);
791 doLog(lr, bundleName);
795 * Log a message, specifying source class, method, and resource bundle name,
796 * with associated Throwable information.
798 * If the logger is currently enabled for the given message
799 * level then the given arguments are stored in a LogRecord
800 * which is forwarded to all registered output handlers.
802 * The msg string is localized using the named resource bundle. If the
803 * resource bundle name is null, or an empty String or invalid
804 * then the msg string is not localized.
806 * Note that the thrown argument is stored in the LogRecord thrown
807 * property, rather than the LogRecord parameters property. Thus is it
808 * processed specially by output Formatters and is not treated
809 * as a formatting parameter to the LogRecord message property.
811 * @param level One of the message level identifiers, e.g., SEVERE
812 * @param sourceClass name of class that issued the logging request
813 * @param sourceMethod name of method that issued the logging request
814 * @param bundleName name of resource bundle to localize msg,
816 * @param msg The string message (or a key in the message catalog)
817 * @param thrown Throwable associated with log message.
819 public void logrb(Level level, String sourceClass, String sourceMethod,
820 String bundleName, String msg, Throwable thrown) {
821 if (level.intValue() < levelValue || levelValue == offValue) {
824 LogRecord lr = new LogRecord(level, msg);
825 lr.setSourceClassName(sourceClass);
826 lr.setSourceMethodName(sourceMethod);
827 lr.setThrown(thrown);
828 doLog(lr, bundleName);
832 //======================================================================
833 // Start of convenience methods for logging method entries and returns.
834 //======================================================================
837 * Log a method entry.
839 * This is a convenience method that can be used to log entry
840 * to a method. A LogRecord with message "ENTRY", log level
841 * FINER, and the given sourceMethod and sourceClass is logged.
843 * @param sourceClass name of class that issued the logging request
844 * @param sourceMethod name of method that is being entered
846 public void entering(String sourceClass, String sourceMethod) {
847 if (Level.FINER.intValue() < levelValue) {
850 logp(Level.FINER, sourceClass, sourceMethod, "ENTRY");
854 * Log a method entry, with one parameter.
856 * This is a convenience method that can be used to log entry
857 * to a method. A LogRecord with message "ENTRY {0}", log level
858 * FINER, and the given sourceMethod, sourceClass, and parameter
861 * @param sourceClass name of class that issued the logging request
862 * @param sourceMethod name of method that is being entered
863 * @param param1 parameter to the method being entered
865 public void entering(String sourceClass, String sourceMethod, Object param1) {
866 if (Level.FINER.intValue() < levelValue) {
869 Object params[] = { param1 };
870 logp(Level.FINER, sourceClass, sourceMethod, "ENTRY {0}", params);
874 * Log a method entry, with an array of parameters.
876 * This is a convenience method that can be used to log entry
877 * to a method. A LogRecord with message "ENTRY" (followed by a
878 * format {N} indicator for each entry in the parameter array),
879 * log level FINER, and the given sourceMethod, sourceClass, and
880 * parameters is logged.
882 * @param sourceClass name of class that issued the logging request
883 * @param sourceMethod name of method that is being entered
884 * @param params array of parameters to the method being entered
886 public void entering(String sourceClass, String sourceMethod, Object params[]) {
887 if (Level.FINER.intValue() < levelValue) {
890 String msg = "ENTRY";
891 if (params == null ) {
892 logp(Level.FINER, sourceClass, sourceMethod, msg);
895 for (int i = 0; i < params.length; i++) {
896 msg = msg + " {" + i + "}";
898 logp(Level.FINER, sourceClass, sourceMethod, msg, params);
902 * Log a method return.
904 * This is a convenience method that can be used to log returning
905 * from a method. A LogRecord with message "RETURN", log level
906 * FINER, and the given sourceMethod and sourceClass is logged.
908 * @param sourceClass name of class that issued the logging request
909 * @param sourceMethod name of the method
911 public void exiting(String sourceClass, String sourceMethod) {
912 if (Level.FINER.intValue() < levelValue) {
915 logp(Level.FINER, sourceClass, sourceMethod, "RETURN");
920 * Log a method return, with result object.
922 * This is a convenience method that can be used to log returning
923 * from a method. A LogRecord with message "RETURN {0}", log level
924 * FINER, and the gives sourceMethod, sourceClass, and result
927 * @param sourceClass name of class that issued the logging request
928 * @param sourceMethod name of the method
929 * @param result Object that is being returned
931 public void exiting(String sourceClass, String sourceMethod, Object result) {
932 if (Level.FINER.intValue() < levelValue) {
935 Object params[] = { result };
936 logp(Level.FINER, sourceClass, sourceMethod, "RETURN {0}", result);
940 * Log throwing an exception.
942 * This is a convenience method to log that a method is
943 * terminating by throwing an exception. The logging is done
944 * using the FINER level.
946 * If the logger is currently enabled for the given message
947 * level then the given arguments are stored in a LogRecord
948 * which is forwarded to all registered output handlers. The
949 * LogRecord's message is set to "THROW".
951 * Note that the thrown argument is stored in the LogRecord thrown
952 * property, rather than the LogRecord parameters property. Thus is it
953 * processed specially by output Formatters and is not treated
954 * as a formatting parameter to the LogRecord message property.
956 * @param sourceClass name of class that issued the logging request
957 * @param sourceMethod name of the method.
958 * @param thrown The Throwable that is being thrown.
960 public void throwing(String sourceClass, String sourceMethod, Throwable thrown) {
961 if (Level.FINER.intValue() < levelValue || levelValue == offValue ) {
964 LogRecord lr = new LogRecord(Level.FINER, "THROW");
965 lr.setSourceClassName(sourceClass);
966 lr.setSourceMethodName(sourceMethod);
967 lr.setThrown(thrown);
971 //=======================================================================
972 // Start of simple convenience methods using level names as method names
973 //=======================================================================
976 * Log a SEVERE message.
978 * If the logger is currently enabled for the SEVERE message
979 * level then the given message is forwarded to all the
980 * registered output Handler objects.
982 * @param msg The string message (or a key in the message catalog)
984 public void severe(String msg) {
985 if (Level.SEVERE.intValue() < levelValue) {
988 log(Level.SEVERE, msg);
992 * Log a WARNING message.
994 * If the logger is currently enabled for the WARNING message
995 * level then the given message is forwarded to all the
996 * registered output Handler objects.
998 * @param msg The string message (or a key in the message catalog)
1000 public void warning(String msg) {
1001 if (Level.WARNING.intValue() < levelValue) {
1004 log(Level.WARNING, msg);
1008 * Log an INFO message.
1010 * If the logger is currently enabled for the INFO message
1011 * level then the given message is forwarded to all the
1012 * registered output Handler objects.
1014 * @param msg The string message (or a key in the message catalog)
1016 public void info(String msg) {
1017 if (Level.INFO.intValue() < levelValue) {
1020 log(Level.INFO, msg);
1024 * Log a CONFIG message.
1026 * If the logger is currently enabled for the CONFIG message
1027 * level then the given message is forwarded to all the
1028 * registered output Handler objects.
1030 * @param msg The string message (or a key in the message catalog)
1032 public void config(String msg) {
1033 if (Level.CONFIG.intValue() < levelValue) {
1036 log(Level.CONFIG, msg);
1040 * Log a FINE message.
1042 * If the logger is currently enabled for the FINE message
1043 * level then the given message is forwarded to all the
1044 * registered output Handler objects.
1046 * @param msg The string message (or a key in the message catalog)
1048 public void fine(String msg) {
1049 if (Level.FINE.intValue() < levelValue) {
1052 log(Level.FINE, msg);
1056 * Log a FINER message.
1058 * If the logger is currently enabled for the FINER message
1059 * level then the given message is forwarded to all the
1060 * registered output Handler objects.
1062 * @param msg The string message (or a key in the message catalog)
1064 public void finer(String msg) {
1065 if (Level.FINER.intValue() < levelValue) {
1068 log(Level.FINER, msg);
1072 * Log a FINEST message.
1074 * If the logger is currently enabled for the FINEST message
1075 * level then the given message is forwarded to all the
1076 * registered output Handler objects.
1078 * @param msg The string message (or a key in the message catalog)
1080 public void finest(String msg) {
1081 if (Level.FINEST.intValue() < levelValue) {
1084 log(Level.FINEST, msg);
1087 //================================================================
1088 // End of convenience methods
1089 //================================================================
1092 * Set the log level specifying which message levels will be
1093 * logged by this logger. Message levels lower than this
1094 * value will be discarded. The level value Level.OFF
1095 * can be used to turn off logging.
1097 * If the new level is null, it means that this node should
1098 * inherit its level from its nearest ancestor with a specific
1099 * (non-null) level value.
1101 * @param newLevel the new value for the log level (may be null)
1102 * @exception SecurityException if a security manager exists and if
1103 * the caller does not have LoggingPermission("control").
1105 public void setLevel(Level newLevel) throws SecurityException {
1106 levelValue = newLevel.intValue();
1107 levelObject = newLevel;
1111 * Get the log Level that has been specified for this Logger.
1112 * The result may be null, which means that this logger's
1113 * effective level will be inherited from its parent.
1115 * @return this Logger's level
1117 public Level getLevel() {
1122 * Check if a message of the given level would actually be logged
1123 * by this logger. This check is based on the Loggers effective level,
1124 * which may be inherited from its parent.
1126 * @param level a message logging level
1127 * @return true if the given message level is currently being logged.
1129 public boolean isLoggable(Level level) {
1130 if (level.intValue() < levelValue || levelValue == offValue) {
1137 * Get the name for this logger.
1138 * @return logger name. Will be null for anonymous Loggers.
1140 public String getName() {
1145 * Add a log Handler to receive logging messages.
1147 * By default, Loggers also send their output to their parent logger.
1148 * Typically the root Logger is configured with a set of Handlers
1149 * that essentially act as default handlers for all loggers.
1151 * @param handler a logging Handler
1152 * @exception SecurityException if a security manager exists and if
1153 * the caller does not have LoggingPermission("control").
1155 // public void addHandler(Handler handler) throws SecurityException {
1156 // // Check for null handler
1157 // handler.getClass();
1159 // handlers.add(handler);
1163 * Remove a log Handler.
1165 * Returns silently if the given Handler is not found or is null
1167 * @param handler a logging Handler
1168 * @exception SecurityException if a security manager exists and if
1169 * the caller does not have LoggingPermission("control").
1171 // public void removeHandler(Handler handler) throws SecurityException {
1173 // if (handler == null) {
1176 // handlers.remove(handler);
1180 * Get the Handlers associated with this logger.
1182 * @return an array of all registered Handlers
1184 // public Handler[] getHandlers() {
1185 // return handlers.toArray(emptyHandlers);
1189 * Specify whether or not this logger should send its output
1190 * to its parent Logger. This means that any LogRecords will
1191 * also be written to the parent's Handlers, and potentially
1192 * to its parent, recursively up the namespace.
1194 * @param useParentHandlers true if output is to be sent to the
1196 * @exception SecurityException if a security manager exists and if
1197 * the caller does not have LoggingPermission("control").
1199 public void setUseParentHandlers(boolean useParentHandlers) {
1204 * Discover whether or not this logger is sending its output
1205 * to its parent logger.
1207 * @return true if output is to be sent to the logger's parent
1209 public boolean getUseParentHandlers() {
1214 * Return the parent for this Logger.
1216 * This method returns the nearest extant parent in the namespace.
1217 * Thus if a Logger is called "a.b.c.d", and a Logger called "a.b"
1218 * has been created but no logger "a.b.c" exists, then a call of
1219 * getParent on the Logger "a.b.c.d" will return the Logger "a.b".
1221 * The result will be null if it is called on the root Logger
1224 * @return nearest existing parent Logger
1226 public Logger getParent() {
1227 // Note: this used to be synchronized on treeLock. However, this only
1228 // provided memory semantics, as there was no guarantee that the caller
1229 // would synchronize on treeLock (in fact, there is no way for external
1230 // callers to so synchronize). Therefore, we have made parent volatile
1232 String n = getName();
1233 int at = n.length();
1235 int last = n.lastIndexOf('.', at - 1);
1239 Logger p = ALL.get(n.substring(0, last));
1248 * Set the parent for this Logger. This method is used by
1249 * the LogManager to update a Logger when the namespace changes.
1251 * It should not be called from application code.
1253 * @param parent the new parent logger
1254 * @exception SecurityException if a security manager exists and if
1255 * the caller does not have LoggingPermission("control").
1257 public void setParent(Logger parent) {
1258 if (parent == null) {
1259 throw new NullPointerException();