src/share/classes/java/lang/management/PlatformLoggingMXBean.java
Print this page
@@ -21,40 +21,118 @@
* 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;
+package java.lang.management;
-import java.lang.management.PlatformManagedObject;
-
/**
- * The {@linkplain PlatformManagedObject platform managed object} for the
- * logging facility. This interface simply unifies {@link LoggingMXBean}
- * {@link PlatformManagedObject};
- * and it does not specify any new operations.
+ * The management interface for the {@linkplain java.util.logging logging} facility.
*
- * <p>The {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
- * ManagementFactory.getPlatformMXBeans} method can be used to obtain
+ * <p>There is a single global instance of the <tt>PlatformLoggingMXBean</tt>.
+ * The {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
+ * ManagementFactory.getPlatformMXBean} method can be used to obtain
* the {@code PlatformLoggingMXBean} object as follows:
* <pre>
- * ManagementFactory.getPlatformMXBeans(PlatformLoggingMXBean.class);
+ * PlatformLoggingMXBean logging = ManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class);
* </pre>
- * or from the {@linkplain java.lang.management.ManagementFactory#getPlatformMBeanServer
- * platform <tt>MBeanServer</tt>}.
- *
+ * The {@code PlatformLoggingMXBean} object is also registered with the
+ * platform {@linkplain java.lang.management.ManagementFactory#getPlatformMBeanServer
+ * MBeanServer}.
* The {@link javax.management.ObjectName ObjectName} for uniquely
- * identifying the <tt>LoggingMXBean</tt> within an MBeanServer is:
+ * identifying the {@code PlatformLoggingMXBean} within an MBeanServer is:
+ * <pre>
+ * {@link java.util.logging.LogManager#LOGGING_MXBEAN_NAME java.util.logging:type=Logging}
+ * </pre>
+ *
+ * <p>The instance registered in the platform <tt>MBeanServer</tt> with
+ * this {@code ObjectName} implements all attributes defined by
+ * {@link java.util.logging.LoggingMXBean}.
+ *
+ * @since 1.7
+ */
+public interface PlatformLoggingMXBean extends PlatformManagedObject {
+
+ /**
+ * Returns the list of currently registered
+ * {@linkplain java.util.logging.Logger loggers}. This method
+ * calls {@link java.util.logging.LogManager#getLoggerNames} and returns a list
+ * of the logger names.
+ *
+ * @return A list of {@code String} each of which is a
+ * currently registered {@code Logger} name.
+ */
+ java.util.List<String> getLoggerNames();
+
+ /**
+ * Gets the name of the log {@linkplain java.util.logging.Logger#getLevel
+ * level} associated with the specified logger.
+ * If the specified logger does not exist, {@code null}
+ * is returned.
+ * This method first finds the logger of the given name and
+ * then returns the name of the log level by calling:
* <blockquote>
- * <tt>java.util.logging:type=Logging</tt>
+ * {@link java.util.logging.Logger#getLevel
+ * Logger.getLevel()}.{@link java.util.logging.Level#getName getName()};
* </blockquote>
*
- * The {@link PlatformManagedObject#getObjectName} method
- * can be used to obtain its {@code ObjectName}.
+ * <p>
+ * If the {@code Level} of the specified logger is {@code null},
+ * which means that this logger's effective level is inherited
+ * from its parent, an empty string will be returned.
*
- * @see java.lang.management.PlatformManagedObject
+ * @param loggerName The name of the {@code Logger} to be retrieved.
*
- * @author Mandy Chung
- * @since 1.7
+ * @return The name of the log level of the specified logger; or
+ * an empty string if the log level of the specified logger
+ * is {@code null}. If the specified logger does not
+ * exist, {@code null} is returned.
+ *
+ * @see java.util.logging.Logger#getLevel
*/
-public interface PlatformLoggingMXBean extends LoggingMXBean, PlatformManagedObject {
+ String getLoggerLevel( String loggerName );
+
+ /**
+ * Sets the specified logger to the specified new
+ * {@linkplain java.util.logging.Logger#setLevel level}.
+ * If the {@code levelName} is not {@code null}, the level
+ * of the specified logger is set to the parsed
+ * {@link java.util.logging.Level Level}
+ * matching the {@code levelName}.
+ * If the {@code levelName} is {@code null}, the level
+ * of the specified logger is set to {@code null} and
+ * the effective level of the logger is inherited from
+ * its nearest ancestor with a specific (non-null) level value.
+ *
+ * @param loggerName The name of the {@code Logger} to be set.
+ * Must be non-null.
+ * @param levelName The name of the level to set on the specified logger,
+ * or {@code null} if setting the level to inherit
+ * from its nearest ancestor.
+ *
+ * @throws IllegalArgumentException if the specified logger
+ * does not exist, or {@code levelName} is not a valid level name.
+ *
+ * @throws SecurityException if a security manager exists and if
+ * the caller does not have LoggingPermission("control").
+ *
+ * @see java.util.logging.Logger#setLevel
+ */
+ void setLoggerLevel( String loggerName, String levelName );
+
+ /**
+ * Returns the name of the
+ * {@linkplain java.util.logging.Logger#getParent parent}
+ * for the specified logger.
+ * If the specified logger does not exist, {@code null} is returned.
+ * If the specified logger is the root {@code Logger} in the namespace,
+ * the result will be an empty string.
+ *
+ * @param loggerName The name of a {@code Logger}.
+ *
+ * @return the name of the nearest existing parent logger;
+ * an empty string if the specified logger is the root logger.
+ * If the specified logger does not exist, {@code null}
+ * is returned.
+ */
+ String getParentLoggerName(String loggerName);
}