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 }