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 */
017package org.apache.logging.log4j.core.jmx;
018
019/**
020 * The MBean interface for monitoring and managing a {@code LoggerConfig}.
021 */
022public interface LoggerConfigAdminMBean {
023    /**
024     * ObjectName pattern ({@value}) for LoggerConfigAdmin MBeans.
025     * This pattern contains two variables, where the first is the name of the
026     * context, the second is the name of the instrumented logger config.
027     * <p>
028     * You can find all registered LoggerConfigAdmin MBeans like this:
029     * </p>
030     * <pre>
031     * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
032     * String pattern = String.format(LoggerConfigAdminMBean.PATTERN, &quot;*&quot;, &quot;*&quot;);
033     * Set&lt;ObjectName&gt; loggerConfigNames = mbs.queryNames(new ObjectName(pattern), null);
034     * </pre>
035     * <p>
036     * Some characters are not allowed in ObjectNames. The logger context name
037     * and logger config name may be quoted. When LoggerConfigAdmin MBeans are
038     * registered, their ObjectNames are created using this pattern as follows:
039     * </p>
040     * <pre>
041     * String ctxName = Server.escape(loggerContext.getName());
042     * String loggerConfigName = Server.escape(loggerConfig.getName());
043     * String name = String.format(PATTERN, ctxName, loggerConfigName);
044     * ObjectName objectName = new ObjectName(name);
045     * </pre>
046     * @see Server#escape(String)
047     */
048    String PATTERN = Server.DOMAIN + ":type=%s,component=Loggers,name=%s";
049
050    /**
051     * Returns the name of the instrumented {@code LoggerConfig}.
052     *
053     * @return the name of the LoggerConfig
054     */
055    String getName();
056
057    /**
058     * Returns the {@code LoggerConfig} level as a String.
059     *
060     * @return the {@code LoggerConfig} level.
061     */
062    String getLevel();
063
064    /**
065     * Sets the {@code LoggerConfig} level to the specified value.
066     *
067     * @param level the new {@code LoggerConfig} level.
068     * @throws IllegalArgumentException if the specified level is not one of
069     *             "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE",
070     *             "ALL"
071     */
072    void setLevel(String level);
073
074    /**
075     * Returns whether the instrumented {@code LoggerConfig} is additive.
076     *
077     * @return {@code true} if the LoggerConfig is additive, {@code false}
078     *         otherwise
079     */
080    boolean isAdditive();
081
082    /**
083     * Sets whether the instrumented {@code LoggerConfig} should be additive.
084     *
085     * @param additive {@code true} if the instrumented LoggerConfig should be
086     *            additive, {@code false} otherwise
087     */
088    void setAdditive(boolean additive);
089
090    /**
091     * Returns whether the instrumented {@code LoggerConfig} is configured to
092     * include location.
093     *
094     * @return whether location should be passed downstream
095     */
096    boolean isIncludeLocation();
097
098    /**
099     * Returns a string description of all filters configured for the
100     * instrumented {@code LoggerConfig}.
101     *
102     * @return a string description of all configured filters for this
103     *         LoggerConfig
104     */
105    String getFilter();
106
107    /**
108     * Returns a String array with the appender refs configured for the
109     * instrumented {@code LoggerConfig}.
110     *
111     * @return the appender refs for the instrumented {@code LoggerConfig}.
112     */
113    String[] getAppenderRefs();
114
115}