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    import javax.management.ObjectName;
024    
025    /**
026     * The MBean interface for monitoring and managing a {@code LoggerContext}.
027     */
028    public 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    }