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  /**
24   * The MBean interface for monitoring and managing a {@code LoggerContext}.
25   */
26  public interface LoggerContextAdminMBean {
27      /**
28       * ObjectName pattern ({@value}) for LoggerContextAdmin MBeans.
29       * This pattern contains a variable, which is the name of the logger context.
30       * <p>
31       * You can find all registered LoggerContextAdmin MBeans like this:
32       * </p>
33       * <pre>
34       * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
35       * String pattern = String.format(LoggerContextAdminMBean.PATTERN, &quot;*&quot;);
36       * Set&lt;ObjectName&gt; loggerContextNames = mbs.queryNames(new ObjectName(pattern), null);
37       * </pre>
38       * <p>
39       * Some characters are not allowed in ObjectNames. The logger context name
40       * may be quoted. When LoggerContextAdmin MBeans are
41       * registered, their ObjectNames are created using this pattern as follows:
42       * </p>
43       * <pre>
44       * String ctxName = Server.escape(loggerContext.getName());
45       * String name = String.format(PATTERN, ctxName);
46       * ObjectName objectName = new ObjectName(name);
47       * </pre>
48       * @see Server#escape(String)
49       */
50      String PATTERN = "org.apache.logging.log4j2:type=LoggerContext,ctx=%s";
51  
52      /**
53       * Notification that the {@code Configuration} of the instrumented
54       * {@code LoggerContext} has been reconfigured. Notifications of this type
55       * ({@value}) do not carry a message or user data.
56       */
57      String NOTIF_TYPE_RECONFIGURED = "com.apache.logging.log4j.core.jmx.config.reconfigured";
58  
59      /**
60       * Returns the status of the instrumented {@code LoggerContext}.
61       * 
62       * @return the LoggerContext status.
63       */
64      String getStatus();
65  
66      /**
67       * Returns the name of the instrumented {@code LoggerContext}.
68       * 
69       * @return the name of the instrumented {@code LoggerContext}.
70       */
71      String getName();
72  
73      /**
74       * Returns the configuration location URI as a String.
75       * 
76       * @return the configuration location
77       */
78      String getConfigLocationURI();
79  
80      /**
81       * Sets the configuration location to the specified URI. This will cause the
82       * instrumented {@code LoggerContext} to reconfigure.
83       * 
84       * @param configLocation location of the configuration file in
85       *            {@link java.net.URI} format.
86       * @throws URISyntaxException if the format of the specified
87       *             configLocationURI is incorrect
88       * @throws IOException if an error occurred reading the specified location
89       */
90      void setConfigLocationURI(String configLocation) throws URISyntaxException,
91              IOException;
92  
93      /**
94       * Returns the configuration text, which may be the contents of the
95       * configuration file or the text that was last set with a call to
96       * {@code setConfigText}. If reading a file, this method assumes the file's
97       * character encoding is UTF-8.
98       * 
99       * @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 }