    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.web;
    018
    019    import org.apache.logging.log4j.spi.LoggerContext;
    020
    021    /**
    022     * Specifies an interface for setting and clearing a thread-bound {@link LoggerContext} in a Java EE web application.
    023     * Also defines constants for context parameter and attribute names. In most cases you will never need to use this
    024     * directly because the Log4j filter handles this task automatically. However, in async operations you should wrap
    025     * code that executes in separate threads with {@link #setLoggerContext} and {@link #clearLoggerContext}.
    026     *
    027     * <p>
    028     * You can obtain the instance of this for your web application by retrieving the {@link javax.servlet.ServletContext}
    029     * attribute named {@code org.apache.logging.log4j.core.web.Log4jWebSupport.INSTANCE}. If needed, you can also obtain
    030     * the {@link LoggerContext} instance for your web application by retrieving the {@code ServletContext} attribute named
    031     * {@code org.apache.logging.log4j.spi.LoggerContext.INSTANCE}.
    032     * </p>
    033     */
    034    public interface Log4jWebSupport {
    035        /**
    036         * The {@link javax.servlet.ServletContext} parameter name for the name of the
    037         * {@link org.apache.logging.log4j.core.LoggerContext}.
    038         */
    039        String LOG4J_CONTEXT_NAME = "log4jContextName";
    040
    041        /**
    042         * The {@link javax.servlet.ServletContext} parameter name for the location of the configuration.
    043         */
    044        String LOG4J_CONFIG_LOCATION = "log4jConfiguration";
    045
    046        /**
    047         * The {@link javax.servlet.ServletContext} parameter name for the JNDI flag.
    048         */
    049        String IS_LOG4J_CONTEXT_SELECTOR_NAMED = "isLog4jContextSelectorNamed";
    050
    051        /**
    052         * The {@link javax.servlet.ServletContext} parameter name for the flag that disables Log4j's auto-initialization
    053         * in Servlet 3.0+ web applications. Set a context parameter with this name to "true" to disable
    054         * auto-initialization.
    055         */
    056        String IS_LOG4J_AUTO_INITIALIZATION_DISABLED = "isLog4jAutoInitializationDisabled";
    057
    058        /**
    059         * The attribute key for the {@link javax.servlet.ServletContext} attribute that the singleton support instance
    060         * is stored in.
    061         */
    062        String SUPPORT_ATTRIBUTE = Log4jWebSupport.class.getName() + ".INSTANCE";
    063
    064        /**
    065         * The attribute key for the {@link javax.servlet.ServletContext} attribute that the {@link LoggerContext}
    066         * is stored in.
    067         */
    068        String CONTEXT_ATTRIBUTE = LoggerContext.class.getName() + ".INSTANCE";
    069
    070        /**
    071         * Sets the logger context so that code executing afterwards can easily and quickly access loggers via
    072         * {@link org.apache.logging.log4j.LogManager#getLogger}.
    073         */
    074        void setLoggerContext();
    075
    076        /**
    077         * Clears the logger context set up in {@link #setLoggerContext}.
    078         */
    079        void clearLoggerContext();
    080
    081        /**
    082         * Sets the logger context by calling {@link #setLoggerContext}, executes the runnable argument, then clears the
    083         * logger context by calling {@link #clearLoggerContext}.
    084         *
    085         * @param runnable The runnable to execute wrapped with a configured logger context
    086         */
    087        void wrapExecution(Runnable runnable);
    088    }