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