/*

 * Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.util.logging;

import java.lang.ref.WeakReference;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.util.ArrayList;

import java.util.Iterator;

import java.util.Locale;

import java.util.MissingResourceException;

import java.util.Objects;

import java.util.ResourceBundle;

import java.util.concurrent.CopyOnWriteArrayList;

import java.util.function.Supplier;

import jdk.internal.access.JavaUtilResourceBundleAccess;

import jdk.internal.access.SharedSecrets;

import jdk.internal.reflect.CallerSensitive;

import jdk.internal.reflect.Reflection;

import static jdk.internal.logger.DefaultLoggerFinder.isSystem;

/**

 * A Logger object is used to log messages for a specific

 * system or application component.  Loggers are normally named,

 * using a hierarchical dot-separated namespace.  Logger names

 * can be arbitrary strings, but they should normally be based on

 * the package name or class name of the logged component, such

 * as java.net or javax.swing.  In addition it is possible to create

 * "anonymous" Loggers that are not stored in the Logger namespace.

 * <p>

 * Logger objects may be obtained by calls on one of the getLogger

 * factory methods.  These will either create a new Logger or

 * return a suitable existing Logger. It is important to note that

 * the Logger returned by one of the {@code getLogger} factory methods

 * may be garbage collected at any time if a strong reference to the

 * Logger is not kept.

 * <p>

 * Logging messages will be forwarded to registered Handler

 * objects, which can forward the messages to a variety of

 * destinations, including consoles, files, OS logs, etc.

 * <p>

 * Each Logger keeps track of a "parent" Logger, which is its

 * nearest existing ancestor in the Logger namespace.

 * <p>

 * Each Logger has a "Level" associated with it.  This reflects

 * a minimum Level that this logger cares about.  If a Logger's

 * level is set to {@code null}, then its effective level is inherited

 * from its parent, which may in turn obtain it recursively from its

 * parent, and so on up the tree.

 * <p>

 * The log level can be configured based on the properties from the

 * logging configuration file, as described in the description

 * of the LogManager class.  However it may also be dynamically changed

 * by calls on the Logger.setLevel method.  If a logger's level is

 * changed the change may also affect child loggers, since any child

 * logger that has {@code null} as its level will inherit its

 * effective level from its parent.

 * <p>

 * On each logging call the Logger initially performs a cheap

 * check of the request level (e.g., SEVERE or FINE) against the

 * effective log level of the logger.  If the request level is

 * lower than the log level, the logging call returns immediately.

 * <p>

 * After passing this initial (cheap) test, the Logger will allocate

 * a LogRecord to describe the logging message.  It will then call a

 * Filter (if present) to do a more detailed check on whether the

 * record should be published.  If that passes it will then publish

 * the LogRecord to its output Handlers.  By default, loggers also

 * publish to their parent's Handlers, recursively up the tree.

 * <p>

 * Each Logger may have a {@code ResourceBundle} associated with it.

 * The {@code ResourceBundle} may be specified by name, using the

 * {@link #getLogger(java.lang.String, java.lang.String)} factory

 * method, or by value - using the {@link

 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method.

 * This bundle will be used for localizing logging messages.

 * If a Logger does not have its own {@code ResourceBundle} or resource bundle

 * name, then it will inherit the {@code ResourceBundle} or resource bundle name

 * from its parent, recursively up the tree.

 * <p>

 * Most of the logger output methods take a "msg" argument.  This

 * msg argument may be either a raw value or a localization key.

 * During formatting, if the logger has (or inherits) a localization

 * {@code ResourceBundle} and if the {@code ResourceBundle} has a mapping for

 * the msg string, then the msg string is replaced by the localized value.

 * Otherwise the original msg string is used.  Typically, formatters use

 * java.text.MessageFormat style formatting to format parameters, so

 * for example a format string "{0} {1}" would format two parameters

 * as strings.

 * <p>

 * A set of methods alternatively take a "msgSupplier" instead of a "msg"

 * argument.  These methods take a {@link Supplier}{@code <String>} function

 * which is invoked to construct the desired log message only when the message

 * actually is to be logged based on the effective log level thus eliminating

 * unnecessary message construction. For example, if the developer wants to

 * log system health status for diagnosis, with the String-accepting version,

 * the code would look like:

 * <pre>{@code

 *

 *  class DiagnosisMessages {

 *    static String systemHealthStatus() {

 *      // collect system health information

 *      ...

 *    }

 *  }

 *  ...

 *  logger.log(Level.FINER, DiagnosisMessages.systemHealthStatus());

 * }</pre>

 * With the above code, the health status is collected unnecessarily even when

 * the log level FINER is disabled. With the Supplier-accepting version as

 * below, the status will only be collected when the log level FINER is

 * enabled.

 * <pre>{@code

 *

 *  logger.log(Level.FINER, DiagnosisMessages::systemHealthStatus);

 * }</pre>

 * <p>

 * When looking for a {@code ResourceBundle}, the logger will first look at

 * whether a bundle was specified using {@link

 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle}, and then

 * only whether a resource bundle name was specified through the {@link

 * #getLogger(java.lang.String, java.lang.String) getLogger} factory method.

 * If no {@code ResourceBundle} or no resource bundle name is found,

 * then it will use the nearest {@code ResourceBundle} or resource bundle

 * name inherited from its parent tree.<br>

 * When a {@code ResourceBundle} was inherited or specified through the

 * {@link

 * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method, then

 * that {@code ResourceBundle} will be used. Otherwise if the logger only

 * has or inherited a resource bundle name, then that resource bundle name

 * will be mapped to a {@code ResourceBundle} object, using the default Locale

 * at the time of logging.

 * <br id="ResourceBundleMapping">When mapping resource bundle names to

 * {@code ResourceBundle} objects, the logger will first try to use the

 * Thread's {@linkplain java.lang.Thread#getContextClassLoader() context class

 * loader} to map the given resource bundle name to a {@code ResourceBundle}.

 * If the thread context class loader is {@code null}, it will try the

 * {@linkplain java.lang.ClassLoader#getSystemClassLoader() system class loader}

 * instead.  If the {@code ResourceBundle} is still not found, it will use the

 * class loader of the first caller of the {@link

 * #getLogger(java.lang.String, java.lang.String) getLogger} factory method.

 * <p>

 * Formatting (including localization) is the responsibility of

 * the output Handler, which will typically call a Formatter.

 * <p>

 * Note that formatting need not occur synchronously.  It may be delayed

 * until a LogRecord is actually written to an external sink.

 * <p>

 * The logging methods are grouped in five main categories:

 * <ul>

 * <li><p>

 *     There are a set of "log" methods that take a log level, a message

 *     string, and optionally some parameters to the message string.

 * <li><p>

 *     There are a set of "logp" methods (for "log precise") that are

 *     like the "log" methods, but also take an explicit source class name

 *     and method name.

 * <li><p>

 *     There are a set of "logrb" method (for "log with resource bundle")

 *     that are like the "logp" method, but also take an explicit resource

 *     bundle object for use in localizing the log message.

 * <li><p>

 *     There are convenience methods for tracing method entries (the

 *     "entering" methods), method returns (the "exiting" methods) and

 *     throwing exceptions (the "throwing" methods).

 * <li><p>

 *     Finally, there are a set of convenience methods for use in the

 *     very simplest cases, when a developer simply wants to log a

 *     simple string at a given log level.  These methods are named

 *     after the standard Level names ("severe", "warning", "info", etc.)

 *     and take a single argument, a message string.

 * </ul>

 * <p>

 * For the methods that do not take an explicit source name and

 * method name, the Logging framework will make a "best effort"

 * to determine which class and method called into the logging method.

 * However, it is important to realize that this automatically inferred

 * information may only be approximate (or may even be quite wrong!).

 * Virtual machines are allowed to do extensive optimizations when

 * JITing and may entirely remove stack frames, making it impossible

 * to reliably locate the calling class and method.

 * <P>

 * All methods on Logger are multi-thread safe.

 * <p>

 * <b>Subclassing Information:</b> Note that a LogManager class may

 * provide its own implementation of named Loggers for any point in

 * the namespace.  Therefore, any subclasses of Logger (unless they

 * are implemented in conjunction with a new LogManager class) should

 * take care to obtain a Logger instance from the LogManager class and

 * should delegate operations such as "isLoggable" and "log(LogRecord)"

 * to that instance.  Note that in order to intercept all logging

 * output, subclasses need only override the log(LogRecord) method.

 * All the other logging methods are implemented as calls on this

 * log(LogRecord) method.

 *

 * @since 1.4

 */

public class Logger {

    private static final Handler emptyHandlers[] = new Handler[0];

    private static final int offValue = Level.OFF.intValue();

    static final String SYSTEM_LOGGER_RB_NAME = "sun.util.logging.resources.logging";

    // This class is immutable and it is important that it remains so.

    private static final class LoggerBundle {

        final String resourceBundleName; // Base name of the bundle.

        final ResourceBundle userBundle; // Bundle set through setResourceBundle.

        private LoggerBundle(String resourceBundleName, ResourceBundle bundle) {

            this.resourceBundleName = resourceBundleName;

            this.userBundle = bundle;

        }

        boolean isSystemBundle() {

            return SYSTEM_LOGGER_RB_NAME.equals(resourceBundleName);

        }

        static LoggerBundle get(String name, ResourceBundle bundle) {

            if (name == null && bundle == null) {

                return NO_RESOURCE_BUNDLE;

            } else if (SYSTEM_LOGGER_RB_NAME.equals(name) && bundle == null) {

                return SYSTEM_BUNDLE;

            } else {

                return new LoggerBundle(name, bundle);

            }

        }

    }

    // This instance will be shared by all loggers created by the system

    // code

    private static final LoggerBundle SYSTEM_BUNDLE =

            new LoggerBundle(SYSTEM_LOGGER_RB_NAME, null);

    // This instance indicates that no resource bundle has been specified yet,

    // and it will be shared by all loggers which have no resource bundle.

    private static final LoggerBundle NO_RESOURCE_BUNDLE =

            new LoggerBundle(null, null);

    // Calling SharedSecrets.getJavaUtilResourceBundleAccess()

    // forces the initialization of ResourceBundle.class, which

    // can be too early if the VM has not finished booting yet.

    private static final class RbAccess {

        static final JavaUtilResourceBundleAccess RB_ACCESS =

            SharedSecrets.getJavaUtilResourceBundleAccess();

    }

    // A value class that holds the logger configuration data.

    // This configuration can be shared between an application logger

    // and a system logger of the same name.

    private static final class ConfigurationData {

        // The delegate field is used to avoid races while

        // merging configuration. This will ensure that any pending

        // configuration action on an application logger will either

        // be finished before the merge happens, or will be forwarded

        // to the system logger configuration after the merge is completed.

        // By default delegate=this.

        private volatile ConfigurationData delegate;

        volatile boolean useParentHandlers;

        volatile Filter filter;

        volatile Level levelObject;

        volatile int levelValue;  // current effective level value

        final CopyOnWriteArrayList<Handler> handlers =

            new CopyOnWriteArrayList<>();

        ConfigurationData() {

            delegate = this;

            useParentHandlers = true;

            levelValue = Level.INFO.intValue();

        }

        void setUseParentHandlers(boolean flag) {

            useParentHandlers = flag;

            if (delegate != this) {

                // merge in progress - propagate value to system peer.

                final ConfigurationData system = delegate;

                synchronized (system) {

                    system.useParentHandlers = useParentHandlers;

                }

            }

        }

        void setFilter(Filter f) {

            filter = f;

            if (delegate != this) {

                // merge in progress - propagate value to system peer.

                final ConfigurationData system = delegate;

                synchronized (system) {

                    system.filter = filter;

                }

            }

        }

        void setLevelObject(Level l) {

            levelObject = l;

            if (delegate != this) {

                // merge in progress - propagate value to system peer.

                final ConfigurationData system = delegate;

                synchronized (system) {

                    system.levelObject = levelObject;

                }

            }

        }

        void setLevelValue(int v) {

            levelValue = v;

            if (delegate != this) {

                // merge in progress - propagate value to system peer.

                final ConfigurationData system = delegate;

                synchronized (system) {

                    system.levelValue = levelValue;

                }

            }

        }

        void addHandler(Handler h) {

            if (handlers.add(h)) {

                if (delegate != this) {

                    // merge in progress - propagate value to system peer.

                    final ConfigurationData system = delegate;

                    synchronized (system) {

                        system.handlers.addIfAbsent(h);

                    }

                }

            }

        }

        void removeHandler(Handler h) {

            if (handlers.remove(h)) {

                if (delegate != this) {

                    // merge in progress - propagate value to system peer.

                    final ConfigurationData system = delegate;

                    synchronized (system) {

                        system.handlers.remove(h);

                    }

                }

            }

        }

        ConfigurationData merge(Logger systemPeer) {

            if (!systemPeer.isSystemLogger) {

                // should never come here

                throw new InternalError("not a system logger");

            }

            ConfigurationData system = systemPeer.config;

            if (system == this) {

                // nothing to do

                return system;

            }

            synchronized (system) {

                // synchronize before checking on delegate to counter

                // race conditions where two threads might attempt to

                // merge concurrently

                if (delegate == system) {

                    // merge already performed;

                    return system;

                }

                // publish system as the temporary delegate configuration.

                // This should take care of potential race conditions where

                // an other thread might attempt to call e.g. setlevel on

                // the application logger while merge is in progress.

                // (see implementation of ConfigurationData::setLevel)

                delegate = system;

                // merge this config object data into the system config

                system.useParentHandlers = useParentHandlers;

                system.filter = filter;

                system.levelObject = levelObject;

                system.levelValue = levelValue;

                // Prevent race condition in case two threads attempt to merge

                // configuration and add handlers at the same time. We don't want

                // to add the same handlers twice.

                //

                // Handlers are created and loaded by LogManager.addLogger. If we

                // reach here, then it means that the application logger has

                // been created first and added with LogManager.addLogger, and the

                // system logger was created after - and no handler has been added

                // to it by LogManager.addLogger. Therefore, system.handlers

                // should be empty.

                //

                // A non empty cfg.handlers list indicates a race condition

                // where two threads might attempt to merge the configuration

                // or add handlers concurrently. Though of no consequence for

                // the other data (level etc...) this would be an issue if we

                // added the same handlers twice.

                //

                for (Handler h : handlers) {

                    if (!system.handlers.contains(h)) {

                        systemPeer.addHandler(h);

                    }

                }

                system.handlers.retainAll(handlers);

                system.handlers.addAllAbsent(handlers);

            }

            // sanity: update effective level after merging

            synchronized(treeLock) {

                systemPeer.updateEffectiveLevel();

            }

            return system;

        }

    }

    // The logger configuration data. Ideally, this should be final

    // for system loggers, and replace-once for application loggers.

    // When an application requests a logger by name, we do not know a-priori

    // whether that corresponds to a system logger name or not.

    // So if no system logger by that name already exists, we simply return an

    // application logger.

    // If a system class later requests a system logger of the same name, then

    // the application logger and system logger configurations will be merged

    // in a single instance of ConfigurationData that both loggers will share.

    private volatile ConfigurationData config;

    private volatile LogManager manager;

    private String name;

    private volatile LoggerBundle loggerBundle = NO_RESOURCE_BUNDLE;

    private boolean anonymous;

    // Cache to speed up behavior of findResourceBundle:

    private WeakReference<ResourceBundle> catalogRef;  // Cached resource bundle

    private String catalogName;         // name associated with catalog

    private Locale catalogLocale;       // locale associated with catalog

    // The fields relating to parent-child relationships and levels

    // are managed under a separate lock, the treeLock.

    private static final Object treeLock = new Object();

    // We keep weak references from parents to children, but strong

    // references from children to parents.

    private volatile Logger parent;    // our nearest parent.

    private ArrayList<LogManager.LoggerWeakRef> kids;   // WeakReferences to loggers that have us as parent

    private WeakReference<Module> callerModuleRef;

    private final boolean isSystemLogger;

    /**

     * GLOBAL_LOGGER_NAME is a name for the global logger.

     *

     * @since 1.6

     */

    public static final String GLOBAL_LOGGER_NAME = "global";

    /**

     * Return global logger object with the name Logger.GLOBAL_LOGGER_NAME.

     *

     * @return global logger object

     * @since 1.7

     */

    public static final Logger getGlobal() {

        // In order to break a cyclic dependence between the LogManager

        // and Logger static initializers causing deadlocks, the global

        // logger is created with a special constructor that does not

        // initialize its log manager.

        //

        // If an application calls Logger.getGlobal() before any logger

        // has been initialized, it is therefore possible that the

        // LogManager class has not been initialized yet, and therefore

        // Logger.global.manager will be null.

        //

        // In order to finish the initialization of the global logger, we

        // will therefore call LogManager.getLogManager() here.

        //

        // To prevent race conditions we also need to call

        // LogManager.getLogManager() unconditionally here.

        // Indeed we cannot rely on the observed value of global.manager,

        // because global.manager will become not null somewhere during

        // the initialization of LogManager.

        // If two threads are calling getGlobal() concurrently, one thread

        // will see global.manager null and call LogManager.getLogManager(),

        // but the other thread could come in at a time when global.manager

        // is already set although ensureLogManagerInitialized is not finished

        // yet...

        // Calling LogManager.getLogManager() unconditionally will fix that.

        LogManager.getLogManager();

        // Now the global LogManager should be initialized,

        // and the global logger should have been added to

        // it, unless we were called within the constructor of a LogManager

        // subclass installed as LogManager, in which case global.manager

        // would still be null, and global will be lazily initialized later on.

        return global;

    }

    /**

     * The "global" Logger object is provided as a convenience to developers

     * who are making casual use of the Logging package.  Developers

     * who are making serious use of the logging package (for example

     * in products) should create and use their own Logger objects,

     * with appropriate names, so that logging can be controlled on a

     * suitable per-Logger granularity. Developers also need to keep a

     * strong reference to their Logger objects to prevent them from

     * being garbage collected.

     *

     * @deprecated Initialization of this field is prone to deadlocks.

     * The field must be initialized by the Logger class initialization

     * which may cause deadlocks with the LogManager class initialization.

     * In such cases two class initialization wait for each other to complete.

     * The preferred way to get the global logger object is via the call

     * {@code Logger.getGlobal()}.

     * For compatibility with old JDK versions where the

     * {@code Logger.getGlobal()} is not available use the call

     * {@code Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)}

     * or {@code Logger.getLogger("global")}.

     */

    @Deprecated

    public static final Logger global = new Logger(GLOBAL_LOGGER_NAME);

    /**

     * Protected method to construct a logger for a named subsystem.

     * <p>

     * The logger will be initially configured with a null Level

     * and with useParentHandlers set to true.

     *

     * @param   name    A name for the logger.  This should

     *                          be a dot-separated name and should normally

     *                          be based on the package name or class name

     *                          of the subsystem, such as java.net

     *                          or javax.swing.  It may be null for anonymous Loggers.

     * @param   resourceBundleName  name of ResourceBundle to be used for localizing

     *                          messages for this logger.  May be null if none

     *                          of the messages require localization.

     * @throws MissingResourceException if the resourceBundleName is non-null and

     *             no corresponding resource can be found.

     */

    protected Logger(String name, String resourceBundleName) {

        this(name, resourceBundleName, null, LogManager.getLogManager(), false);

    }

    Logger(String name, String resourceBundleName, Module caller,

           LogManager manager, boolean isSystemLogger) {

        this.manager = manager;

        this.isSystemLogger = isSystemLogger;

        this.config = new ConfigurationData();

        this.name = name;

        setupResourceInfo(resourceBundleName, caller);

    }

    // Called by LogManager when a system logger is created

    // after a user logger of the same name.

    // Ensure that both loggers will share the same

    // configuration.

    final void mergeWithSystemLogger(Logger system) {

        // sanity checks

        if (!system.isSystemLogger

                || anonymous

                || name == null

                || !name.equals(system.name)) {

            // should never come here

            throw new InternalError("invalid logger merge");

        }

        checkPermission();

        final ConfigurationData cfg = config;

        if (cfg != system.config) {

            config = cfg.merge(system);

        }

    }

    private void setCallerModuleRef(Module callerModule) {

        if (callerModule != null) {

            this.callerModuleRef = new WeakReference<>(callerModule);

        }

    }

    private Module getCallerModule() {

        return (callerModuleRef != null)

                ? callerModuleRef.get()

                : null;

    }

    // This constructor is used only to create the global Logger.

    // It is needed to break a cyclic dependence between the LogManager

    // and Logger static initializers causing deadlocks.

    private Logger(String name) {

        // The manager field is not initialized here.

        this.name = name;

        this.isSystemLogger = true;

        config = new ConfigurationData();

    }

    // It is called from LoggerContext.addLocalLogger() when the logger

    // is actually added to a LogManager.

    void setLogManager(LogManager manager) {

        this.manager = manager;

    }

    private void checkPermission() throws SecurityException {

        if (!anonymous) {

            if (manager == null) {

                // Complete initialization of the global Logger.

                manager = LogManager.getLogManager();

            }

            manager.checkPermission();

        }

    }

    // Until all JDK code converted to call sun.util.logging.PlatformLogger

    // (see 7054233), we need to determine if Logger.getLogger is to add

    // a system logger or user logger.

    //

    // As an interim solution, if the immediate caller whose caller loader is

    // null, we assume it's a system logger and add it to the system context.

    // These system loggers only set the resource bundle to the given

    // resource bundle name (rather than the default system resource bundle).

    private static class SystemLoggerHelper {

        static boolean disableCallerCheck = getBooleanProperty("sun.util.logging.disableCallerCheck");

        private static boolean getBooleanProperty(final String key) {

            @SuppressWarnings("removal")

            String s = AccessController.doPrivileged(new PrivilegedAction<String>() {

                @Override

                public String run() {

                    return System.getProperty(key);

                }

            });

            return Boolean.parseBoolean(s);

        }

    }

    private static Logger demandLogger(String name, String resourceBundleName, Class<?> caller) {

        LogManager manager = LogManager.getLogManager();

        if (!SystemLoggerHelper.disableCallerCheck) {

            if (isSystem(caller.getModule())) {

                return manager.demandSystemLogger(name, resourceBundleName, caller);

            }

        }

        return manager.demandLogger(name, resourceBundleName, caller);

        // ends up calling new Logger(name, resourceBundleName, caller)

        // iff the logger doesn't exist already

    }

    /**

     * Find or create a logger for a named subsystem.  If a logger has

     * already been created with the given name it is returned.  Otherwise

     * a new logger is created.

     * <p>

     * If a new logger is created its log level will be configured

     * based on the LogManager configuration and it will be configured

     * to also send logging output to its parent's Handlers.  It will

     * be registered in the LogManager global namespace.

     * <p>

     * Note: The LogManager may only retain a weak reference to the newly

     * created Logger. It is important to understand that a previously

     * created Logger with the given name may be garbage collected at any

     * time if there is no strong reference to the Logger. In particular,

     * this means that two back-to-back calls like

     * {@code getLogger("MyLogger").log(...)} may use different Logger

     * objects named "MyLogger" if there is no strong reference to the

     * Logger named "MyLogger" elsewhere in the program.

     *

     * @param   name            A name for the logger.  This should

     *                          be a dot-separated name and should normally

     *                          be based on the package name or class name

     *                          of the subsystem, such as java.net

     *                          or javax.swing

     * @return a suitable Logger

     * @throws NullPointerException if the name is null.

     */

    // Synchronization is not required here. All synchronization for

    // adding a new Logger object is handled by LogManager.addLogger().

    @CallerSensitive

    public static Logger getLogger(String name) {

        // This method is intentionally not a wrapper around a call

        // to getLogger(name, resourceBundleName). If it were then

        // this sequence:

        //

        //     getLogger("Foo", "resourceBundleForFoo");

        //     getLogger("Foo");

        //

        // would throw an IllegalArgumentException in the second call

        // because the wrapper would result in an attempt to replace

        // the existing "resourceBundleForFoo" with null.

        return Logger.getLogger(name, Reflection.getCallerClass());

    }

    /**

     * Find or create a logger for a named subsystem on behalf

     * of the given caller.

     *

     * This method is called by {@link #getLogger(java.lang.String)} after

     * it has obtained a reference to its caller's class.

     *

     * @param   name            A name for the logger.

     * @param   callerClass     The class that called {@link

     *                          #getLogger(java.lang.String)}.

     * @return a suitable Logger for {@code callerClass}.

     */

    private static Logger getLogger(String name, Class<?> callerClass) {

        return demandLogger(name, null, callerClass);

    }

    /**

     * Find or create a logger for a named subsystem.  If a logger has

     * already been created with the given name it is returned.  Otherwise

     * a new logger is created.

     *

     * <p>

     * If a new logger is created its log level will be configured

     * based on the LogManager and it will be configured to also send logging

     * output to its parent's Handlers.  It will be registered in

     * the LogManager global namespace.

     * <p>

     * Note: The LogManager may only retain a weak reference to the newly

     * created Logger. It is important to understand that a previously

     * created Logger with the given name may be garbage collected at any

     * time if there is no strong reference to the Logger. In particular,

     * this means that two back-to-back calls like

     * {@code getLogger("MyLogger", ...).log(...)} may use different Logger

     * objects named "MyLogger" if there is no strong reference to the

     * Logger named "MyLogger" elsewhere in the program.

     * <p>

     * If the named Logger already exists and does not yet have a

     * localization resource bundle then the given resource bundle

     * name is used. If the named Logger already exists and has

     * a different resource bundle name then an IllegalArgumentException

     * is thrown.

     *

     * @param   name    A name for the logger.  This should

     *                          be a dot-separated name and should normally

     *                          be based on the package name or class name

     *                          of the subsystem, such as java.net

     *                          or javax.swing

     * @param   resourceBundleName  name of ResourceBundle to be used for localizing

     *                          messages for this logger. May be {@code null}

     *                          if none of the messages require localization.

     * @return a suitable Logger

     * @throws MissingResourceException if the resourceBundleName is non-null and

     *             no corresponding resource can be found.

     * @throws IllegalArgumentException if the Logger already exists and uses

     *             a different resource bundle name; or if

     *             {@code resourceBundleName} is {@code null} but the named

     *             logger has a resource bundle set.

     * @throws NullPointerException if the name is null.

     */

    // Synchronization is not required here. All synchronization for

    // adding a new Logger object is handled by LogManager.addLogger().

    @CallerSensitive

    public static Logger getLogger(String name, String resourceBundleName) {

        return Logger.getLogger(name, resourceBundleName, Reflection.getCallerClass());

    }

    /**

     * Find or create a logger for a named subsystem on behalf

     * of the given caller.

     *

     * This method is called by {@link

     * #getLogger(java.lang.String, java.lang.String)} after

     * it has obtained a reference to its caller's class.

     *

     * @param   name            A name for the logger.

     * @param   resourceBundleName  name of ResourceBundle to be used for localizing

     *                          messages for this logger. May be {@code null}

     *                          if none of the messages require localization.

     * @param   callerClass     The class that called {@link

     *                          #getLogger(java.lang.String, java.lang.String)}.

     *                          This class will also be used for locating the

     *                          resource bundle if {@code resourceBundleName} is

     *                          not {@code null}.

     * @return a suitable Logger for {@code callerClass}.

     */

    private static Logger getLogger(String name, String resourceBundleName,

                                    Class<?> callerClass) {

        Logger result = demandLogger(name, resourceBundleName, callerClass);

        // MissingResourceException or IllegalArgumentException can be

        // thrown by setupResourceInfo().

        // We have to set the callers ClassLoader here in case demandLogger

        // above found a previously created Logger.  This can happen, for

        // example, if Logger.getLogger(name) is called and subsequently

        // Logger.getLogger(name, resourceBundleName) is called.  In this case

        // we won't necessarily have the correct classloader saved away, so

        // we need to set it here, too.

        result.setupResourceInfo(resourceBundleName, callerClass);

        return result;

    }

    // package-private

    // Add a platform logger to the system context.

    // i.e. caller of sun.util.logging.PlatformLogger.getLogger

    static Logger getPlatformLogger(String name) {

        LogManager manager = LogManager.getLogManager();

        // all loggers in the system context will default to

        // the system logger's resource bundle - therefore the caller won't

        // be needed and can be null.

        Logger result = manager.demandSystemLogger(name, SYSTEM_LOGGER_RB_NAME, (Module)null);

        return result;

    }

    /**

     * Create an anonymous Logger.  The newly created Logger is not

     * registered in the LogManager namespace.  There will be no

     * access checks on updates to the logger.

     * <p>

     * This factory method is primarily intended for use from applets.

     * Because the resulting Logger is anonymous it can be kept private

     * by the creating class.  This removes the need for normal security

     * checks, which in turn allows untrusted applet code to update

     * the control state of the Logger.  For example an applet can do

     * a setLevel or an addHandler on an anonymous Logger.

     * <p>

     * Even although the new logger is anonymous, it is configured

     * to have the root logger ("") as its parent.  This means that

     * by default it inherits its effective level and handlers

     * from the root logger. Changing its parent via the

     * {@link #setParent(java.util.logging.Logger) setParent} method

     * will still require the security permission specified by that method.

     *

     * @return a newly created private Logger

     */

    public static Logger getAnonymousLogger() {

        return getAnonymousLogger(null);

    }

    /**

     * Create an anonymous Logger.  The newly created Logger is not

     * registered in the LogManager namespace.  There will be no

     * access checks on updates to the logger.

     * <p>

     * This factory method is primarily intended for use from applets.

     * Because the resulting Logger is anonymous it can be kept private

     * by the creating class.  This removes the need for normal security

     * checks, which in turn allows untrusted applet code to update

     * the control state of the Logger.  For example an applet can do

     * a setLevel or an addHandler on an anonymous Logger.

     * <p>

     * Even although the new logger is anonymous, it is configured

     * to have the root logger ("") as its parent.  This means that

     * by default it inherits its effective level and handlers

     * from the root logger.  Changing its parent via the

     * {@link #setParent(java.util.logging.Logger) setParent} method

     * will still require the security permission specified by that method.

     *

     * @param   resourceBundleName  name of ResourceBundle to be used for localizing

     *                          messages for this logger.

     *          May be null if none of the messages require localization.

     * @return a newly created private Logger

     * @throws MissingResourceException if the resourceBundleName is non-null and

     *             no corresponding resource can be found.

     */

    // Synchronization is not required here. All synchronization for

    // adding a new anonymous Logger object is handled by doSetParent().

    @CallerSensitive

    public static Logger getAnonymousLogger(String resourceBundleName) {

        LogManager manager = LogManager.getLogManager();

        // cleanup some Loggers that have been GC'ed

        manager.drainLoggerRefQueueBounded();

        final Class<?> callerClass = Reflection.getCallerClass();

        final Module module = callerClass.getModule();

        Logger result = new Logger(null, resourceBundleName,

                                   module, manager, false);

        result.anonymous = true;

        Logger root = manager.getLogger("");

        result.doSetParent(root);

        return result;

    }

    /**

     * Retrieve the localization resource bundle for this

     * logger.

     * This method will return a {@code ResourceBundle} that was either

     * set by the {@link

     * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method or

     * <a href="#ResourceBundleMapping">mapped from the

     * the resource bundle name</a> set via the {@link

     * Logger#getLogger(java.lang.String, java.lang.String) getLogger} factory

     * method for the current default locale.

     * <br>Note that if the result is {@code null}, then the Logger will use a resource

     * bundle or resource bundle name inherited from its parent.

     *

     * @return localization bundle (may be {@code null})

     */

    public ResourceBundle getResourceBundle() {

        return findResourceBundle(getResourceBundleName(), true);

    }

    /**

     * Retrieve the localization resource bundle name for this

     * logger.

     * This is either the name specified through the {@link

     * #getLogger(java.lang.String, java.lang.String) getLogger} factory method,

     * or the {@linkplain ResourceBundle#getBaseBundleName() base name} of the

     * ResourceBundle set through {@link

     * #setResourceBundle(java.util.ResourceBundle) setResourceBundle} method.

     * <br>Note that if the result is {@code null}, then the Logger will use a resource

     * bundle or resource bundle name inherited from its parent.

     *

     * @return localization bundle name (may be {@code null})

     */

    public String getResourceBundleName() {

        return loggerBundle.resourceBundleName;

    }

    /**

     * Set a filter to control output on this Logger.

     * <P>

     * After passing the initial "level" check, the Logger will

     * call this Filter to check if a log record should really

     * be published.

     *

     * @param   newFilter  a filter object (may be null)

     * @throws  SecurityException if a security manager exists,

     *          this logger is not anonymous, and the caller

     *          does not have LoggingPermission("control").

     */

    public void setFilter(Filter newFilter) throws SecurityException {

        checkPermission();

        config.setFilter(newFilter);

    }

    /**

     * Get the current filter for this Logger.

     *

     * @return  a filter object (may be null)

     */

    public Filter getFilter() {

        return config.filter;

    }

    /**

     * Log a LogRecord.

     * <p>

     * All the other logging methods in this class call through

     * this method to actually perform any logging.  Subclasses can

     * override this single method to capture all log activity.

     *

     * @param record the LogRecord to be published

     */

    public void log(LogRecord record) {

        if (!isLoggable(record.getLevel())) {

            return;

        }

        Filter theFilter = config.filter;

        if (theFilter != null && !theFilter.isLoggable(record)) {

            return;

        }

        // Post the LogRecord to all our Handlers, and then to

        // our parents' handlers, all the way up the tree.

        Logger logger = this;

        while (logger != null) {

            final Handler[] loggerHandlers = isSystemLogger

                ? logger.accessCheckedHandlers()

                : logger.getHandlers();

            for (Handler handler : loggerHandlers) {

                handler.publish(record);

            }

            final boolean useParentHdls = isSystemLogger

                ? logger.config.useParentHandlers

                : logger.getUseParentHandlers();

            if (!useParentHdls) {

                break;

            }

            logger = isSystemLogger ? logger.parent : logger.getParent();

        }

    }

    // private support method for logging.

    // We fill in the logger name, resource bundle name, and

    // resource bundle and then call "void log(LogRecord)".

    private void doLog(LogRecord lr) {

        lr.setLoggerName(name);

        final LoggerBundle lb = getEffectiveLoggerBundle();

        final ResourceBundle  bundle = lb.userBundle;

        final String ebname = lb.resourceBundleName;

        if (ebname != null && bundle != null) {

            lr.setResourceBundleName(ebname);

            lr.setResourceBundle(bundle);

        }

        log(lr);

    }

    //================================================================

    // Start of convenience methods WITHOUT className and methodName

    //================================================================

    /**

     * Log a message, with no arguments.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the given message is forwarded to all the

     * registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   msg     The string message (or a key in the message catalog)

     */

    public void log(Level level, String msg) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        doLog(lr);

    }

    /**

     * Log a message, which is only to be constructed if the logging level

     * is such that the message will actually be logged.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the message is constructed by invoking the provided

     * supplier function and forwarded to all the registered output

     * Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   msgSupplier   A function, which when called, produces the

     *                        desired log message

     * @since 1.8

     */

    public void log(Level level, Supplier<String> msgSupplier) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msgSupplier.get());

        doLog(lr);

    }

    /**

     * Log a message, with one object parameter.

     * <p>

     * If the logger is currently enabled for the given message

     * level then a corresponding LogRecord is created and forwarded

     * to all the registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   msg     The string message (or a key in the message catalog)

     * @param   param1  parameter to the message

     */

    public void log(Level level, String msg, Object param1) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        Object params[] = { param1 };

        lr.setParameters(params);

        doLog(lr);

    }

    /**

     * Log a message, with an array of object arguments.

     * <p>

     * If the logger is currently enabled for the given message

     * level then a corresponding LogRecord is created and forwarded

     * to all the registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   msg     The string message (or a key in the message catalog)

     * @param   params  array of parameters to the message

     */

    public void log(Level level, String msg, Object params[]) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setParameters(params);

        doLog(lr);

    }

    /**

     * Log a message, with associated Throwable information.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the given arguments are stored in a LogRecord

     * which is forwarded to all registered output handlers.

     * <p>

     * Note that the thrown argument is stored in the LogRecord thrown

     * property, rather than the LogRecord parameters property.  Thus it is

     * processed specially by output Formatters and is not treated

     * as a formatting parameter to the LogRecord message property.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   msg     The string message (or a key in the message catalog)

     * @param   thrown  Throwable associated with log message.

     */

    public void log(Level level, String msg, Throwable thrown) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setThrown(thrown);

        doLog(lr);

    }

    /**

     * Log a lazily constructed message, with associated Throwable information.

     * <p>

     * If the logger is currently enabled for the given message level then the

     * message is constructed by invoking the provided supplier function. The

     * message and the given {@link Throwable} are then stored in a {@link

     * LogRecord} which is forwarded to all registered output handlers.

     * <p>

     * Note that the thrown argument is stored in the LogRecord thrown

     * property, rather than the LogRecord parameters property.  Thus it is

     * processed specially by output Formatters and is not treated

     * as a formatting parameter to the LogRecord message property.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   thrown  Throwable associated with log message.

     * @param   msgSupplier   A function, which when called, produces the

     *                        desired log message

     * @since   1.8

     */

    public void log(Level level, Throwable thrown, Supplier<String> msgSupplier) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msgSupplier.get());

        lr.setThrown(thrown);

        doLog(lr);

    }

    //================================================================

    // Start of convenience methods WITH className and methodName

    //================================================================

    /**

     * Log a message, specifying source class and method,

     * with no arguments.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the given message is forwarded to all the

     * registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   sourceClass    name of class that issued the logging request

     * @param   sourceMethod   name of method that issued the logging request

     * @param   msg     The string message (or a key in the message catalog)

     */

    public void logp(Level level, String sourceClass, String sourceMethod, String msg) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setSourceClassName(sourceClass);

        lr.setSourceMethodName(sourceMethod);

        doLog(lr);

    }

    /**

     * Log a lazily constructed message, specifying source class and method,

     * with no arguments.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the message is constructed by invoking the provided

     * supplier function and forwarded to all the registered output

     * Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   sourceClass    name of class that issued the logging request

     * @param   sourceMethod   name of method that issued the logging request

     * @param   msgSupplier   A function, which when called, produces the

     *                        desired log message

     * @since   1.8

     */

    public void logp(Level level, String sourceClass, String sourceMethod,

                     Supplier<String> msgSupplier) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msgSupplier.get());

        lr.setSourceClassName(sourceClass);

        lr.setSourceMethodName(sourceMethod);

        doLog(lr);

    }

    /**

     * Log a message, specifying source class and method,

     * with a single object parameter to the log message.

     * <p>

     * If the logger is currently enabled for the given message

     * level then a corresponding LogRecord is created and forwarded

     * to all the registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   sourceClass    name of class that issued the logging request

     * @param   sourceMethod   name of method that issued the logging request

     * @param   msg      The string message (or a key in the message catalog)

     * @param   param1    Parameter to the log message.

     */

    public void logp(Level level, String sourceClass, String sourceMethod,

                                                String msg, Object param1) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setSourceClassName(sourceClass);

        lr.setSourceMethodName(sourceMethod);

        Object params[] = { param1 };

        lr.setParameters(params);

        doLog(lr);

    }

    /**

     * Log a message, specifying source class and method,

     * with an array of object arguments.

     * <p>

     * If the logger is currently enabled for the given message

     * level then a corresponding LogRecord is created and forwarded

     * to all the registered output Handler objects.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   sourceClass    name of class that issued the logging request

     * @param   sourceMethod   name of method that issued the logging request

     * @param   msg     The string message (or a key in the message catalog)

     * @param   params  Array of parameters to the message

     */

    public void logp(Level level, String sourceClass, String sourceMethod,

                                                String msg, Object params[]) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setSourceClassName(sourceClass);

        lr.setSourceMethodName(sourceMethod);

        lr.setParameters(params);

        doLog(lr);

    }

    /**

     * Log a message, specifying source class and method,

     * with associated Throwable information.

     * <p>

     * If the logger is currently enabled for the given message

     * level then the given arguments are stored in a LogRecord

     * which is forwarded to all registered output handlers.

     * <p>

     * Note that the thrown argument is stored in the LogRecord thrown

     * property, rather than the LogRecord parameters property.  Thus it is

     * processed specially by output Formatters and is not treated

     * as a formatting parameter to the LogRecord message property.

     *

     * @param   level   One of the message level identifiers, e.g., SEVERE

     * @param   sourceClass    name of class that issued the logging request

     * @param   sourceMethod   name of method that issued the logging request

     * @param   msg     The string message (or a key in the message catalog)

     * @param   thrown  Throwable associated with log message.

     */

    public void logp(Level level, String sourceClass, String sourceMethod,

                     String msg, Throwable thrown) {

        if (!isLoggable(level)) {

            return;

        }

        LogRecord lr = new LogRecord(level, msg);

        lr.setSourceClassName(sourceClass);

        lr.setSourceMethodName(sourceMethod);

        lr.setThrown(thrown);

        doLog(lr);

    }

    /**

     * Log a lazily constructed message, specifying source class and method,

     * with associated Throwable information.

     * <p>

     * If the logger is currently enabled for the given message level then the

     * message is constructed by invoking the provided supplier function. The