    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    }