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 /** 024 * The MBean interface for monitoring and managing a {@code LoggerContext}. 025 */ 026 public interface LoggerContextAdminMBean { 027 /** 028 * ObjectName pattern ({@value}) for LoggerContextAdmin MBeans. 029 * This pattern contains a variable, which is the name of the logger context. 030 * <p> 031 * You can find all registered LoggerContextAdmin MBeans like this: 032 * </p> 033 * <pre> 034 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 035 * String pattern = String.format(LoggerContextAdminMBean.PATTERN, "*"); 036 * Set<ObjectName> loggerContextNames = mbs.queryNames(new ObjectName(pattern), null); 037 * </pre> 038 * <p> 039 * Some characters are not allowed in ObjectNames. The logger context name 040 * may be quoted. When LoggerContextAdmin MBeans are 041 * registered, their ObjectNames are created using this pattern as follows: 042 * </p> 043 * <pre> 044 * String ctxName = Server.escape(loggerContext.getName()); 045 * String name = String.format(PATTERN, ctxName); 046 * ObjectName objectName = new ObjectName(name); 047 * </pre> 048 * @see Server#escape(String) 049 */ 050 String PATTERN = "org.apache.logging.log4j2:type=LoggerContext,ctx=%s"; 051 052 /** 053 * Notification that the {@code Configuration} of the instrumented 054 * {@code LoggerContext} has been reconfigured. Notifications of this type 055 * ({@value}) do not carry a message or user data. 056 */ 057 String NOTIF_TYPE_RECONFIGURED = "com.apache.logging.log4j.core.jmx.config.reconfigured"; 058 059 /** 060 * Returns the status of the instrumented {@code LoggerContext}. 061 * 062 * @return the LoggerContext status. 063 */ 064 String getStatus(); 065 066 /** 067 * Returns the name of the instrumented {@code LoggerContext}. 068 * 069 * @return the name of the instrumented {@code LoggerContext}. 070 */ 071 String getName(); 072 073 /** 074 * Returns the configuration location URI as a String. 075 * 076 * @return the configuration location 077 */ 078 String getConfigLocationURI(); 079 080 /** 081 * Sets the configuration location to the specified URI. This will cause the 082 * instrumented {@code LoggerContext} to reconfigure. 083 * 084 * @param configLocation location of the configuration file in 085 * {@link java.net.URI} format. 086 * @throws URISyntaxException if the format of the specified 087 * configLocationURI is incorrect 088 * @throws IOException if an error occurred reading the specified location 089 */ 090 void setConfigLocationURI(String configLocation) throws URISyntaxException, 091 IOException; 092 093 /** 094 * Returns the configuration text, which may be the contents of the 095 * configuration file or the text that was last set with a call to 096 * {@code setConfigText}. If reading a file, this method assumes the file's 097 * character encoding is UTF-8. 098 * 099 * @return the configuration text 100 * @throws IOException if a problem occurred reading the contents of the 101 * config file. 102 */ 103 String getConfigText() throws IOException; 104 105 /** 106 * Returns the configuration text, which may be the contents of the 107 * configuration file or the text that was last set with a call to 108 * {@code setConfigText}. 109 * 110 * @param charsetName the encoding to use to convert the file's bytes into 111 * the resulting string. 112 * @return the configuration text 113 * @throws IOException if a problem occurred reading the contents of the 114 * config file. 115 */ 116 String getConfigText(String charsetName) throws IOException; 117 118 /** 119 * Sets the configuration text. This does not replace the contents of the 120 * configuration file, but <em>does</em> cause the instrumented 121 * {@code LoggerContext} to be reconfigured with the specified text. 122 * 123 * @param configText the configuration text in XML or JSON format 124 * @param charsetName name of the {@code Charset} used to convert the 125 * specified configText to bytes 126 * @throws IllegalArgumentException if a problem occurs configuring from the 127 * specified text 128 */ 129 void setConfigText(String configText, String charsetName); 130 131 /** 132 * Returns the name of the Configuration of the instrumented LoggerContext. 133 * 134 * @return the Configuration name 135 */ 136 String getConfigName(); 137 138 /** 139 * Returns the class name of the {@code Configuration} of the instrumented 140 * LoggerContext. 141 * 142 * @return the class name of the {@code Configuration}. 143 */ 144 String getConfigClassName(); 145 146 /** 147 * Returns a string description of all Filters configured in the 148 * {@code Configuration} of the instrumented LoggerContext. 149 * 150 * @return a string description of all Filters configured 151 */ 152 String getConfigFilter(); 153 154 /** 155 * Returns the class name of the object that is monitoring the configuration 156 * file for modifications. 157 * 158 * @return the class name of the object that is monitoring the configuration 159 * file for modifications 160 */ 161 String getConfigMonitorClassName(); 162 163 /** 164 * Returns a map with configured properties. 165 * 166 * @return a map with configured properties. 167 */ 168 Map<String, String> getConfigProperties(); 169 170 }