1 /*
   2  * Copyright (c) 2009, 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 package java.lang.management;
  27 
  28 /**
  29  * The management interface for the {@linkplain java.util.logging logging} facility. 
  30  *
  31  * <p>There is a single global instance of the <tt>PlatformLoggingMXBean</tt>.
  32  * The {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
  33  * ManagementFactory.getPlatformMXBean} method can be used to obtain
  34  * the {@code PlatformLoggingMXBean} object as follows:
  35  * <pre>
  36  *     PlatformLoggingMXBean logging = ManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class);
  37  * </pre>
  38  * The {@code PlatformLoggingMXBean} object is also registered with the
  39  * platform {@linkplain java.lang.management.ManagementFactory#getPlatformMBeanServer
  40  * MBeanServer}.
  41  * The {@link javax.management.ObjectName ObjectName} for uniquely
  42  * identifying the {@code PlatformLoggingMXBean} within an MBeanServer is:
  43  * <pre>
  44  *      {@link java.util.logging.LogManager#LOGGING_MXBEAN_NAME java.util.logging:type=Logging}
  45  * </pre>
  46  *
  47  * <p>The instance registered in the platform <tt>MBeanServer</tt> with
  48  * this {@code ObjectName} implements all attributes defined by
  49  * {@link java.util.logging.LoggingMXBean}.
  50  *
  51  * @since   1.7
  52  */
  53 public interface PlatformLoggingMXBean extends PlatformManagedObject {
  54 
  55     /**
  56      * Returns the list of the currently registered 
  57      * {@linkplain java.util.logging.Logger logger} names. This method
  58      * calls {@link java.util.logging.LogManager#getLoggerNames} and 
  59      * returns a list of the logger names.
  60      *
  61      * @return A list of {@code String} each of which is a
  62      *         currently registered {@code Logger} name.
  63      */
  64     java.util.List<String> getLoggerNames();
  65 
  66     /**
  67      * Gets the name of the log {@linkplain java.util.logging.Logger#getLevel
  68      * level} associated with the specified logger.
  69      * If the specified logger does not exist, {@code null}
  70      * is returned.
  71      * This method first finds the logger of the given name and
  72      * then returns the name of the log level by calling:
  73      * <blockquote>
  74      *   {@link java.util.logging.Logger#getLevel
  75      *    Logger.getLevel()}.{@link java.util.logging.Level#getName getName()};
  76      * </blockquote>
  77      *
  78      * <p>
  79      * If the {@code Level} of the specified logger is {@code null},
  80      * which means that this logger's effective level is inherited
  81      * from its parent, an empty string will be returned.
  82      *
  83      * @param loggerName The name of the {@code Logger} to be retrieved.
  84      *
  85      * @return The name of the log level of the specified logger; or
  86      *         an empty string if the log level of the specified logger
  87      *         is {@code null}.  If the specified logger does not
  88      *         exist, {@code null} is returned.
  89      *
  90      * @see java.util.logging.Logger#getLevel
  91      */
  92     String getLoggerLevel(String loggerName);
  93 
  94     /**
  95      * Sets the specified logger to the specified new 
  96      * {@linkplain java.util.logging.Logger#setLevel level}.
  97      * If the {@code levelName} is not {@code null}, the level
  98      * of the specified logger is set to the parsed 
  99      * {@link java.util.logging.Level Level}
 100      * matching the {@code levelName}.
 101      * If the {@code levelName} is {@code null}, the level
 102      * of the specified logger is set to {@code null} and
 103      * the effective level of the logger is inherited from
 104      * its nearest ancestor with a specific (non-null) level value.
 105      *
 106      * @param loggerName The name of the {@code Logger} to be set.
 107      *                   Must be non-null.
 108      * @param levelName The name of the level to set on the specified logger,
 109      *                 or  {@code null} if setting the level to inherit
 110      *                 from its nearest ancestor.
 111      *
 112      * @throws IllegalArgumentException if the specified logger
 113      * does not exist, or {@code levelName} is not a valid level name.
 114      *
 115      * @throws SecurityException if a security manager exists and if
 116      * the caller does not have LoggingPermission("control").
 117      *
 118      * @see java.util.logging.Logger#setLevel
 119      */
 120     void setLoggerLevel(String loggerName, String levelName);
 121 
 122     /**
 123      * Returns the name of the 
 124      * {@linkplain java.util.logging.Logger#getParent parent}
 125      * for the specified logger.
 126      * If the specified logger does not exist, {@code null} is returned.
 127      * If the specified logger is the root {@code Logger} in the namespace,
 128      * the result will be an empty string.
 129      *
 130      * @param loggerName The name of a {@code Logger}.
 131      *
 132      * @return the name of the nearest existing parent logger;
 133      *         an empty string if the specified logger is the root logger.
 134      *         If the specified logger does not exist, {@code null}
 135      *         is returned.
 136      */
 137     String getParentLoggerName(String loggerName);
 138 }