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.spi;
018
019import java.net.URI;
020
021/**
022 * Implemented by factories that create {@link LoggerContext} objects.
023 */
024public interface LoggerContextFactory {
025
026    /**
027     * Shuts down the LoggerContext.
028     * @param fqcn The fully qualified class name of the caller.
029     * @param loader The ClassLoader to use or null.
030     * @param currentContext If true shuts down the current Context, if false shuts down the Context appropriate
031     * for the caller if a more appropriate Context can be determined.
032     * @param allContexts if true all LoggerContexts that can be located will be shutdown.
033     * @since 2.13.0
034     */
035    default void shutdown(String fqcn, ClassLoader loader, boolean currentContext, boolean allContexts) {
036        if (hasContext(fqcn, loader, currentContext)) {
037            LoggerContext ctx = getContext(fqcn, loader, null, currentContext);
038            if (ctx instanceof Terminable) {
039                ((Terminable) ctx).terminate();
040            }
041        }
042    }
043
044    /**
045     * Checks to see if a LoggerContext is installed. The default implementation returns false.
046     * @param fqcn The fully qualified class name of the caller.
047     * @param loader The ClassLoader to use or null.
048     * @param currentContext If true returns the current Context, if false returns the Context appropriate
049     * for the caller if a more appropriate Context can be determined.
050     * @return true if a LoggerContext has been installed, false otherwise.
051     * @since 2.13.0
052     */
053    default boolean hasContext(String fqcn, ClassLoader loader, boolean currentContext) {
054        return false;
055    }
056
057    /**
058     * Creates a {@link LoggerContext}.
059     *
060     * @param fqcn The fully qualified class name of the caller.
061     * @param loader The ClassLoader to use or null.
062     * @param currentContext If true returns the current Context, if false returns the Context appropriate
063     * for the caller if a more appropriate Context can be determined.
064     * @param externalContext An external context (such as a ServletContext) to be associated with the LoggerContext.
065     * @return The LoggerContext.
066     */
067    LoggerContext getContext(String fqcn, ClassLoader loader, Object externalContext, boolean currentContext);
068
069    /**
070     * Creates a {@link LoggerContext}.
071     *
072     * @param fqcn The fully qualified class name of the caller.
073     * @param loader The ClassLoader to use or null.
074     * @param currentContext If true returns the current Context, if false returns the Context appropriate
075     * for the caller if a more appropriate Context can be determined.
076     * @param configLocation The location of the configuration for the LoggerContext.
077     * @param externalContext An external context (such as a ServletContext) to be associated with the LoggerContext.
078     * @param name The name of the context or null.
079     * @return The LoggerContext.
080     */
081    LoggerContext getContext(String fqcn, ClassLoader loader, Object externalContext, boolean currentContext,
082                             URI configLocation, String name);
083
084    /**
085     * Removes knowledge of a LoggerContext.
086     *
087     * @param context The context to remove.
088     */
089    void removeContext(LoggerContext context);
090
091    /**
092     * Determines whether or not this factory and perhaps the underlying
093     * ContextSelector behavior depend on the callers classloader.
094     *
095     * This method should be overridden by implementations, however a default method is provided which always
096     * returns {@code true} to preserve the old behavior.
097     *
098     * @since 2.15.0
099     */
100    default boolean isClassLoaderDependent() {
101        return true;
102    }
103}