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