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 */ 017package org.apache.logging.log4j.core.jmx; 018 019import java.io.IOException; 020import java.net.URISyntaxException; 021import java.util.Map; 022 023import javax.management.ObjectName; 024 025/** 026 * The MBean interface for monitoring and managing a {@code LoggerContext}. 027 */ 028public 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}