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