001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017 package org.apache.logging.log4j.core.jmx;
018
019 import java.io.IOException;
020 import java.net.URISyntaxException;
021 import java.util.Map;
022
023 import javax.management.ObjectName;
024
025 /**
026 * The MBean interface for monitoring and managing a {@code LoggerContext}.
027 */
028 public interface LoggerContextAdminMBean {
029 /**
030 * ObjectName pattern ({@value} ) for LoggerContextAdmin MBeans. This
031 * pattern contains a variable, which is the name of the logger context.
032 * <p>
033 * You can find all registered LoggerContextAdmin MBeans like this:
034 * </p>
035 *
036 * <pre>
037 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
038 * String pattern = String.format(LoggerContextAdminMBean.PATTERN, "*");
039 * Set<ObjectName> loggerContextNames = mbs.queryNames(new ObjectName(pattern), null);
040 * </pre>
041 * <p>
042 * Some characters are not allowed in ObjectNames. The logger context name
043 * may be quoted. When LoggerContextAdmin MBeans are registered, their
044 * ObjectNames are created using this pattern as follows:
045 * </p>
046 *
047 * <pre>
048 * String ctxName = Server.escape(loggerContext.getName());
049 * String name = String.format(PATTERN, ctxName);
050 * ObjectName objectName = new ObjectName(name);
051 * </pre>
052 *
053 * @see Server#escape(String)
054 */
055 String PATTERN = Server.DOMAIN + ":type=%s";
056
057 /**
058 * Notification that the {@code Configuration} of the instrumented
059 * {@code LoggerContext} has been reconfigured. Notifications of this type
060 * ({@value} ) do not carry a message or user data.
061 */
062 String NOTIF_TYPE_RECONFIGURED = "com.apache.logging.log4j.core.jmx.config.reconfigured";
063
064 /**
065 * Returns the {@code ObjectName} that this MBean is registered with in the
066 * MBean server.
067 */
068 ObjectName getObjectName();
069
070 /**
071 * Returns the status of the instrumented {@code LoggerContext}.
072 *
073 * @return the LoggerContext status.
074 */
075 String getStatus();
076
077 /**
078 * Returns the name of the instrumented {@code LoggerContext}.
079 *
080 * @return the name of the instrumented {@code LoggerContext}.
081 */
082 String getName();
083
084 /**
085 * Returns the configuration location URI as a String.
086 *
087 * @return the configuration location
088 */
089 String getConfigLocationUri();
090
091 /**
092 * Sets the configuration location to the specified URI. This will cause the
093 * instrumented {@code LoggerContext} to reconfigure.
094 *
095 * @param configLocation location of the configuration file in
096 * {@link java.net.URI} format.
097 * @throws URISyntaxException if the format of the specified
098 * configLocationURI is incorrect
099 * @throws IOException if an error occurred reading the specified location
100 */
101 void setConfigLocationUri(String configLocation) throws URISyntaxException, IOException;
102
103 /**
104 * Returns the configuration text, which may be the contents of the
105 * configuration file or the text that was last set with a call to
106 * {@code setConfigText}. If reading a file, this method assumes the file's
107 * character encoding is UTF-8.
108 *
109 * @return the configuration text
110 * @throws IOException if a problem occurred reading the contents of the
111 * config file.
112 */
113 String getConfigText() throws IOException;
114
115 /**
116 * Returns the configuration text, which may be the contents of the
117 * configuration file or the text that was last set with a call to
118 * {@code setConfigText}.
119 *
120 * @param charsetName the encoding to use to convert the file's bytes into
121 * the resulting string.
122 * @return the configuration text
123 * @throws IOException if a problem occurred reading the contents of the
124 * config file.
125 */
126 String getConfigText(String charsetName) throws IOException;
127
128 /**
129 * Sets the configuration text. This does not replace the contents of the
130 * configuration file, but <em>does</em> cause the instrumented
131 * {@code LoggerContext} to be reconfigured with the specified text.
132 *
133 * @param configText the configuration text in XML or JSON format
134 * @param charsetName name of the {@code Charset} used to convert the
135 * specified configText to bytes
136 * @throws IllegalArgumentException if a problem occurs configuring from the
137 * specified text
138 */
139 void setConfigText(String configText, String charsetName);
140
141 /**
142 * Returns the name of the Configuration of the instrumented LoggerContext.
143 *
144 * @return the Configuration name
145 */
146 String getConfigName();
147
148 /**
149 * Returns the class name of the {@code Configuration} of the instrumented
150 * LoggerContext.
151 *
152 * @return the class name of the {@code Configuration}.
153 */
154 String getConfigClassName();
155
156 /**
157 * Returns a string description of all Filters configured in the
158 * {@code Configuration} of the instrumented LoggerContext.
159 *
160 * @return a string description of all Filters configured
161 */
162 String getConfigFilter();
163
164 /**
165 * Returns the class name of the object that is monitoring the configuration
166 * file for modifications.
167 *
168 * @return the class name of the object that is monitoring the configuration
169 * file for modifications
170 */
171 String getConfigMonitorClassName();
172
173 /**
174 * Returns a map with configured properties.
175 *
176 * @return a map with configured properties.
177 */
178 Map<String, String> getConfigProperties();
179
180 }