util/logging/Logger.java

47  * A Logger object is used to log messages for a specific
49  * using a hierarchical dot-separated namespace.  Logger names
53  * "anonymous" Loggers that are not stored in the Logger namespace.
55  * Logger objects may be obtained by calls on one of the getLogger
56  * factory methods.  These will either create a new Logger or
57  * return a suitable existing Logger. It is important to note that
58  * the Logger returned by one of the {@code getLogger} factory methods
60  * Logger is not kept.
66  * Each Logger keeps track of a "parent" Logger, which is its
67  * nearest existing ancestor in the Logger namespace.
69  * Each Logger has a "Level" associated with it.  This reflects
70  * a minimum Level that this logger cares about.  If a Logger's
78  * by calls on the Logger.setLevel method.  If a logger's level is
83  * On each logging call the Logger initially performs a cheap
88  * After passing this initial (cheap) test, the Logger will allocate
95  * Each Logger may have a {@code ResourceBundle} associated with it.
101  * If a Logger does not have its own {@code ResourceBundle} or resource bundle
207  * All methods on Logger are multi-thread safe.
211  * the namespace.  Therefore, any subclasses of Logger (unless they
213  * take care to obtain a Logger instance from the LogManager class and
222 public class Logger {
362         ConfigurationData merge(Logger systemPeer) {
459     private volatile Logger parent;    // our nearest parent.
472      * Return global logger object with the name Logger.GLOBAL_LOGGER_NAME.
477     public static final Logger getGlobal() {
479         // and Logger static initializers causing deadlocks, the global
483         // If an application calls Logger.getGlobal() before any logger
486         // Logger.global.manager will be null.
515      * The "global" Logger object is provided as a convenience to developers
518      * in products) should create and use their own Logger objects,
520      * suitable per-Logger granularity. Developers also need to keep a
521      * strong reference to their Logger objects to prevent them from
525      * The field must be initialized by the Logger class initialization
529      * {@code Logger.getGlobal()}.
531      * {@code Logger.getGlobal()} is not available use the call
532      * {@code Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)}
533      * or {@code Logger.getLogger("global")}.
536     public static final Logger global = new Logger(GLOBAL_LOGGER_NAME);
555     protected Logger(String name, String resourceBundleName) {
559     Logger(String name, String resourceBundleName, Module caller,
572     final void mergeWithSystemLogger(Logger system) {
600     // This constructor is used only to create the global Logger.
602     // and Logger static initializers causing deadlocks.
603     private Logger(String name) {
619                 // Complete initialization of the global Logger.
627     // (see 7054233), we need to determine if Logger.getLogger is to add
647     private static Logger demandLogger(String name, String resourceBundleName, Class<?> caller) {
655         // ends up calling new Logger(name, resourceBundleName, caller)
670      * created Logger. It is important to understand that a previously
671      * created Logger with the given name may be garbage collected at any
672      * time if there is no strong reference to the Logger. In particular,
674      * {@code getLogger("MyLogger").log(...)} may use different Logger
676      * Logger named "MyLogger" elsewhere in the program.
683      * @return a suitable Logger
688     // adding a new Logger object is handled by LogManager.addLogger().
690     public static Logger getLogger(String name) {
701         return Logger.getLogger(name, Reflection.getCallerClass());
714      * @return a suitable Logger for {@code callerClass}.
716     private static Logger getLogger(String name, Class<?> callerClass) {
732      * created Logger. It is important to understand that a previously
733      * created Logger with the given name may be garbage collected at any
734      * time if there is no strong reference to the Logger. In particular,
736      * {@code getLogger("MyLogger", ...).log(...)} may use different Logger
738      * Logger named "MyLogger" elsewhere in the program.
740      * If the named Logger already exists and does not yet have a
742      * name is used. If the named Logger already exists and has
754      * @return a suitable Logger
757      * @throws IllegalArgumentException if the Logger already exists and uses
765     // adding a new Logger object is handled by LogManager.addLogger().
767     public static Logger getLogger(String name, String resourceBundleName) {
768         return Logger.getLogger(name, resourceBundleName, Reflection.getCallerClass());
788      * @return a suitable Logger for {@code callerClass}.
790     private static Logger getLogger(String name, String resourceBundleName,
792         Logger result = demandLogger(name, resourceBundleName, callerClass);
797         // above found a previously created Logger.  This can happen, for
798         // example, if Logger.getLogger(name) is called and subsequently
799         // Logger.getLogger(name, resourceBundleName) is called.  In this case
810     static Logger getPlatformLogger(String name) {
816         Logger result = manager.demandSystemLogger(name, SYSTEM_LOGGER_RB_NAME, (Module)null);
821      * Create an anonymous Logger.  The newly created Logger is not
826      * Because the resulting Logger is anonymous it can be kept private
829      * the control state of the Logger.  For example an applet can do
830      * a setLevel or an addHandler on an anonymous Logger.
836      * {@link #setParent(java.util.logging.Logger) setParent} method
839      * @return a newly created private Logger
841     public static Logger getAnonymousLogger() {
846      * Create an anonymous Logger.  The newly created Logger is not
851      * Because the resulting Logger is anonymous it can be kept private
854      * the control state of the Logger.  For example an applet can do
855      * a setLevel or an addHandler on an anonymous Logger.
861      * {@link #setParent(java.util.logging.Logger) setParent} method
867      * @return a newly created private Logger
873     // adding a new anonymous Logger object is handled by doSetParent().
875     public static Logger getAnonymousLogger(String resourceBundleName) {
881         Logger result = new Logger(null, resourceBundleName,
884         Logger root = manager.getLogger("");
897      * Logger#getLogger(java.lang.String, java.lang.String) getLogger} factory
899      * <br>Note that if the result is {@code null}, then the Logger will use a resource
916      * <br>Note that if the result is {@code null}, then the Logger will use a resource
926      * Set a filter to control output on this Logger.
928      * After passing the initial "level" check, the Logger will
943      * Get the current filter for this Logger.
972         Logger logger = this;
2013      * Get the log Level that has been specified for this Logger.
2017      * @return  this Logger's level
2051      * Typically the root Logger is configured with a set of Handlers
2100      * to its parent Logger.  This means that any LogRecords will
2258             // this Logger already has a ResourceBundle
2338      * Return the parent for this Logger.
2341      * Thus if a Logger is called "a.b.c.d", and a Logger called "a.b"
2343      * getParent on the Logger "a.b.c.d" will return the Logger "a.b".
2345      * The result will be null if it is called on the root Logger
2348      * @return nearest existing parent Logger
2350     public Logger getParent() {
2360      * Set the parent for this Logger.  This method is used by
2361      * the LogManager to update a Logger when the namespace changes.
2369     public void setParent(Logger parent) {
2384     // Logger onto a parent logger.
2385     private void doSetParent(Logger newParent) {
2398                     Logger kid =  ref.get();
2430     // Remove the weak reference for the specified child Logger from the
2477                 Logger kid = ref.get();
2487     // resource bundle and resource bundle name for this Logger.
2508         Logger target = this.parent;