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, &quot;*&quot;);
039     * Set&lt;ObjectName&gt; 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}