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