1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache license, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the license for the specific language governing permissions and 15 * limitations under the license. 16 */ 17 package org.apache.logging.log4j.core.jmx; 18 19 import java.io.IOException; 20 import java.net.URISyntaxException; 21 import java.util.Map; 22 23 import javax.management.ObjectName; 24 25 /** 26 * The MBean interface for monitoring and managing a {@code LoggerContext}. 27 */ 28 public interface LoggerContextAdminMBean { 29 /** 30 * ObjectName pattern ({@value} ) for LoggerContextAdmin MBeans. This 31 * pattern contains a variable, which is the name of the logger context. 32 * <p> 33 * You can find all registered LoggerContextAdmin MBeans like this: 34 * </p> 35 * 36 * <pre> 37 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 38 * String pattern = String.format(LoggerContextAdminMBean.PATTERN, "*"); 39 * Set<ObjectName> loggerContextNames = mbs.queryNames(new ObjectName(pattern), null); 40 * </pre> 41 * <p> 42 * Some characters are not allowed in ObjectNames. The logger context name 43 * may be quoted. When LoggerContextAdmin MBeans are registered, their 44 * ObjectNames are created using this pattern as follows: 45 * </p> 46 * 47 * <pre> 48 * String ctxName = Server.escape(loggerContext.getName()); 49 * String name = String.format(PATTERN, ctxName); 50 * ObjectName objectName = new ObjectName(name); 51 * </pre> 52 * 53 * @see Server#escape(String) 54 */ 55 String PATTERN = Server.DOMAIN + ":type=%s"; 56 57 /** 58 * Notification that the {@code Configuration} of the instrumented 59 * {@code LoggerContext} has been reconfigured. Notifications of this type 60 * ({@value} ) do not carry a message or user data. 61 */ 62 String NOTIF_TYPE_RECONFIGURED = "com.apache.logging.log4j.core.jmx.config.reconfigured"; 63 64 /** 65 * Returns the {@code ObjectName} that this MBean is registered with in the 66 * MBean server. 67 */ 68 ObjectName getObjectName(); 69 70 /** 71 * Returns the status of the instrumented {@code LoggerContext}. 72 * 73 * @return the LoggerContext status. 74 */ 75 String getStatus(); 76 77 /** 78 * Returns the name of the instrumented {@code LoggerContext}. 79 * 80 * @return the name of the instrumented {@code LoggerContext}. 81 */ 82 String getName(); 83 84 /** 85 * Returns the configuration location URI as a String. 86 * 87 * @return the configuration location 88 */ 89 String getConfigLocationUri(); 90 91 /** 92 * Sets the configuration location to the specified URI. This will cause the 93 * instrumented {@code LoggerContext} to reconfigure. 94 * 95 * @param configLocation location of the configuration file in 96 * {@link java.net.URI} format. 97 * @throws URISyntaxException if the format of the specified 98 * configLocationURI is incorrect 99 * @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 }