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    /**
020     * The MBean interface for monitoring and managing an {@code AsyncAppender}.
021     */
022    public interface AsyncAppenderAdminMBean {
023        /**
024         * ObjectName pattern ({@value} ) for AsyncAppenderAdmin MBeans. This
025         * pattern contains two variables, where the first is the name of the
026         * context, the second is the name of the instrumented appender.
027         * <p>
028         * You can find all registered AsyncAppenderAdmin MBeans like this:
029         * </p>
030         * 
031         * <pre>
032         * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
033         * String pattern = String.format(AsyncAppenderAdminMBean.PATTERN, &quot;*&quot;, &quot;*&quot;);
034         * Set&lt;ObjectName&gt; appenderNames = mbs.queryNames(new ObjectName(pattern), null);
035         * </pre>
036         * <p>
037         * Some characters are not allowed in ObjectNames. The logger context name
038         * and appender name may be quoted. When AsyncAppenderAdmin MBeans are
039         * registered, their ObjectNames are created using this pattern as follows:
040         * </p>
041         * 
042         * <pre>
043         * String ctxName = Server.escape(loggerContext.getName());
044         * String appenderName = Server.escape(appender.getName());
045         * String name = String.format(PATTERN, ctxName, appenderName);
046         * ObjectName objectName = new ObjectName(name);
047         * </pre>
048         * 
049         * @see Server#escape(String)
050         */
051        String PATTERN = Server.DOMAIN + ":type=%s,component=AsyncAppenders,name=%s";
052    
053        /**
054         * Returns the name of the instrumented {@code AsyncAppender}.
055         * 
056         * @return the name of the AsyncAppender
057         */
058        String getName();
059    
060        /**
061         * Returns the result of calling {@code toString} on the {@code Layout}
062         * object of the instrumented {@code AsyncAppender}.
063         * 
064         * @return the {@code Layout} of the instrumented {@code AsyncAppender} as a
065         *         string
066         */
067        String getLayout();
068    
069        /**
070         * Returns how exceptions thrown on the instrumented {@code AsyncAppender}
071         * are handled.
072         * 
073         * @return {@code true} if any exceptions thrown by the AsyncAppender will
074         *         be logged or {@code false} if such exceptions are re-thrown.
075         */
076        boolean isIgnoreExceptions();
077    
078        /**
079         * Returns the result of calling {@code toString} on the error handler of
080         * this appender, or {@code "null"} if no error handler was set.
081         * 
082         * @return result of calling {@code toString} on the error handler of this
083         *         appender, or {@code "null"}
084         */
085        String getErrorHandler();
086    
087        /**
088         * Returns a string description of all filters configured for the
089         * instrumented {@code AsyncAppender}.
090         * 
091         * @return a string description of all configured filters for this appender
092         */
093        String getFilter();
094    
095        /**
096         * Returns a String array with the appender refs configured for the
097         * instrumented {@code AsyncAppender}.
098         * 
099         * @return the appender refs for the instrumented {@code AsyncAppender}.
100         */
101        String[] getAppenderRefs();
102    
103        /**
104         * Returns {@code true} if this AsyncAppender will take a snapshot of the
105         * stack with every log event to determine the class and method where the
106         * logging call was made.
107         * 
108         * @return {@code true} if location is included with every event,
109         *         {@code false} otherwise
110         */
111        boolean isIncludeLocation();
112    
113        /**
114         * Returns {@code true} if this AsyncAppender will block when the queue is
115         * full, or {@code false} if events are dropped when the queue is full.
116         * 
117         * @return whether this AsyncAppender will block or drop events when the
118         *         queue is full.
119         */
120        boolean isBlocking();
121        
122        /**
123         * Returns the name of the appender that any errors are logged to or {@code null}.
124         * @return the name of the appender that any errors are logged to or {@code null}
125         */
126        String getErrorRef();
127        
128        int getQueueCapacity();
129        
130        int getQueueRemainingCapacity();
131    }