1 /*
2 * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
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.
10 *
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).
16 *
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.
20 *
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
23 * questions.
24 */
25
26
27 package java.util.logging;
28
29 import java.lang.ref.WeakReference;
30 import java.security.AccessController;
31 import java.security.PrivilegedAction;
32 import java.util.ArrayList;
33 import java.util.Iterator;
34 import java.util.Locale;
35 import java.util.MissingResourceException;
36 import java.util.Objects;
37 import java.util.ResourceBundle;
38 import java.util.concurrent.CopyOnWriteArrayList;
39 import java.util.function.Supplier;
40 import sun.reflect.CallerSensitive;
41 import sun.reflect.Reflection;
42
43 /**
44 * A Logger object is used to log messages for a specific
45 * system or application component. Loggers are normally named,
46 * using a hierarchical dot-separated namespace. Logger names
47 * can be arbitrary strings, but they should normally be based on
48 * the package name or class name of the logged component, such
49 * as java.net or javax.swing. In addition it is possible to create
50 * "anonymous" Loggers that are not stored in the Logger namespace.
51 * <p>
52 * Logger objects may be obtained by calls on one of the getLogger
53 * factory methods. These will either create a new Logger or
54 * return a suitable existing Logger. It is important to note that
55 * the Logger returned by one of the {@code getLogger} factory methods
56 * may be garbage collected at any time if a strong reference to the
57 * Logger is not kept.
58 * <p>
59 * Logging messages will be forwarded to registered Handler
60 * objects, which can forward the messages to a variety of
61 * destinations, including consoles, files, OS logs, etc.
62 * <p>
63 * Each Logger keeps track of a "parent" Logger, which is its
64 * nearest existing ancestor in the Logger namespace.
65 * <p>
66 * Each Logger has a "Level" associated with it. This reflects
67 * a minimum Level that this logger cares about. If a Logger's
68 * level is set to {@code null}, then its effective level is inherited
69 * from its parent, which may in turn obtain it recursively from its
70 * parent, and so on up the tree.
71 * <p>
72 * The log level can be configured based on the properties from the
73 * logging configuration file, as described in the description
74 * of the LogManager class. However it may also be dynamically changed
75 * by calls on the Logger.setLevel method. If a logger's level is
76 * changed the change may also affect child loggers, since any child
77 * logger that has {@code null} as its level will inherit its
78 * effective level from its parent.
79 * <p>
80 * On each logging call the Logger initially performs a cheap
81 * check of the request level (e.g., SEVERE or FINE) against the
82 * effective log level of the logger. If the request level is
83 * lower than the log level, the logging call returns immediately.
84 * <p>
85 * After passing this initial (cheap) test, the Logger will allocate
86 * a LogRecord to describe the logging message. It will then call a
87 * Filter (if present) to do a more detailed check on whether the
88 * record should be published. If that passes it will then publish
89 * the LogRecord to its output Handlers. By default, loggers also
90 * publish to their parent's Handlers, recursively up the tree.
91 * <p>
92 * Each Logger may have a {@code ResourceBundle} associated with it.
93 * The {@code ResourceBundle} may be specified by name, using the
94 * {@link #getLogger(java.lang.String, java.lang.String)} factory
95 * method, or by value - using the {@link
96 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method.
97 * This bundle will be used for localizing logging messages.
98 * If a Logger does not have its own {@code ResourceBundle} or resource bundle
99 * name, then it will inherit the {@code ResourceBundle} or resource bundle name
100 * from its parent, recursively up the tree.
101 * <p>
102 * Most of the logger output methods take a "msg" argument. This
103 * msg argument may be either a raw value or a localization key.
104 * During formatting, if the logger has (or inherits) a localization
105 * {@code ResourceBundle} and if the {@code ResourceBundle} has a mapping for
106 * the msg string, then the msg string is replaced by the localized value.
107 * Otherwise the original msg string is used. Typically, formatters use
108 * java.text.MessageFormat style formatting to format parameters, so
109 * for example a format string "{0} {1}" would format two parameters
110 * as strings.
111 * <p>
112 * A set of methods alternatively take a "msgSupplier" instead of a "msg"
113 * argument. These methods take a {@link Supplier}{@code <String>} function
114 * which is invoked to construct the desired log message only when the message
115 * actually is to be logged based on the effective log level thus eliminating
116 * unnecessary message construction. For example, if the developer wants to
117 * log system health status for diagnosis, with the String-accepting version,
118 * the code would look like:
119 * <pre>{@code
120 *
121 * class DiagnosisMessages {
122 * static String systemHealthStatus() {
123 * // collect system health information
124 * ...
125 * }
126 * }
127 * ...
128 * logger.log(Level.FINER, DiagnosisMessages.systemHealthStatus());
129 * }</pre>
130 * With the above code, the health status is collected unnecessarily even when
131 * the log level FINER is disabled. With the Supplier-accepting version as
132 * below, the status will only be collected when the log level FINER is
133 * enabled.
134 * <pre>{@code
135 *
136 * logger.log(Level.FINER, DiagnosisMessages::systemHealthStatus);
137 * }</pre>
138 * <p>
139 * When looking for a {@code ResourceBundle}, the logger will first look at
140 * whether a bundle was specified using {@link
141 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle}, and then
142 * only whether a resource bundle name was specified through the {@link
143 * #getLogger(java.lang.String, java.lang.String) getLogger} factory method.
144 * If no {@code ResourceBundle} or no resource bundle name is found,
145 * then it will use the nearest {@code ResourceBundle} or resource bundle
146 * name inherited from its parent tree.<br>
147 * When a {@code ResourceBundle} was inherited or specified through the
148 * {@link
149 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method, then
150 * that {@code ResourceBundle} will be used. Otherwise if the logger only
151 * has or inherited a resource bundle name, then that resource bundle name
152 * will be mapped to a {@code ResourceBundle} object, using the default Locale
153 * at the time of logging.
154 * <br id="ResourceBundleMapping">When mapping resource bundle names to
155 * {@code ResourceBundle} objects, the logger will first try to use the
156 * Thread's {@linkplain java.lang.Thread#getContextClassLoader() context class
157 * loader} to map the given resource bundle name to a {@code ResourceBundle}.
158 * If the thread context class loader is {@code null}, it will try the
159 * {@linkplain java.lang.ClassLoader#getSystemClassLoader() system class loader}
160 * instead. If the {@code ResourceBundle} is still not found, it will use the
161 * class loader of the first caller of the {@link
162 * #getLogger(java.lang.String, java.lang.String) getLogger} factory method.
163 * <p>
164 * Formatting (including localization) is the responsibility of
165 * the output Handler, which will typically call a Formatter.
166 * <p>
167 * Note that formatting need not occur synchronously. It may be delayed
168 * until a LogRecord is actually written to an external sink.
169 * <p>
170 * The logging methods are grouped in five main categories:
171 * <ul>
172 * <li><p>
173 * There are a set of "log" methods that take a log level, a message
174 * string, and optionally some parameters to the message string.
175 * <li><p>
176 * There are a set of "logp" methods (for "log precise") that are
177 * like the "log" methods, but also take an explicit source class name
178 * and method name.
179 * <li><p>
180 * There are a set of "logrb" method (for "log with resource bundle")
181 * that are like the "logp" method, but also take an explicit resource
182 * bundle object for use in localizing the log message.
183 * <li><p>
184 * There are convenience methods for tracing method entries (the
185 * "entering" methods), method returns (the "exiting" methods) and
186 * throwing exceptions (the "throwing" methods).
187 * <li><p>
188 * Finally, there are a set of convenience methods for use in the
189 * very simplest cases, when a developer simply wants to log a
190 * simple string at a given log level. These methods are named
191 * after the standard Level names ("severe", "warning", "info", etc.)
192 * and take a single argument, a message string.
193 * </ul>
194 * <p>
195 * For the methods that do not take an explicit source name and
196 * method name, the Logging framework will make a "best effort"
197 * to determine which class and method called into the logging method.
198 * However, it is important to realize that this automatically inferred
199 * information may only be approximate (or may even be quite wrong!).
200 * Virtual machines are allowed to do extensive optimizations when
201 * JITing and may entirely remove stack frames, making it impossible
202 * to reliably locate the calling class and method.
203 * <P>
204 * All methods on Logger are multi-thread safe.
205 * <p>
206 * <b>Subclassing Information:</b> Note that a LogManager class may
207 * provide its own implementation of named Loggers for any point in
208 * the namespace. Therefore, any subclasses of Logger (unless they
209 * are implemented in conjunction with a new LogManager class) should
210 * take care to obtain a Logger instance from the LogManager class and
211 * should delegate operations such as "isLoggable" and "log(LogRecord)"
212 * to that instance. Note that in order to intercept all logging
213 * output, subclasses need only override the log(LogRecord) method.
214 * All the other logging methods are implemented as calls on this
215 * log(LogRecord) method.
216 *
217 * @since 1.4
218 */
219 public class Logger {
220 private static final Handler emptyHandlers[] = new Handler[0];
221 private static final int offValue = Level.OFF.intValue();
222
223 static final String SYSTEM_LOGGER_RB_NAME = "sun.util.logging.resources.logging";
224
225 // This class is immutable and it is important that it remains so.
226 private static final class LoggerBundle {
227 final String resourceBundleName; // Base name of the bundle.
228 final ResourceBundle userBundle; // Bundle set through setResourceBundle.
229 private LoggerBundle(String resourceBundleName, ResourceBundle bundle) {
230 this.resourceBundleName = resourceBundleName;
231 this.userBundle = bundle;
232 }
233 boolean isSystemBundle() {
234 return SYSTEM_LOGGER_RB_NAME.equals(resourceBundleName);
235 }
236 static LoggerBundle get(String name, ResourceBundle bundle) {
237 if (name == null && bundle == null) {
238 return NO_RESOURCE_BUNDLE;
239 } else if (SYSTEM_LOGGER_RB_NAME.equals(name) && bundle == null) {
240 return SYSTEM_BUNDLE;
241 } else {
242 return new LoggerBundle(name, bundle);
243 }
244 }
245 }
246
247 // This instance will be shared by all loggers created by the system
248 // code
249 private static final LoggerBundle SYSTEM_BUNDLE =
250 new LoggerBundle(SYSTEM_LOGGER_RB_NAME, null);
251
252 // This instance indicates that no resource bundle has been specified yet,
253 // and it will be shared by all loggers which have no resource bundle.
254 private static final LoggerBundle NO_RESOURCE_BUNDLE =
255 new LoggerBundle(null, null);
256
257 private volatile LogManager manager;
258 private String name;
259 private final CopyOnWriteArrayList<Handler> handlers =
260 new CopyOnWriteArrayList<>();
261 private volatile LoggerBundle loggerBundle = NO_RESOURCE_BUNDLE;
262 private volatile boolean useParentHandlers = true;
263 private volatile Filter filter;
264 private boolean anonymous;
265
266 // Cache to speed up behavior of findResourceBundle:
267 private ResourceBundle catalog; // Cached resource bundle
268 private String catalogName; // name associated with catalog
269 private Locale catalogLocale; // locale associated with catalog
270
271 // The fields relating to parent-child relationships and levels
272 // are managed under a separate lock, the treeLock.
273 private static final Object treeLock = new Object();
274 // We keep weak references from parents to children, but strong
275 // references from children to parents.
276 private volatile Logger parent; // our nearest parent.
277 private ArrayList<LogManager.LoggerWeakRef> kids; // WeakReferences to loggers that have us as parent
278 private volatile Level levelObject;
279 private volatile int levelValue; // current effective level value
280 private WeakReference<ClassLoader> callersClassLoaderRef;
281 private final boolean isSystemLogger;
282
283 /**
284 * GLOBAL_LOGGER_NAME is a name for the global logger.
285 *
286 * @since 1.6
287 */
288 public static final String GLOBAL_LOGGER_NAME = "global";
289
290 /**
291 * Return global logger object with the name Logger.GLOBAL_LOGGER_NAME.
292 *
293 * @return global logger object
294 * @since 1.7
295 */
296 public static final Logger getGlobal() {
297 // In order to break a cyclic dependence between the LogManager
298 // and Logger static initializers causing deadlocks, the global
299 // logger is created with a special constructor that does not
300 // initialize its log manager.
301 //
302 // If an application calls Logger.getGlobal() before any logger
303 // has been initialized, it is therefore possible that the
304 // LogManager class has not been initialized yet, and therefore
305 // Logger.global.manager will be null.
306 //
307 // In order to finish the initialization of the global logger, we
308 // will therefore call LogManager.getLogManager() here.
309 //
310 // To prevent race conditions we also need to call
311 // LogManager.getLogManager() unconditionally here.
312 // Indeed we cannot rely on the observed value of global.manager,
313 // because global.manager will become not null somewhere during
314 // the initialization of LogManager.
315 // If two threads are calling getGlobal() concurrently, one thread
316 // will see global.manager null and call LogManager.getLogManager(),
317 // but the other thread could come in at a time when global.manager
318 // is already set although ensureLogManagerInitialized is not finished
319 // yet...
320 // Calling LogManager.getLogManager() unconditionally will fix that.
321
322 LogManager.getLogManager();
323
324 // Now the global LogManager should be initialized,
325 // and the global logger should have been added to
326 // it, unless we were called within the constructor of a LogManager
327 // subclass installed as LogManager, in which case global.manager
328 // would still be null, and global will be lazily initialized later on.
329
330 return global;
331 }
332
333 /**
334 * The "global" Logger object is provided as a convenience to developers
335 * who are making casual use of the Logging package. Developers
336 * who are making serious use of the logging package (for example
337 * in products) should create and use their own Logger objects,
338 * with appropriate names, so that logging can be controlled on a
339 * suitable per-Logger granularity. Developers also need to keep a
340 * strong reference to their Logger objects to prevent them from
341 * being garbage collected.
342 *
343 * @deprecated Initialization of this field is prone to deadlocks.
344 * The field must be initialized by the Logger class initialization
345 * which may cause deadlocks with the LogManager class initialization.
346 * In such cases two class initialization wait for each other to complete.
347 * The preferred way to get the global logger object is via the call
348 * {@code Logger.getGlobal()}.
349 * For compatibility with old JDK versions where the
350 * {@code Logger.getGlobal()} is not available use the call
351 * {@code Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)}
352 * or {@code Logger.getLogger("global")}.
353 */
354 @Deprecated
355 public static final Logger global = new Logger(GLOBAL_LOGGER_NAME);
356
357 /**
358 * Protected method to construct a logger for a named subsystem.
359 * <p>
360 * The logger will be initially configured with a null Level
361 * and with useParentHandlers set to true.
362 *
363 * @param name A name for the logger. This should
364 * be a dot-separated name and should normally
365 * be based on the package name or class name
366 * of the subsystem, such as java.net
367 * or javax.swing. It may be null for anonymous Loggers.
368 * @param resourceBundleName name of ResourceBundle to be used for localizing
369 * messages for this logger. May be null if none
370 * of the messages require localization.
371 * @throws MissingResourceException if the resourceBundleName is non-null and
372 * no corresponding resource can be found.
373 */
374 protected Logger(String name, String resourceBundleName) {
375 this(name, resourceBundleName, null, LogManager.getLogManager(), false);
376 }
377
378 Logger(String name, String resourceBundleName, Class<?> caller, LogManager manager, boolean isSystemLogger) {
379 this.manager = manager;
380 this.isSystemLogger = isSystemLogger;
381 setupResourceInfo(resourceBundleName, caller);
382 this.name = name;
383 levelValue = Level.INFO.intValue();
384 }
385
386 private void setCallersClassLoaderRef(Class<?> caller) {
387 ClassLoader callersClassLoader = ((caller != null)
388 ? caller.getClassLoader()
389 : null);
390 if (callersClassLoader != null) {
391 this.callersClassLoaderRef = new WeakReference<>(callersClassLoader);
392 }
393 }
394
395 private ClassLoader getCallersClassLoader() {
396 return (callersClassLoaderRef != null)
397 ? callersClassLoaderRef.get()
398 : null;
399 }
400
401 // This constructor is used only to create the global Logger.
402 // It is needed to break a cyclic dependence between the LogManager
403 // and Logger static initializers causing deadlocks.
404 private Logger(String name) {
405 // The manager field is not initialized here.
406 this.name = name;
407 this.isSystemLogger = true;
408 levelValue = Level.INFO.intValue();
409 }
410
411 // It is called from LoggerContext.addLocalLogger() when the logger
412 // is actually added to a LogManager.
413 void setLogManager(LogManager manager) {
414 this.manager = manager;
415 }
416
417 private void checkPermission() throws SecurityException {
418 if (!anonymous) {
419 if (manager == null) {
420 // Complete initialization of the global Logger.
421 manager = LogManager.getLogManager();
422 }
423 manager.checkPermission();
424 }
425 }
426
427 // Until all JDK code converted to call sun.util.logging.PlatformLogger
428 // (see 7054233), we need to determine if Logger.getLogger is to add
429 // a system logger or user logger.
430 //
431 // As an interim solution, if the immediate caller whose caller loader is
432 // null, we assume it's a system logger and add it to the system context.
433 // These system loggers only set the resource bundle to the given
434 // resource bundle name (rather than the default system resource bundle).
435 private static class SystemLoggerHelper {
436 static boolean disableCallerCheck = getBooleanProperty("sun.util.logging.disableCallerCheck");
437 private static boolean getBooleanProperty(final String key) {
438 String s = AccessController.doPrivileged(new PrivilegedAction<String>() {
439 @Override
440 public String run() {
441 return System.getProperty(key);
442 }
443 });
444 return Boolean.valueOf(s);
445 }
446 }
447
448 private static Logger demandLogger(String name, String resourceBundleName, Class<?> caller) {
449 LogManager manager = LogManager.getLogManager();
450 if (!SystemLoggerHelper.disableCallerCheck) {
451 if (caller.getClassLoader() == null) {
452 return manager.demandSystemLogger(name, resourceBundleName, caller);
453 }
454 }
455 return manager.demandLogger(name, resourceBundleName, caller);
456 // ends up calling new Logger(name, resourceBundleName, caller)
457 // iff the logger doesn't exist already
458 }
459
460 /**
461 * Find or create a logger for a named subsystem. If a logger has
462 * already been created with the given name it is returned. Otherwise
463 * a new logger is created.
464 * <p>
465 * If a new logger is created its log level will be configured
466 * based on the LogManager configuration and it will configured
467 * to also send logging output to its parent's Handlers. It will
468 * be registered in the LogManager global namespace.
469 * <p>
470 * Note: The LogManager may only retain a weak reference to the newly
471 * created Logger. It is important to understand that a previously
472 * created Logger with the given name may be garbage collected at any
473 * time if there is no strong reference to the Logger. In particular,
474 * this means that two back-to-back calls like
475 * {@code getLogger("MyLogger").log(...)} may use different Logger
476 * objects named "MyLogger" if there is no strong reference to the
477 * Logger named "MyLogger" elsewhere in the program.
478 *
479 * @param name A name for the logger. This should
480 * be a dot-separated name and should normally
481 * be based on the package name or class name
482 * of the subsystem, such as java.net
483 * or javax.swing
484 * @return a suitable Logger
485 * @throws NullPointerException if the name is null.
486 */
487
488 // Synchronization is not required here. All synchronization for
489 // adding a new Logger object is handled by LogManager.addLogger().
490 @CallerSensitive
491 public static Logger getLogger(String name) {
492 // This method is intentionally not a wrapper around a call
493 // to getLogger(name, resourceBundleName). If it were then
494 // this sequence:
495 //
496 // getLogger("Foo", "resourceBundleForFoo");
497 // getLogger("Foo");
498 //
499 // would throw an IllegalArgumentException in the second call
500 // because the wrapper would result in an attempt to replace
501 // the existing "resourceBundleForFoo" with null.
502 return Logger.getLogger(name, Reflection.getCallerClass());
503 }
504
505 /**
506 * Find or create a logger for a named subsystem on behalf
507 * of the given caller.
508 *
509 * This method is called by {@link #getLogger(java.lang.String)} after
510 * it has obtained a reference to its caller's class.
511 *
512 * @param name A name for the logger.
513 * @param callerClass The class that called {@link
514 * #getLogger(java.lang.String)}.
515 * @return a suitable Logger for {@code callerClass}.
516 */
517 private static Logger getLogger(String name, Class<?> callerClass) {
518 return demandLogger(name, null, callerClass);
519 }
520
521 /**
522 * Find or create a logger for a named subsystem. If a logger has
523 * already been created with the given name it is returned. Otherwise
524 * a new logger is created.
525 * <p>
526 * If a new logger is created its log level will be configured
527 * based on the LogManager and it will configured to also send logging
528 * output to its parent's Handlers. It will be registered in
529 * the LogManager global namespace.
530 * <p>
531 * Note: The LogManager may only retain a weak reference to the newly
532 * created Logger. It is important to understand that a previously
533 * created Logger with the given name may be garbage collected at any
534 * time if there is no strong reference to the Logger. In particular,
535 * this means that two back-to-back calls like
536 * {@code getLogger("MyLogger", ...).log(...)} may use different Logger
537 * objects named "MyLogger" if there is no strong reference to the
538 * Logger named "MyLogger" elsewhere in the program.
539 * <p>
540 * If the named Logger already exists and does not yet have a
541 * localization resource bundle then the given resource bundle
542 * name is used. If the named Logger already exists and has
543 * a different resource bundle name then an IllegalArgumentException
544 * is thrown.
545 *
546 * @param name A name for the logger. This should
547 * be a dot-separated name and should normally
548 * be based on the package name or class name
549 * of the subsystem, such as java.net
550 * or javax.swing
551 * @param resourceBundleName name of ResourceBundle to be used for localizing
552 * messages for this logger. May be {@code null}
553 * if none of the messages require localization.
554 * @return a suitable Logger
555 * @throws MissingResourceException if the resourceBundleName is non-null and
556 * no corresponding resource can be found.
557 * @throws IllegalArgumentException if the Logger already exists and uses
558 * a different resource bundle name; or if
559 * {@code resourceBundleName} is {@code null} but the named
560 * logger has a resource bundle set.
561 * @throws NullPointerException if the name is null.
562 */
563
564 // Synchronization is not required here. All synchronization for
565 // adding a new Logger object is handled by LogManager.addLogger().
566 @CallerSensitive
567 public static Logger getLogger(String name, String resourceBundleName) {
568 return Logger.getLogger(name, resourceBundleName, Reflection.getCallerClass());
569 }
570
571 /**
572 * Find or create a logger for a named subsystem on behalf
573 * of the given caller.
574 *
575 * This method is called by {@link
576 * #getLogger(java.lang.String, java.lang.String)} after
577 * it has obtained a reference to its caller's class.
578 *
579 * @param name A name for the logger.
580 * @param resourceBundleName name of ResourceBundle to be used for localizing
581 * messages for this logger. May be {@code null}
582 * if none of the messages require localization.
583 * @param callerClass The class that called {@link
584 * #getLogger(java.lang.String, java.lang.String)}.
585 * This class will also be used for locating the
586 * resource bundle if {@code resourceBundleName} is
587 * not {@code null}.
588 * @return a suitable Logger for {@code callerClass}.
589 */
590 private static Logger getLogger(String name, String resourceBundleName,
591 Class<?> callerClass) {
592 Logger result = demandLogger(name, resourceBundleName, callerClass);
593
594 // MissingResourceException or IllegalArgumentException can be
595 // thrown by setupResourceInfo().
596 // We have to set the callers ClassLoader here in case demandLogger
597 // above found a previously created Logger. This can happen, for
598 // example, if Logger.getLogger(name) is called and subsequently
599 // Logger.getLogger(name, resourceBundleName) is called. In this case
600 // we won't necessarily have the correct classloader saved away, so
601 // we need to set it here, too.
602
603 result.setupResourceInfo(resourceBundleName, callerClass);
604 return result;
605 }
606
607 // package-private
608 // Add a platform logger to the system context.
609 // i.e. caller of sun.util.logging.PlatformLogger.getLogger
610 static Logger getPlatformLogger(String name) {
611 LogManager manager = LogManager.getLogManager();
612
613 // all loggers in the system context will default to
614 // the system logger's resource bundle - therefore the caller won't
615 // be needed and can be null.
616 Logger result = manager.demandSystemLogger(name, SYSTEM_LOGGER_RB_NAME, null);
617 return result;
618 }
619
620 /**
621 * Create an anonymous Logger. The newly created Logger is not
622 * registered in the LogManager namespace. There will be no
623 * access checks on updates to the logger.
624 * <p>
625 * This factory method is primarily intended for use from applets.
626 * Because the resulting Logger is anonymous it can be kept private
627 * by the creating class. This removes the need for normal security
628 * checks, which in turn allows untrusted applet code to update
629 * the control state of the Logger. For example an applet can do
630 * a setLevel or an addHandler on an anonymous Logger.
631 * <p>
632 * Even although the new logger is anonymous, it is configured
633 * to have the root logger ("") as its parent. This means that
634 * by default it inherits its effective level and handlers
635 * from the root logger. Changing its parent via the
636 * {@link #setParent(java.util.logging.Logger) setParent} method
637 * will still require the security permission specified by that method.
638 *
639 * @return a newly created private Logger
640 */
641 public static Logger getAnonymousLogger() {
642 return getAnonymousLogger(null);
643 }
644
645 /**
646 * Create an anonymous Logger. The newly created Logger is not
647 * registered in the LogManager namespace. There will be no
648 * access checks on updates to the logger.
649 * <p>
650 * This factory method is primarily intended for use from applets.
651 * Because the resulting Logger is anonymous it can be kept private
652 * by the creating class. This removes the need for normal security
653 * checks, which in turn allows untrusted applet code to update
654 * the control state of the Logger. For example an applet can do
655 * a setLevel or an addHandler on an anonymous Logger.
656 * <p>
657 * Even although the new logger is anonymous, it is configured
658 * to have the root logger ("") as its parent. This means that
659 * by default it inherits its effective level and handlers
660 * from the root logger. Changing its parent via the
661 * {@link #setParent(java.util.logging.Logger) setParent} method
662 * will still require the security permission specified by that method.
663 *
664 * @param resourceBundleName name of ResourceBundle to be used for localizing
665 * messages for this logger.
666 * May be null if none of the messages require localization.
667 * @return a newly created private Logger
668 * @throws MissingResourceException if the resourceBundleName is non-null and
669 * no corresponding resource can be found.
670 */
671
672 // Synchronization is not required here. All synchronization for
673 // adding a new anonymous Logger object is handled by doSetParent().
674 @CallerSensitive
675 public static Logger getAnonymousLogger(String resourceBundleName) {
676 LogManager manager = LogManager.getLogManager();
677 // cleanup some Loggers that have been GC'ed
678 manager.drainLoggerRefQueueBounded();
679 Logger result = new Logger(null, resourceBundleName,
680 Reflection.getCallerClass(), manager, false);
681 result.anonymous = true;
682 Logger root = manager.getLogger("");
683 result.doSetParent(root);
684 return result;
685 }
686
687 /**
688 * Retrieve the localization resource bundle for this
689 * logger.
690 * This method will return a {@code ResourceBundle} that was either
691 * set by the {@link
692 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method or
693 * <a href="#ResourceBundleMapping">mapped from the
694 * the resource bundle name</a> set via the {@link
695 * Logger#getLogger(java.lang.String, java.lang.String) getLogger} factory
696 * method for the current default locale.
697 * <br>Note that if the result is {@code null}, then the Logger will use a resource
698 * bundle or resource bundle name inherited from its parent.
699 *
700 * @return localization bundle (may be {@code null})
701 */
702 public ResourceBundle getResourceBundle() {
703 return findResourceBundle(getResourceBundleName(), true);
704 }
705
706 /**
707 * Retrieve the localization resource bundle name for this
708 * logger.
709 * This is either the name specified through the {@link
710 * #getLogger(java.lang.String, java.lang.String) getLogger} factory method,
711 * or the {@linkplain ResourceBundle#getBaseBundleName() base name} of the
712 * ResourceBundle set through {@link
713 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method.
714 * <br>Note that if the result is {@code null}, then the Logger will use a resource
715 * bundle or resource bundle name inherited from its parent.
716 *
717 * @return localization bundle name (may be {@code null})
718 */
719 public String getResourceBundleName() {
720 return loggerBundle.resourceBundleName;
721 }
722
723 /**
724 * Set a filter to control output on this Logger.
725 * <P>
726 * After passing the initial "level" check, the Logger will
727 * call this Filter to check if a log record should really
728 * be published.
729 *
730 * @param newFilter a filter object (may be null)
731 * @throws SecurityException if a security manager exists,
732 * this logger is not anonymous, and the caller
733 * does not have LoggingPermission("control").
734 */
735 public void setFilter(Filter newFilter) throws SecurityException {
736 checkPermission();
737 filter = newFilter;
738 }
739
740 /**
741 * Get the current filter for this Logger.
742 *
743 * @return a filter object (may be null)
744 */
745 public Filter getFilter() {
746 return filter;
747 }
748
749 /**
750 * Log a LogRecord.
751 * <p>
752 * All the other logging methods in this class call through
753 * this method to actually perform any logging. Subclasses can
754 * override this single method to capture all log activity.
755 *
756 * @param record the LogRecord to be published
757 */
758 public void log(LogRecord record) {
759 if (!isLoggable(record.getLevel())) {
760 return;
761 }
762 Filter theFilter = filter;
763 if (theFilter != null && !theFilter.isLoggable(record)) {
764 return;
765 }
766
767 // Post the LogRecord to all our Handlers, and then to
768 // our parents' handlers, all the way up the tree.
769
770 Logger logger = this;
771 while (logger != null) {
772 final Handler[] loggerHandlers = isSystemLogger
773 ? logger.accessCheckedHandlers()
774 : logger.getHandlers();
775
776 for (Handler handler : loggerHandlers) {
777 handler.publish(record);
778 }
779
780 final boolean useParentHdls = isSystemLogger
781 ? logger.useParentHandlers
782 : logger.getUseParentHandlers();
783
784 if (!useParentHdls) {
785 break;
786 }
787
788 logger = isSystemLogger ? logger.parent : logger.getParent();
789 }
790 }
791
792 // private support method for logging.
793 // We fill in the logger name, resource bundle name, and
794 // resource bundle and then call "void log(LogRecord)".
795 private void doLog(LogRecord lr) {
796 lr.setLoggerName(name);
797 final LoggerBundle lb = getEffectiveLoggerBundle();
798 final ResourceBundle bundle = lb.userBundle;
799 final String ebname = lb.resourceBundleName;
800 if (ebname != null && bundle != null) {
801 lr.setResourceBundleName(ebname);
802 lr.setResourceBundle(bundle);
803 }
804 log(lr);
805 }
806
807
808 //================================================================
809 // Start of convenience methods WITHOUT className and methodName
810 //================================================================
811
812 /**
813 * Log a message, with no arguments.
814 * <p>
815 * If the logger is currently enabled for the given message
816 * level then the given message is forwarded to all the
817 * registered output Handler objects.
818 *
819 * @param level One of the message level identifiers, e.g., SEVERE
820 * @param msg The string message (or a key in the message catalog)
821 */
822 public void log(Level level, String msg) {
823 if (!isLoggable(level)) {
824 return;
825 }
826 LogRecord lr = new LogRecord(level, msg);
827 doLog(lr);
828 }
829
830 /**
831 * Log a message, which is only to be constructed if the logging level
832 * is such that the message will actually be logged.
833 * <p>
834 * If the logger is currently enabled for the given message
835 * level then the message is constructed by invoking the provided
836 * supplier function and forwarded to all the registered output
837 * Handler objects.
838 *
839 * @param level One of the message level identifiers, e.g., SEVERE
840 * @param msgSupplier A function, which when called, produces the
841 * desired log message
842 */
843 public void log(Level level, Supplier<String> msgSupplier) {
844 if (!isLoggable(level)) {
845 return;
846 }
847 LogRecord lr = new LogRecord(level, msgSupplier.get());
848 doLog(lr);
849 }
850
851 /**
852 * Log a message, with one object parameter.
853 * <p>
854 * If the logger is currently enabled for the given message
855 * level then a corresponding LogRecord is created and forwarded
856 * to all the registered output Handler objects.
857 *
858 * @param level One of the message level identifiers, e.g., SEVERE
859 * @param msg The string message (or a key in the message catalog)
860 * @param param1 parameter to the message
861 */
862 public void log(Level level, String msg, Object param1) {
863 if (!isLoggable(level)) {
864 return;
865 }
866 LogRecord lr = new LogRecord(level, msg);
867 Object params[] = { param1 };
868 lr.setParameters(params);
869 doLog(lr);
870 }
871
872 /**
873 * Log a message, with an array of object arguments.
874 * <p>
875 * If the logger is currently enabled for the given message
876 * level then a corresponding LogRecord is created and forwarded
877 * to all the registered output Handler objects.
878 *
879 * @param level One of the message level identifiers, e.g., SEVERE
880 * @param msg The string message (or a key in the message catalog)
881 * @param params array of parameters to the message
882 */
883 public void log(Level level, String msg, Object params[]) {
884 if (!isLoggable(level)) {
885 return;
886 }
887 LogRecord lr = new LogRecord(level, msg);
888 lr.setParameters(params);
889 doLog(lr);
890 }
891
892 /**
893 * Log a message, with associated Throwable information.
894 * <p>
895 * If the logger is currently enabled for the given message
896 * level then the given arguments are stored in a LogRecord
897 * which is forwarded to all registered output handlers.
898 * <p>
899 * Note that the thrown argument is stored in the LogRecord thrown
900 * property, rather than the LogRecord parameters property. Thus it is
901 * processed specially by output Formatters and is not treated
902 * as a formatting parameter to the LogRecord message property.
903 *
904 * @param level One of the message level identifiers, e.g., SEVERE
905 * @param msg The string message (or a key in the message catalog)
906 * @param thrown Throwable associated with log message.
907 */
908 public void log(Level level, String msg, Throwable thrown) {
909 if (!isLoggable(level)) {
910 return;
911 }
912 LogRecord lr = new LogRecord(level, msg);
913 lr.setThrown(thrown);
914 doLog(lr);
915 }
916
917 /**
918 * Log a lazily constructed message, with associated Throwable information.
919 * <p>
920 * If the logger is currently enabled for the given message level then the
921 * message is constructed by invoking the provided supplier function. The
922 * message and the given {@link Throwable} are then stored in a {@link
923 * LogRecord} which is forwarded to all registered output handlers.
924 * <p>
925 * Note that the thrown argument is stored in the LogRecord thrown
926 * property, rather than the LogRecord parameters property. Thus it is
927 * processed specially by output Formatters and is not treated
928 * as a formatting parameter to the LogRecord message property.
929 *
930 * @param level One of the message level identifiers, e.g., SEVERE
931 * @param thrown Throwable associated with log message.
932 * @param msgSupplier A function, which when called, produces the
933 * desired log message
934 * @since 1.8
935 */
936 public void log(Level level, Throwable thrown, Supplier<String> msgSupplier) {
937 if (!isLoggable(level)) {
938 return;
939 }
940 LogRecord lr = new LogRecord(level, msgSupplier.get());
941 lr.setThrown(thrown);
942 doLog(lr);
943 }
944
945 //================================================================
946 // Start of convenience methods WITH className and methodName
947 //================================================================
948
949 /**
950 * Log a message, specifying source class and method,
951 * with no arguments.
952 * <p>
953 * If the logger is currently enabled for the given message
954 * level then the given message is forwarded to all the
955 * registered output Handler objects.
956 *
957 * @param level One of the message level identifiers, e.g., SEVERE
958 * @param sourceClass name of class that issued the logging request
959 * @param sourceMethod name of method that issued the logging request
960 * @param msg The string message (or a key in the message catalog)
961 */
962 public void logp(Level level, String sourceClass, String sourceMethod, String msg) {
963 if (!isLoggable(level)) {
964 return;
965 }
966 LogRecord lr = new LogRecord(level, msg);
967 lr.setSourceClassName(sourceClass);
968 lr.setSourceMethodName(sourceMethod);
969 doLog(lr);
970 }
971
972 /**
973 * Log a lazily constructed message, specifying source class and method,
974 * with no arguments.
975 * <p>
976 * If the logger is currently enabled for the given message
977 * level then the message is constructed by invoking the provided
978 * supplier function and forwarded to all the registered output
979 * Handler objects.
980 *
981 * @param level One of the message level identifiers, e.g., SEVERE
982 * @param sourceClass name of class that issued the logging request
983 * @param sourceMethod name of method that issued the logging request
984 * @param msgSupplier A function, which when called, produces the
985 * desired log message
986 * @since 1.8
987 */
988 public void logp(Level level, String sourceClass, String sourceMethod,
989 Supplier<String> msgSupplier) {
990 if (!isLoggable(level)) {
991 return;
992 }
993 LogRecord lr = new LogRecord(level, msgSupplier.get());
994 lr.setSourceClassName(sourceClass);
995 lr.setSourceMethodName(sourceMethod);
996 doLog(lr);
997 }
998
999 /**
1000 * Log a message, specifying source class and method,
1001 * with a single object parameter to the log message.
1002 * <p>
1003 * If the logger is currently enabled for the given message
1004 * level then a corresponding LogRecord is created and forwarded
1005 * to all the registered output Handler objects.
1006 *
1007 * @param level One of the message level identifiers, e.g., SEVERE
1008 * @param sourceClass name of class that issued the logging request
1009 * @param sourceMethod name of method that issued the logging request
1010 * @param msg The string message (or a key in the message catalog)
1011 * @param param1 Parameter to the log message.
1012 */
1013 public void logp(Level level, String sourceClass, String sourceMethod,
1014 String msg, Object param1) {
1015 if (!isLoggable(level)) {
1016 return;
1017 }
1018 LogRecord lr = new LogRecord(level, msg);
1019 lr.setSourceClassName(sourceClass);
1020 lr.setSourceMethodName(sourceMethod);
1021 Object params[] = { param1 };
1022 lr.setParameters(params);
1023 doLog(lr);
1024 }
1025
1026 /**
1027 * Log a message, specifying source class and method,
1028 * with an array of object arguments.
1029 * <p>
1030 * If the logger is currently enabled for the given message
1031 * level then a corresponding LogRecord is created and forwarded
1032 * to all the registered output Handler objects.
1033 *
1034 * @param level One of the message level identifiers, e.g., SEVERE
1035 * @param sourceClass name of class that issued the logging request
1036 * @param sourceMethod name of method that issued the logging request
1037 * @param msg The string message (or a key in the message catalog)
1038 * @param params Array of parameters to the message
1039 */
1040 public void logp(Level level, String sourceClass, String sourceMethod,
1041 String msg, Object params[]) {
1042 if (!isLoggable(level)) {
1043 return;
1044 }
1045 LogRecord lr = new LogRecord(level, msg);
1046 lr.setSourceClassName(sourceClass);
1047 lr.setSourceMethodName(sourceMethod);
1048 lr.setParameters(params);
1049 doLog(lr);
1050 }
1051
1052 /**
1053 * Log a message, specifying source class and method,
1054 * with associated Throwable information.
1055 * <p>
1056 * If the logger is currently enabled for the given message
1057 * level then the given arguments are stored in a LogRecord
1058 * which is forwarded to all registered output handlers.
1059 * <p>
1060 * Note that the thrown argument is stored in the LogRecord thrown
1061 * property, rather than the LogRecord parameters property. Thus it is
1062 * processed specially by output Formatters and is not treated
1063 * as a formatting parameter to the LogRecord message property.
1064 *
1065 * @param level One of the message level identifiers, e.g., SEVERE
1066 * @param sourceClass name of class that issued the logging request
1067 * @param sourceMethod name of method that issued the logging request
1068 * @param msg The string message (or a key in the message catalog)
1069 * @param thrown Throwable associated with log message.
1070 */
1071 public void logp(Level level, String sourceClass, String sourceMethod,
1072 String msg, Throwable thrown) {
1073 if (!isLoggable(level)) {
1074 return;
1075 }
1076 LogRecord lr = new LogRecord(level, msg);
1077 lr.setSourceClassName(sourceClass);
1078 lr.setSourceMethodName(sourceMethod);
1079 lr.setThrown(thrown);
1080 doLog(lr);
1081 }
1082
1083 /**
1084 * Log a lazily constructed message, specifying source class and method,
1085 * with associated Throwable information.
1086 * <p>
1087 * If the logger is currently enabled for the given message level then the
1088 * message is constructed by invoking the provided supplier function. The
1089 * message and the given {@link Throwable} are then stored in a {@link
1090 * LogRecord} which is forwarded to all registered output handlers.
1091 * <p>
1092 * Note that the thrown argument is stored in the LogRecord thrown
1093 * property, rather than the LogRecord parameters property. Thus it is
1094 * processed specially by output Formatters and is not treated
1095 * as a formatting parameter to the LogRecord message property.
1096 *
1097 * @param level One of the message level identifiers, e.g., SEVERE
1098 * @param sourceClass name of class that issued the logging request
1099 * @param sourceMethod name of method that issued the logging request
1100 * @param thrown Throwable associated with log message.
1101 * @param msgSupplier A function, which when called, produces the
1102 * desired log message
1103 * @since 1.8
1104 */
1105 public void logp(Level level, String sourceClass, String sourceMethod,
1106 Throwable thrown, Supplier<String> msgSupplier) {
1107 if (!isLoggable(level)) {
1108 return;
1109 }
1110 LogRecord lr = new LogRecord(level, msgSupplier.get());
1111 lr.setSourceClassName(sourceClass);
1112 lr.setSourceMethodName(sourceMethod);
1113 lr.setThrown(thrown);
1114 doLog(lr);
1115 }
1116
1117
1118 //=========================================================================
1119 // Start of convenience methods WITH className, methodName and bundle name.
1120 //=========================================================================
1121
1122 // Private support method for logging for "logrb" methods.
1123 // We fill in the logger name, resource bundle name, and
1124 // resource bundle and then call "void log(LogRecord)".
1125 private void doLog(LogRecord lr, String rbname) {
1126 lr.setLoggerName(name);
1127 if (rbname != null) {
1128 lr.setResourceBundleName(rbname);
1129 lr.setResourceBundle(findResourceBundle(rbname, false));
1130 }
1131 log(lr);
1132 }
1133
1134 // Private support method for logging for "logrb" methods.
1135 private void doLog(LogRecord lr, ResourceBundle rb) {
1136 lr.setLoggerName(name);
1137 if (rb != null) {
1138 lr.setResourceBundleName(rb.getBaseBundleName());
1139 lr.setResourceBundle(rb);
1140 }
1141 log(lr);
1142 }
1143
1144 /**
1145 * Log a message, specifying source class, method, and resource bundle name
1146 * with no arguments.
1147 * <p>
1148 * If the logger is currently enabled for the given message
1149 * level then the given message is forwarded to all the
1150 * registered output Handler objects.
1151 * <p>
1152 * The msg string is localized using the named resource bundle. If the
1153 * resource bundle name is null, or an empty String or invalid
1154 * then the msg string is not localized.
1155 *
1156 * @param level One of the message level identifiers, e.g., SEVERE
1157 * @param sourceClass name of class that issued the logging request
1158 * @param sourceMethod name of method that issued the logging request
1159 * @param bundleName name of resource bundle to localize msg,
1160 * can be null
1161 * @param msg The string message (or a key in the message catalog)
1162 * @deprecated Use {@link #logrb(java.util.logging.Level, java.lang.String,
1163 * java.lang.String, java.util.ResourceBundle, java.lang.String,
1164 * java.lang.Object...)} instead.
1165 */
1166 @Deprecated
1167 public void logrb(Level level, String sourceClass, String sourceMethod,
1168 String bundleName, String msg) {
1169 if (!isLoggable(level)) {
1170 return;
1171 }
1172 LogRecord lr = new LogRecord(level, msg);
1173 lr.setSourceClassName(sourceClass);
1174 lr.setSourceMethodName(sourceMethod);
1175 doLog(lr, bundleName);
1176 }
1177
1178 /**
1179 * Log a message, specifying source class, method, and resource bundle name,
1180 * with a single object parameter to the log message.
1181 * <p>
1182 * If the logger is currently enabled for the given message
1183 * level then a corresponding LogRecord is created and forwarded
1184 * to all the registered output Handler objects.
1185 * <p>
1186 * The msg string is localized using the named resource bundle. If the
1187 * resource bundle name is null, or an empty String or invalid
1188 * then the msg string is not localized.
1189 *
1190 * @param level One of the message level identifiers, e.g., SEVERE
1191 * @param sourceClass name of class that issued the logging request
1192 * @param sourceMethod name of method that issued the logging request
1193 * @param bundleName name of resource bundle to localize msg,
1194 * can be null
1195 * @param msg The string message (or a key in the message catalog)
1196 * @param param1 Parameter to the log message.
1197 * @deprecated Use {@link #logrb(java.util.logging.Level, java.lang.String,
1198 * java.lang.String, java.util.ResourceBundle, java.lang.String,
1199 * java.lang.Object...)} instead
1200 */
1201 @Deprecated
1202 public void logrb(Level level, String sourceClass, String sourceMethod,
1203 String bundleName, String msg, Object param1) {
1204 if (!isLoggable(level)) {
1205 return;
1206 }
1207 LogRecord lr = new LogRecord(level, msg);
1208 lr.setSourceClassName(sourceClass);
1209 lr.setSourceMethodName(sourceMethod);
1210 Object params[] = { param1 };
1211 lr.setParameters(params);
1212 doLog(lr, bundleName);
1213 }
1214
1215 /**
1216 * Log a message, specifying source class, method, and resource bundle name,
1217 * with an array of object arguments.
1218 * <p>
1219 * If the logger is currently enabled for the given message
1220 * level then a corresponding LogRecord is created and forwarded
1221 * to all the registered output Handler objects.
1222 * <p>
1223 * The msg string is localized using the named resource bundle. If the
1224 * resource bundle name is null, or an empty String or invalid
1225 * then the msg string is not localized.
1226 *
1227 * @param level One of the message level identifiers, e.g., SEVERE
1228 * @param sourceClass name of class that issued the logging request
1229 * @param sourceMethod name of method that issued the logging request
1230 * @param bundleName name of resource bundle to localize msg,
1231 * can be null.
1232 * @param msg The string message (or a key in the message catalog)
1233 * @param params Array of parameters to the message
1234 * @deprecated Use {@link #logrb(java.util.logging.Level, java.lang.String,
1235 * java.lang.String, java.util.ResourceBundle, java.lang.String,
1236 * java.lang.Object...)} instead.
1237 */
1238 @Deprecated
1239 public void logrb(Level level, String sourceClass, String sourceMethod,
1240 String bundleName, String msg, Object params[]) {
1241 if (!isLoggable(level)) {
1242 return;
1243 }
1244 LogRecord lr = new LogRecord(level, msg);
1245 lr.setSourceClassName(sourceClass);
1246 lr.setSourceMethodName(sourceMethod);
1247 lr.setParameters(params);
1248 doLog(lr, bundleName);
1249 }
1250
1251 /**
1252 * Log a message, specifying source class, method, and resource bundle,
1253 * with an optional list of message parameters.
1254 * <p>
1255 * If the logger is currently enabled for the given message
1256 * level then a corresponding LogRecord is created and forwarded
1257 * to all the registered output Handler objects.
1258 * <p>
1259 * The {@code msg} string is localized using the given resource bundle.
1260 * If the resource bundle is {@code null}, then the {@code msg} string is not
1261 * localized.
1262 *
1263 * @param level One of the message level identifiers, e.g., SEVERE
1264 * @param sourceClass Name of the class that issued the logging request
1265 * @param sourceMethod Name of the method that issued the logging request
1266 * @param bundle Resource bundle to localize {@code msg},
1267 * can be {@code null}.
1268 * @param msg The string message (or a key in the message catalog)
1269 * @param params Parameters to the message (optional, may be none).
1270 * @since 1.8
1271 */
1272 public void logrb(Level level, String sourceClass, String sourceMethod,
1273 ResourceBundle bundle, String msg, Object... params) {
1274 if (!isLoggable(level)) {
1275 return;
1276 }
1277 LogRecord lr = new LogRecord(level, msg);
1278 lr.setSourceClassName(sourceClass);
1279 lr.setSourceMethodName(sourceMethod);
1280 if (params != null && params.length != 0) {
1281 lr.setParameters(params);
1282 }
1283 doLog(lr, bundle);
1284 }
1285
1286 /**
1287 * Log a message, specifying source class, method, and resource bundle,
1288 * with an optional list of message parameters.
1289 * <p>
1290 * If the logger is currently enabled for the given message
1291 * level then a corresponding LogRecord is created and forwarded
1292 * to all the registered output Handler objects.
1293 * <p>
1294 * The {@code msg} string is localized using the given resource bundle.
1295 * If the resource bundle is {@code null}, then the {@code msg} string is not
1296 * localized.
1297 * <p>
1298 * @param level One of the message level identifiers, e.g., SEVERE
1299 * @param bundle Resource bundle to localize {@code msg},
1300 * can be {@code null}.
1301 * @param msg The string message (or a key in the message catalog)
1302 * @param params Parameters to the message (optional, may be none).
1303 * @since 1.9
1304 */
1305 public void logrb(Level level, ResourceBundle bundle, String msg, Object... params) {
1306 if (!isLoggable(level)) {
1307 return;
1308 }
1309 LogRecord lr = new LogRecord(level, msg);
1310 if (params != null && params.length != 0) {
1311 lr.setParameters(params);
1312 }
1313 doLog(lr, bundle);
1314 }
1315
1316 /**
1317 * Log a message, specifying source class, method, and resource bundle name,
1318 * with associated Throwable information.
1319 * <p>
1320 * If the logger is currently enabled for the given message
1321 * level then the given arguments are stored in a LogRecord
1322 * which is forwarded to all registered output handlers.
1323 * <p>
1324 * The msg string is localized using the named resource bundle. If the
1325 * resource bundle name is null, or an empty String or invalid
1326 * then the msg string is not localized.
1327 * <p>
1328 * Note that the thrown argument is stored in the LogRecord thrown
1329 * property, rather than the LogRecord parameters property. Thus it is
1330 * processed specially by output Formatters and is not treated
1331 * as a formatting parameter to the LogRecord message property.
1332 *
1333 * @param level One of the message level identifiers, e.g., SEVERE
1334 * @param sourceClass name of class that issued the logging request
1335 * @param sourceMethod name of method that issued the logging request
1336 * @param bundleName name of resource bundle to localize msg,
1337 * can be null
1338 * @param msg The string message (or a key in the message catalog)
1339 * @param thrown Throwable associated with log message.
1340 * @deprecated Use {@link #logrb(java.util.logging.Level, java.lang.String,
1341 * java.lang.String, java.util.ResourceBundle, java.lang.String,
1342 * java.lang.Throwable)} instead.
1343 */
1344 @Deprecated
1345 public void logrb(Level level, String sourceClass, String sourceMethod,
1346 String bundleName, String msg, Throwable thrown) {
1347 if (!isLoggable(level)) {
1348 return;
1349 }
1350 LogRecord lr = new LogRecord(level, msg);
1351 lr.setSourceClassName(sourceClass);
1352 lr.setSourceMethodName(sourceMethod);
1353 lr.setThrown(thrown);
1354 doLog(lr, bundleName);
1355 }
1356
1357 /**
1358 * Log a message, specifying source class, method, and resource bundle,
1359 * with associated Throwable information.
1360 * <p>
1361 * If the logger is currently enabled for the given message
1362 * level then the given arguments are stored in a LogRecord
1363 * which is forwarded to all registered output handlers.
1364 * <p>
1365 * The {@code msg} string is localized using the given resource bundle.
1366 * If the resource bundle is {@code null}, then the {@code msg} string is not
1367 * localized.
1368 * <p>
1369 * Note that the thrown argument is stored in the LogRecord thrown
1370 * property, rather than the LogRecord parameters property. Thus it is
1371 * processed specially by output Formatters and is not treated
1372 * as a formatting parameter to the LogRecord message property.
1373 *
1374 * @param level One of the message level identifiers, e.g., SEVERE
1375 * @param sourceClass Name of the class that issued the logging request
1376 * @param sourceMethod Name of the method that issued the logging request
1377 * @param bundle Resource bundle to localize {@code msg},
1378 * can be {@code null}
1379 * @param msg The string message (or a key in the message catalog)
1380 * @param thrown Throwable associated with the log message.
1381 * @since 1.8
1382 */
1383 public void logrb(Level level, String sourceClass, String sourceMethod,
1384 ResourceBundle bundle, String msg, Throwable thrown) {
1385 if (!isLoggable(level)) {
1386 return;
1387 }
1388 LogRecord lr = new LogRecord(level, msg);
1389 lr.setSourceClassName(sourceClass);
1390 lr.setSourceMethodName(sourceMethod);
1391 lr.setThrown(thrown);
1392 doLog(lr, bundle);
1393 }
1394
1395 /**
1396 * Log a message, specifying source class, method, and resource bundle,
1397 * with associated Throwable information.
1398 * <p>
1399 * If the logger is currently enabled for the given message
1400 * level then the given arguments are stored in a LogRecord
1401 * which is forwarded to all registered output handlers.
1402 * <p>
1403 * The {@code msg} string is localized using the given resource bundle.
1404 * If the resource bundle is {@code null}, then the {@code msg} string is not
1405 * localized.
1406 * <p>
1407 * Note that the thrown argument is stored in the LogRecord thrown
1408 * property, rather than the LogRecord parameters property. Thus it is
1409 * processed specially by output Formatters and is not treated
1410 * as a formatting parameter to the LogRecord message property.
1411 * <p>
1412 * @param level One of the message level identifiers, e.g., SEVERE
1413 * @param bundle Resource bundle to localize {@code msg},
1414 * can be {@code null}
1415 * @param msg The string message (or a key in the message catalog)
1416 * @param thrown Throwable associated with the log message.
1417 * @since 1.9
1418 */
1419 public void logrb(Level level, ResourceBundle bundle, String msg,
1420 Throwable thrown) {
1421 if (!isLoggable(level)) {
1422 return;
1423 }
1424 LogRecord lr = new LogRecord(level, msg);
1425 lr.setThrown(thrown);
1426 doLog(lr, bundle);
1427 }
1428
1429 //======================================================================
1430 // Start of convenience methods for logging method entries and returns.
1431 //======================================================================
1432
1433 /**
1434 * Log a method entry.
1435 * <p>
1436 * This is a convenience method that can be used to log entry
1437 * to a method. A LogRecord with message "ENTRY", log level
1438 * FINER, and the given sourceMethod and sourceClass is logged.
1439 *
1440 * @param sourceClass name of class that issued the logging request
1441 * @param sourceMethod name of method that is being entered
1442 */
1443 public void entering(String sourceClass, String sourceMethod) {
1444 logp(Level.FINER, sourceClass, sourceMethod, "ENTRY");
1445 }
1446
1447 /**
1448 * Log a method entry, with one parameter.
1449 * <p>
1450 * This is a convenience method that can be used to log entry
1451 * to a method. A LogRecord with message "ENTRY {0}", log level
1452 * FINER, and the given sourceMethod, sourceClass, and parameter
1453 * is logged.
1454 *
1455 * @param sourceClass name of class that issued the logging request
1456 * @param sourceMethod name of method that is being entered
1457 * @param param1 parameter to the method being entered
1458 */
1459 public void entering(String sourceClass, String sourceMethod, Object param1) {
1460 logp(Level.FINER, sourceClass, sourceMethod, "ENTRY {0}", param1);
1461 }
1462
1463 /**
1464 * Log a method entry, with an array of parameters.
1465 * <p>
1466 * This is a convenience method that can be used to log entry
1467 * to a method. A LogRecord with message "ENTRY" (followed by a
1468 * format {N} indicator for each entry in the parameter array),
1469 * log level FINER, and the given sourceMethod, sourceClass, and
1470 * parameters is logged.
1471 *
1472 * @param sourceClass name of class that issued the logging request
1473 * @param sourceMethod name of method that is being entered
1474 * @param params array of parameters to the method being entered
1475 */
1476 public void entering(String sourceClass, String sourceMethod, Object params[]) {
1477 String msg = "ENTRY";
1478 if (params == null ) {
1479 logp(Level.FINER, sourceClass, sourceMethod, msg);
1480 return;
1481 }
1482 if (!isLoggable(Level.FINER)) return;
1483 if (params.length > 0) {
1484 final StringBuilder b = new StringBuilder(msg);
1485 for (int i = 0; i < params.length; i++) {
1486 b.append(' ').append('{').append(i).append('}');
1487 }
1488 msg = b.toString();
1489 }
1490 logp(Level.FINER, sourceClass, sourceMethod, msg, params);
1491 }
1492
1493 /**
1494 * Log a method return.
1495 * <p>
1496 * This is a convenience method that can be used to log returning
1497 * from a method. A LogRecord with message "RETURN", log level
1498 * FINER, and the given sourceMethod and sourceClass is logged.
1499 *
1500 * @param sourceClass name of class that issued the logging request
1501 * @param sourceMethod name of the method
1502 */
1503 public void exiting(String sourceClass, String sourceMethod) {
1504 logp(Level.FINER, sourceClass, sourceMethod, "RETURN");
1505 }
1506
1507
1508 /**
1509 * Log a method return, with result object.
1510 * <p>
1511 * This is a convenience method that can be used to log returning
1512 * from a method. A LogRecord with message "RETURN {0}", log level
1513 * FINER, and the gives sourceMethod, sourceClass, and result
1514 * object is logged.
1515 *
1516 * @param sourceClass name of class that issued the logging request
1517 * @param sourceMethod name of the method
1518 * @param result Object that is being returned
1519 */
1520 public void exiting(String sourceClass, String sourceMethod, Object result) {
1521 logp(Level.FINER, sourceClass, sourceMethod, "RETURN {0}", result);
1522 }
1523
1524 /**
1525 * Log throwing an exception.
1526 * <p>
1527 * This is a convenience method to log that a method is
1528 * terminating by throwing an exception. The logging is done
1529 * using the FINER level.
1530 * <p>
1531 * If the logger is currently enabled for the given message
1532 * level then the given arguments are stored in a LogRecord
1533 * which is forwarded to all registered output handlers. The
1534 * LogRecord's message is set to "THROW".
1535 * <p>
1536 * Note that the thrown argument is stored in the LogRecord thrown
1537 * property, rather than the LogRecord parameters property. Thus it is
1538 * processed specially by output Formatters and is not treated
1539 * as a formatting parameter to the LogRecord message property.
1540 *
1541 * @param sourceClass name of class that issued the logging request
1542 * @param sourceMethod name of the method.
1543 * @param thrown The Throwable that is being thrown.
1544 */
1545 public void throwing(String sourceClass, String sourceMethod, Throwable thrown) {
1546 if (!isLoggable(Level.FINER)) {
1547 return;
1548 }
1549 LogRecord lr = new LogRecord(Level.FINER, "THROW");
1550 lr.setSourceClassName(sourceClass);
1551 lr.setSourceMethodName(sourceMethod);
1552 lr.setThrown(thrown);
1553 doLog(lr);
1554 }
1555
1556 //=======================================================================
1557 // Start of simple convenience methods using level names as method names
1558 //=======================================================================
1559
1560 /**
1561 * Log a SEVERE message.
1562 * <p>
1563 * If the logger is currently enabled for the SEVERE message
1564 * level then the given message is forwarded to all the
1565 * registered output Handler objects.
1566 *
1567 * @param msg The string message (or a key in the message catalog)
1568 */
1569 public void severe(String msg) {
1570 log(Level.SEVERE, msg);
1571 }
1572
1573 /**
1574 * Log a WARNING message.
1575 * <p>
1576 * If the logger is currently enabled for the WARNING message
1577 * level then the given message is forwarded to all the
1578 * registered output Handler objects.
1579 *
1580 * @param msg The string message (or a key in the message catalog)
1581 */
1582 public void warning(String msg) {
1583 log(Level.WARNING, msg);
1584 }
1585
1586 /**
1587 * Log an INFO message.
1588 * <p>
1589 * If the logger is currently enabled for the INFO message
1590 * level then the given message is forwarded to all the
1591 * registered output Handler objects.
1592 *
1593 * @param msg The string message (or a key in the message catalog)
1594 */
1595 public void info(String msg) {
1596 log(Level.INFO, msg);
1597 }
1598
1599 /**
1600 * Log a CONFIG message.
1601 * <p>
1602 * If the logger is currently enabled for the CONFIG message
1603 * level then the given message is forwarded to all the
1604 * registered output Handler objects.
1605 *
1606 * @param msg The string message (or a key in the message catalog)
1607 */
1608 public void config(String msg) {
1609 log(Level.CONFIG, msg);
1610 }
1611
1612 /**
1613 * Log a FINE message.
1614 * <p>
1615 * If the logger is currently enabled for the FINE message
1616 * level then the given message is forwarded to all the
1617 * registered output Handler objects.
1618 *
1619 * @param msg The string message (or a key in the message catalog)
1620 */
1621 public void fine(String msg) {
1622 log(Level.FINE, msg);
1623 }
1624
1625 /**
1626 * Log a FINER message.
1627 * <p>
1628 * If the logger is currently enabled for the FINER message
1629 * level then the given message is forwarded to all the
1630 * registered output Handler objects.
1631 *
1632 * @param msg The string message (or a key in the message catalog)
1633 */
1634 public void finer(String msg) {
1635 log(Level.FINER, msg);
1636 }
1637
1638 /**
1639 * Log a FINEST message.
1640 * <p>
1641 * If the logger is currently enabled for the FINEST message
1642 * level then the given message is forwarded to all the
1643 * registered output Handler objects.
1644 *
1645 * @param msg The string message (or a key in the message catalog)
1646 */
1647 public void finest(String msg) {
1648 log(Level.FINEST, msg);
1649 }
1650
1651 //=======================================================================
1652 // Start of simple convenience methods using level names as method names
1653 // and use Supplier<String>
1654 //=======================================================================
1655
1656 /**
1657 * Log a SEVERE message, which is only to be constructed if the logging
1658 * level is such that the message will actually be logged.
1659 * <p>
1660 * If the logger is currently enabled for the SEVERE message
1661 * level then the message is constructed by invoking the provided
1662 * supplier function and forwarded to all the registered output
1663 * Handler objects.
1664 *
1665 * @param msgSupplier A function, which when called, produces the
1666 * desired log message
1667 * @since 1.8
1668 */
1669 public void severe(Supplier<String> msgSupplier) {
1670 log(Level.SEVERE, msgSupplier);
1671 }
1672
1673 /**
1674 * Log a WARNING message, which is only to be constructed if the logging
1675 * level is such that the message will actually be logged.
1676 * <p>
1677 * If the logger is currently enabled for the WARNING message
1678 * level then the message is constructed by invoking the provided
1679 * supplier function and forwarded to all the registered output
1680 * Handler objects.
1681 *
1682 * @param msgSupplier A function, which when called, produces the
1683 * desired log message
1684 * @since 1.8
1685 */
1686 public void warning(Supplier<String> msgSupplier) {
1687 log(Level.WARNING, msgSupplier);
1688 }
1689
1690 /**
1691 * Log a INFO message, which is only to be constructed if the logging
1692 * level is such that the message will actually be logged.
1693 * <p>
1694 * If the logger is currently enabled for the INFO message
1695 * level then the message is constructed by invoking the provided
1696 * supplier function and forwarded to all the registered output
1697 * Handler objects.
1698 *
1699 * @param msgSupplier A function, which when called, produces the
1700 * desired log message
1701 * @since 1.8
1702 */
1703 public void info(Supplier<String> msgSupplier) {
1704 log(Level.INFO, msgSupplier);
1705 }
1706
1707 /**
1708 * Log a CONFIG message, which is only to be constructed if the logging
1709 * level is such that the message will actually be logged.
1710 * <p>
1711 * If the logger is currently enabled for the CONFIG message
1712 * level then the message is constructed by invoking the provided
1713 * supplier function and forwarded to all the registered output
1714 * Handler objects.
1715 *
1716 * @param msgSupplier A function, which when called, produces the
1717 * desired log message
1718 * @since 1.8
1719 */
1720 public void config(Supplier<String> msgSupplier) {
1721 log(Level.CONFIG, msgSupplier);
1722 }
1723
1724 /**
1725 * Log a FINE message, which is only to be constructed if the logging
1726 * level is such that the message will actually be logged.
1727 * <p>
1728 * If the logger is currently enabled for the FINE message
1729 * level then the message is constructed by invoking the provided
1730 * supplier function and forwarded to all the registered output
1731 * Handler objects.
1732 *
1733 * @param msgSupplier A function, which when called, produces the
1734 * desired log message
1735 * @since 1.8
1736 */
1737 public void fine(Supplier<String> msgSupplier) {
1738 log(Level.FINE, msgSupplier);
1739 }
1740
1741 /**
1742 * Log a FINER message, which is only to be constructed if the logging
1743 * level is such that the message will actually be logged.
1744 * <p>
1745 * If the logger is currently enabled for the FINER message
1746 * level then the message is constructed by invoking the provided
1747 * supplier function and forwarded to all the registered output
1748 * Handler objects.
1749 *
1750 * @param msgSupplier A function, which when called, produces the
1751 * desired log message
1752 * @since 1.8
1753 */
1754 public void finer(Supplier<String> msgSupplier) {
1755 log(Level.FINER, msgSupplier);
1756 }
1757
1758 /**
1759 * Log a FINEST message, which is only to be constructed if the logging
1760 * level is such that the message will actually be logged.
1761 * <p>
1762 * If the logger is currently enabled for the FINEST message
1763 * level then the message is constructed by invoking the provided
1764 * supplier function and forwarded to all the registered output
1765 * Handler objects.
1766 *
1767 * @param msgSupplier A function, which when called, produces the
1768 * desired log message
1769 * @since 1.8
1770 */
1771 public void finest(Supplier<String> msgSupplier) {
1772 log(Level.FINEST, msgSupplier);
1773 }
1774
1775 //================================================================
1776 // End of convenience methods
1777 //================================================================
1778
1779 /**
1780 * Set the log level specifying which message levels will be
1781 * logged by this logger. Message levels lower than this
1782 * value will be discarded. The level value Level.OFF
1783 * can be used to turn off logging.
1784 * <p>
1785 * If the new level is null, it means that this node should
1786 * inherit its level from its nearest ancestor with a specific
1787 * (non-null) level value.
1788 *
1789 * @param newLevel the new value for the log level (may be null)
1790 * @throws SecurityException if a security manager exists,
1791 * this logger is not anonymous, and the caller
1792 * does not have LoggingPermission("control").
1793 */
1794 public void setLevel(Level newLevel) throws SecurityException {
1795 checkPermission();
1796 synchronized (treeLock) {
1797 levelObject = newLevel;
1798 updateEffectiveLevel();
1799 }
1800 }
1801
1802 final boolean isLevelInitialized() {
1803 return levelObject != null;
1804 }
1805
1806 /**
1807 * Get the log Level that has been specified for this Logger.
1808 * The result may be null, which means that this logger's
1809 * effective level will be inherited from its parent.
1810 *
1811 * @return this Logger's level
1812 */
1813 public Level getLevel() {
1814 return levelObject;
1815 }
1816
1817 /**
1818 * Check if a message of the given level would actually be logged
1819 * by this logger. This check is based on the Loggers effective level,
1820 * which may be inherited from its parent.
1821 *
1822 * @param level a message logging level
1823 * @return true if the given message level is currently being logged.
1824 */
1825 public boolean isLoggable(Level level) {
1826 if (level.intValue() < levelValue || levelValue == offValue) {
1827 return false;
1828 }
1829 return true;
1830 }
1831
1832 /**
1833 * Get the name for this logger.
1834 * @return logger name. Will be null for anonymous Loggers.
1835 */
1836 public String getName() {
1837 return name;
1838 }
1839
1840 /**
1841 * Add a log Handler to receive logging messages.
1842 * <p>
1843 * By default, Loggers also send their output to their parent logger.
1844 * Typically the root Logger is configured with a set of Handlers
1845 * that essentially act as default handlers for all loggers.
1846 *
1847 * @param handler a logging Handler
1848 * @throws SecurityException if a security manager exists,
1849 * this logger is not anonymous, and the caller
1850 * does not have LoggingPermission("control").
1851 */
1852 public void addHandler(Handler handler) throws SecurityException {
1853 Objects.requireNonNull(handler);
1854 checkPermission();
1855 handlers.add(handler);
1856 }
1857
1858 /**
1859 * Remove a log Handler.
1860 * <P>
1861 * Returns silently if the given Handler is not found or is null
1862 *
1863 * @param handler a logging Handler
1864 * @throws SecurityException if a security manager exists,
1865 * this logger is not anonymous, and the caller
1866 * does not have LoggingPermission("control").
1867 */
1868 public void removeHandler(Handler handler) throws SecurityException {
1869 checkPermission();
1870 if (handler == null) {
1871 return;
1872 }
1873 handlers.remove(handler);
1874 }
1875
1876 /**
1877 * Get the Handlers associated with this logger.
1878 *
1879 * @return an array of all registered Handlers
1880 */
1881 public Handler[] getHandlers() {
1882 return accessCheckedHandlers();
1883 }
1884
1885 // This method should ideally be marked final - but unfortunately
1886 // it needs to be overridden by LogManager.RootLogger
1887 Handler[] accessCheckedHandlers() {
1888 return handlers.toArray(emptyHandlers);
1889 }
1890
1891 /**
1892 * Specify whether or not this logger should send its output
1893 * to its parent Logger. This means that any LogRecords will
1894 * also be written to the parent's Handlers, and potentially
1895 * to its parent, recursively up the namespace.
1896 *
1897 * @param useParentHandlers true if output is to be sent to the
1898 * logger's parent.
1899 * @throws SecurityException if a security manager exists,
1900 * this logger is not anonymous, and the caller
1901 * does not have LoggingPermission("control").
1902 */
1903 public void setUseParentHandlers(boolean useParentHandlers) {
1904 checkPermission();
1905 this.useParentHandlers = useParentHandlers;
1906 }
1907
1908 /**
1909 * Discover whether or not this logger is sending its output
1910 * to its parent logger.
1911 *
1912 * @return true if output is to be sent to the logger's parent
1913 */
1914 public boolean getUseParentHandlers() {
1915 return useParentHandlers;
1916 }
1917
1918 private static ResourceBundle findSystemResourceBundle(final Locale locale) {
1919 // the resource bundle is in a restricted package
1920 return AccessController.doPrivileged(new PrivilegedAction<ResourceBundle>() {
1921 @Override
1922 public ResourceBundle run() {
1923 try {
1924 return ResourceBundle.getBundle(SYSTEM_LOGGER_RB_NAME,
1925 locale,
1926 ClassLoader.getSystemClassLoader());
1927 } catch (MissingResourceException e) {
1928 throw new InternalError(e.toString());
1929 }
1930 }
1931 });
1932 }
1933
1934 /**
1935 * Private utility method to map a resource bundle name to an
1936 * actual resource bundle, using a simple one-entry cache.
1937 * Returns null for a null name.
1938 * May also return null if we can't find the resource bundle and
1939 * there is no suitable previous cached value.
1940 *
1941 * @param name the ResourceBundle to locate
1942 * @param userCallersClassLoader if true search using the caller's ClassLoader
1943 * @return ResourceBundle specified by name or null if not found
1944 */
1945 private synchronized ResourceBundle findResourceBundle(String name,
1946 boolean useCallersClassLoader) {
1947 // For all lookups, we first check the thread context class loader
1948 // if it is set. If not, we use the system classloader. If we
1949 // still haven't found it we use the callersClassLoaderRef if it
1950 // is set and useCallersClassLoader is true. We set
1951 // callersClassLoaderRef initially upon creating the logger with a
1952 // non-null resource bundle name.
1953
1954 // Return a null bundle for a null name.
1955 if (name == null) {
1956 return null;
1957 }
1958
1959 Locale currentLocale = Locale.getDefault();
1960 final LoggerBundle lb = loggerBundle;
1961
1962 // Normally we should hit on our simple one entry cache.
1963 if (lb.userBundle != null &&
1964 name.equals(lb.resourceBundleName)) {
1965 return lb.userBundle;
1966 } else if (catalog != null && currentLocale.equals(catalogLocale)
1967 && name.equals(catalogName)) {
1968 return catalog;
1969 }
1970
1971 if (name.equals(SYSTEM_LOGGER_RB_NAME)) {
1972 catalog = findSystemResourceBundle(currentLocale);
1973 catalogName = name;
1974 catalogLocale = currentLocale;
1975 return catalog;
1976 }
1977
1978 // Use the thread's context ClassLoader. If there isn't one, use the
1979 // {@linkplain java.lang.ClassLoader#getSystemClassLoader() system ClassLoader}.
1980 ClassLoader cl = Thread.currentThread().getContextClassLoader();
1981 if (cl == null) {
1982 cl = ClassLoader.getSystemClassLoader();
1983 }
1984 try {
1985 catalog = ResourceBundle.getBundle(name, currentLocale, cl);
1986 catalogName = name;
1987 catalogLocale = currentLocale;
1988 return catalog;
1989 } catch (MissingResourceException ex) {
1990 // We can't find the ResourceBundle in the default
1991 // ClassLoader. Drop through.
1992 }
1993
1994 if (useCallersClassLoader) {
1995 // Try with the caller's ClassLoader
1996 ClassLoader callersClassLoader = getCallersClassLoader();
1997
1998 if (callersClassLoader == null || callersClassLoader == cl) {
1999 return null;
2000 }
2001
2002 try {
2003 catalog = ResourceBundle.getBundle(name, currentLocale,
2004 callersClassLoader);
2005 catalogName = name;
2006 catalogLocale = currentLocale;
2007 return catalog;
2008 } catch (MissingResourceException ex) {
2009 return null; // no luck
2010 }
2011 } else {
2012 return null;
2013 }
2014 }
2015
2016 // Private utility method to initialize our one entry
2017 // resource bundle name cache and the callers ClassLoader
2018 // Note: for consistency reasons, we are careful to check
2019 // that a suitable ResourceBundle exists before setting the
2020 // resourceBundleName field.
2021 // Synchronized to prevent races in setting the fields.
2022 private synchronized void setupResourceInfo(String name,
2023 Class<?> callersClass) {
2024 final LoggerBundle lb = loggerBundle;
2025 if (lb.resourceBundleName != null) {
2026 // this Logger already has a ResourceBundle
2027
2028 if (lb.resourceBundleName.equals(name)) {
2029 // the names match so there is nothing more to do
2030 return;
2031 }
2032
2033 // cannot change ResourceBundles once they are set
2034 throw new IllegalArgumentException(
2035 lb.resourceBundleName + " != " + name);
2036 }
2037
2038 if (name == null) {
2039 return;
2040 }
2041
2042 setCallersClassLoaderRef(callersClass);
2043 if (isSystemLogger && getCallersClassLoader() != null) {
2044 checkPermission();
2045 }
2046 if (findResourceBundle(name, true) == null) {
2047 // We've failed to find an expected ResourceBundle.
2048 // unset the caller's ClassLoader since we were unable to find the
2049 // the bundle using it
2050 this.callersClassLoaderRef = null;
2051 throw new MissingResourceException("Can't find " + name + " bundle",
2052 name, "");
2053 }
2054
2055 // if lb.userBundle is not null we won't reach this line.
2056 assert lb.userBundle == null;
2057 loggerBundle = LoggerBundle.get(name, null);
2058 }
2059
2060 /**
2061 * Sets a resource bundle on this logger.
2062 * All messages will be logged using the given resource bundle for its
2063 * specific {@linkplain ResourceBundle#getLocale locale}.
2064 * @param bundle The resource bundle that this logger shall use.
2065 * @throws NullPointerException if the given bundle is {@code null}.
2066 * @throws IllegalArgumentException if the given bundle doesn't have a
2067 * {@linkplain ResourceBundle#getBaseBundleName base name},
2068 * or if this logger already has a resource bundle set but
2069 * the given bundle has a different base name.
2070 * @throws SecurityException if a security manager exists,
2071 * this logger is not anonymous, and the caller
2072 * does not have LoggingPermission("control").
2073 * @since 1.8
2074 */
2075 public void setResourceBundle(ResourceBundle bundle) {
2076 checkPermission();
2077
2078 // Will throw NPE if bundle is null.
2079 final String baseName = bundle.getBaseBundleName();
2080
2081 // bundle must have a name
2082 if (baseName == null || baseName.isEmpty()) {
2083 throw new IllegalArgumentException("resource bundle must have a name");
2084 }
2085
2086 synchronized (this) {
2087 LoggerBundle lb = loggerBundle;
2088 final boolean canReplaceResourceBundle = lb.resourceBundleName == null
2089 || lb.resourceBundleName.equals(baseName);
2090
2091 if (!canReplaceResourceBundle) {
2092 throw new IllegalArgumentException("can't replace resource bundle");
2093 }
2094
2095
2096 loggerBundle = LoggerBundle.get(baseName, bundle);
2097 }
2098 }
2099
2100 /**
2101 * Return the parent for this Logger.
2102 * <p>
2103 * This method returns the nearest extant parent in the namespace.
2104 * Thus if a Logger is called "a.b.c.d", and a Logger called "a.b"
2105 * has been created but no logger "a.b.c" exists, then a call of
2106 * getParent on the Logger "a.b.c.d" will return the Logger "a.b".
2107 * <p>
2108 * The result will be null if it is called on the root Logger
2109 * in the namespace.
2110 *
2111 * @return nearest existing parent Logger
2112 */
2113 public Logger getParent() {
2114 // Note: this used to be synchronized on treeLock. However, this only
2115 // provided memory semantics, as there was no guarantee that the caller
2116 // would synchronize on treeLock (in fact, there is no way for external
2117 // callers to so synchronize). Therefore, we have made parent volatile
2118 // instead.
2119 return parent;
2120 }
2121
2122 /**
2123 * Set the parent for this Logger. This method is used by
2124 * the LogManager to update a Logger when the namespace changes.
2125 * <p>
2126 * It should not be called from application code.
2127 *
2128 * @param parent the new parent logger
2129 * @throws SecurityException if a security manager exists and if
2130 * the caller does not have LoggingPermission("control").
2131 */
2132 public void setParent(Logger parent) {
2133 if (parent == null) {
2134 throw new NullPointerException();
2135 }
2136
2137 // check permission for all loggers, including anonymous loggers
2138 if (manager == null) {
2139 manager = LogManager.getLogManager();
2140 }
2141 manager.checkPermission();
2142
2143 doSetParent(parent);
2144 }
2145
2146 // Private method to do the work for parenting a child
2147 // Logger onto a parent logger.
2148 private void doSetParent(Logger newParent) {
2149
2150 // System.err.println("doSetParent \"" + getName() + "\" \""
2151 // + newParent.getName() + "\"");
2152
2153 synchronized (treeLock) {
2154
2155 // Remove ourself from any previous parent.
2156 LogManager.LoggerWeakRef ref = null;
2157 if (parent != null) {
2158 // assert parent.kids != null;
2159 for (Iterator<LogManager.LoggerWeakRef> iter = parent.kids.iterator(); iter.hasNext(); ) {
2160 ref = iter.next();
2161 Logger kid = ref.get();
2162 if (kid == this) {
2163 // ref is used down below to complete the reparenting
2164 iter.remove();
2165 break;
2166 } else {
2167 ref = null;
2168 }
2169 }
2170 // We have now removed ourself from our parents' kids.
2171 }
2172
2173 // Set our new parent.
2174 parent = newParent;
2175 if (parent.kids == null) {
2176 parent.kids = new ArrayList<>(2);
2177 }
2178 if (ref == null) {
2179 // we didn't have a previous parent
2180 ref = manager.new LoggerWeakRef(this);
2181 }
2182 ref.setParentRef(new WeakReference<>(parent));
2183 parent.kids.add(ref);
2184
2185 // As a result of the reparenting, the effective level
2186 // may have changed for us and our children.
2187 updateEffectiveLevel();
2188
2189 }
2190 }
2191
2192 // Package-level method.
2193 // Remove the weak reference for the specified child Logger from the
2194 // kid list. We should only be called from LoggerWeakRef.dispose().
2195 final void removeChildLogger(LogManager.LoggerWeakRef child) {
2196 synchronized (treeLock) {
2197 for (Iterator<LogManager.LoggerWeakRef> iter = kids.iterator(); iter.hasNext(); ) {
2198 LogManager.LoggerWeakRef ref = iter.next();
2199 if (ref == child) {
2200 iter.remove();
2201 return;
2202 }
2203 }
2204 }
2205 }
2206
2207 // Recalculate the effective level for this node and
2208 // recursively for our children.
2209
2210 private void updateEffectiveLevel() {
2211 // assert Thread.holdsLock(treeLock);
2212
2213 // Figure out our current effective level.
2214 int newLevelValue;
2215 if (levelObject != null) {
2216 newLevelValue = levelObject.intValue();
2217 } else {
2218 if (parent != null) {
2219 newLevelValue = parent.levelValue;
2220 } else {
2221 // This may happen during initialization.
2222 newLevelValue = Level.INFO.intValue();
2223 }
2224 }
2225
2226 // If our effective value hasn't changed, we're done.
2227 if (levelValue == newLevelValue) {
2228 return;
2229 }
2230
2231 levelValue = newLevelValue;
2232
2233 // System.err.println("effective level: \"" + getName() + "\" := " + level);
2234
2235 // Recursively update the level on each of our kids.
2236 if (kids != null) {
2237 for (LogManager.LoggerWeakRef ref : kids) {
2238 Logger kid = ref.get();
2239 if (kid != null) {
2240 kid.updateEffectiveLevel();
2241 }
2242 }
2243 }
2244 }
2245
2246
2247 // Private method to get the potentially inherited
2248 // resource bundle and resource bundle name for this Logger.
2249 // This method never returns null.
2250 private LoggerBundle getEffectiveLoggerBundle() {
2251 final LoggerBundle lb = loggerBundle;
2252 if (lb.isSystemBundle()) {
2253 return SYSTEM_BUNDLE;
2254 }
2255
2256 // first take care of this logger
2257 final ResourceBundle b = getResourceBundle();
2258 if (b != null && b == lb.userBundle) {
2259 return lb;
2260 } else if (b != null) {
2261 // either lb.userBundle is null or getResourceBundle() is
2262 // overriden
2263 final String rbName = getResourceBundleName();
2264 return LoggerBundle.get(rbName, b);
2265 }
2266
2267 // no resource bundle was specified on this logger, look up the
2268 // parent stack.
2269 Logger target = this.parent;
2270 while (target != null) {
2271 final LoggerBundle trb = target.loggerBundle;
2272 if (trb.isSystemBundle()) {
2273 return SYSTEM_BUNDLE;
2274 }
2275 if (trb.userBundle != null) {
2276 return trb;
2277 }
2278 final String rbName = isSystemLogger
2279 // ancestor of a system logger is expected to be a system logger.
2280 // ignore resource bundle name if it's not.
2281 ? (target.isSystemLogger ? trb.resourceBundleName : null)
2282 : target.getResourceBundleName();
2283 if (rbName != null) {
2284 return LoggerBundle.get(rbName,
2285 findResourceBundle(rbName, true));
2286 }
2287 target = isSystemLogger ? target.parent : target.getParent();
2288 }
2289 return NO_RESOURCE_BUNDLE;
2290 }
2291
2292 }