    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
    018package org.apache.commons.logging.impl;
    019
    020import java.io.PrintWriter;
    021import java.io.StringWriter;
    022import java.lang.reflect.Constructor;
    023import java.lang.reflect.InvocationTargetException;
    024import java.lang.reflect.Method;
    025import java.net.URL;
    026import java.security.AccessController;
    027import java.security.PrivilegedAction;
    028import java.util.Hashtable;
    029
    030import org.apache.commons.logging.Log;
    031import org.apache.commons.logging.LogConfigurationException;
    032import org.apache.commons.logging.LogFactory;
    033
    034/**
    035 * Concrete subclass of {@link LogFactory} that implements the
    036 * following algorithm to dynamically select a logging implementation
    037 * class to instantiate a wrapper for:
    038 * <ul>
    039 * <li>Use a factory configuration attribute named
    040 *     {@code org.apache.commons.logging.Log} to identify the
    041 *     requested implementation class.</li>
    042 * <li>Use the {@code org.apache.commons.logging.Log} system property
    043 *     to identify the requested implementation class.</li>
    044 * <li>If <em>Log4J</em> is available, return an instance of
    045 *     {@code org.apache.commons.logging.impl.Log4JLogger}.</li>
    046 * <li>If <em>JDK 1.4 or later</em> is available, return an instance of
    047 *     {@code org.apache.commons.logging.impl.Jdk14Logger}.</li>
    048 * <li>Otherwise, return an instance of
    049 *     {@code org.apache.commons.logging.impl.SimpleLog}.</li>
    050 * </ul>
    051 * <p>
    052 * If the selected {@link Log} implementation class has a
    053 * {@code setLogFactory()} method that accepts a {@link LogFactory}
    054 * parameter, this method will be called on each newly created instance
    055 * to identify the associated factory.  This makes factory configuration
    056 * attributes available to the Log instance, if it so desires.
    057 * <p>
    058 * This factory will remember previously created {@code Log} instances
    059 * for the same name, and will return them on repeated requests to the
    060 * {@code getInstance()} method.
    061 */
    062public class LogFactoryImpl extends LogFactory {
    063
    064    /** Log4JLogger class name */
    065    private static final String LOGGING_IMPL_LOG4J_LOGGER = "org.apache.commons.logging.impl.Log4JLogger";
    066    /** Jdk14Logger class name */
    067    private static final String LOGGING_IMPL_JDK14_LOGGER = "org.apache.commons.logging.impl.Jdk14Logger";
    068    /** Jdk13LumberjackLogger class name */
    069    private static final String LOGGING_IMPL_LUMBERJACK_LOGGER =
    070            "org.apache.commons.logging.impl.Jdk13LumberjackLogger";
    071
    072    /** SimpleLog class name */
    073    private static final String LOGGING_IMPL_SIMPLE_LOGGER = "org.apache.commons.logging.impl.SimpleLog";
    074
    075    private static final String PKG_IMPL="org.apache.commons.logging.impl.";
    076    private static final int PKG_LEN = PKG_IMPL.length();
    077
    078    /**
    079     * An empty immutable {@code String} array.
    080     */
    081    private static final String[] EMPTY_STRING_ARRAY = {};
    082
    083    /**
    084     * The name ({@code org.apache.commons.logging.Log}) of the system
    085     * property identifying our {@link Log} implementation class.
    086     */
    087    public static final String LOG_PROPERTY = "org.apache.commons.logging.Log";
    088
    089    /**
    090     * The deprecated system property used for backwards compatibility with
    091     * old versions of JCL.
    092     */
    093    protected static final String LOG_PROPERTY_OLD = "org.apache.commons.logging.log";
    094
    095    /**
    096     * The name ({@code org.apache.commons.logging.Log.allowFlawedContext})
    097     * of the system property which can be set true/false to
    098     * determine system behavior when a bad context class loader is encountered.
    099     * When set to false, a LogConfigurationException is thrown if
    100     * LogFactoryImpl is loaded via a child class loader of the TCCL (this
    101     * should never happen in sane systems).
    102     *
    103     * Default behavior: true (tolerates bad context class loaders)
    104     *
    105     * See also method setAttribute.
    106     */
    107    public static final String ALLOW_FLAWED_CONTEXT_PROPERTY =
    108        "org.apache.commons.logging.Log.allowFlawedContext";
    109
    110    /**
    111     * The name ({@code org.apache.commons.logging.Log.allowFlawedDiscovery})
    112     * of the system property which can be set true/false to
    113     * determine system behavior when a bad logging adapter class is
    114     * encountered during logging discovery. When set to false, an
    115     * exception will be thrown and the app will fail to start. When set
    116     * to true, discovery will continue (though the user might end up
    117     * with a different logging implementation than they expected).
    118     * <p>
    119     * Default behavior: true (tolerates bad logging adapters)
    120     *
    121     * See also method setAttribute.
    122     */
    123    public static final String ALLOW_FLAWED_DISCOVERY_PROPERTY =
    124        "org.apache.commons.logging.Log.allowFlawedDiscovery";
    125
    126    /**
    127     * The name ({@code org.apache.commons.logging.Log.allowFlawedHierarchy})
    128     * of the system property which can be set true/false to
    129     * determine system behavior when a logging adapter class is
    130     * encountered which has bound to the wrong Log class implementation.
    131     * When set to false, an exception will be thrown and the app will fail
    132     * to start. When set to true, discovery will continue (though the user
    133     * might end up with a different logging implementation than they expected).
    134     * <p>
    135     * Default behavior: true (tolerates bad Log class hierarchy)
    136     *
    137     * See also method setAttribute.
    138     */
    139    public static final String ALLOW_FLAWED_HIERARCHY_PROPERTY =
    140        "org.apache.commons.logging.Log.allowFlawedHierarchy";
    141
    142    /**
    143     * The names of classes that will be tried (in order) as logging
    144     * adapters. Each class is expected to implement the Log interface,
    145     * and to throw NoClassDefFound or ExceptionInInitializerError when
    146     * loaded if the underlying logging library is not available. Any
    147     * other error indicates that the underlying logging library is available
    148     * but broken/unusable for some reason.
    149     */
    150    private static final String[] classesToDiscover = {
    151            LOGGING_IMPL_JDK14_LOGGER,
    152            LOGGING_IMPL_SIMPLE_LOGGER
    153    };
    154
    155    /**
    156     * Workaround for bug in Java1.2; in theory this method is not needed. {@link LogFactory#getClassLoader(Class)}.
    157     *
    158     * @param clazz See {@link LogFactory#getClassLoader(Class)}.
    159     * @return See {@link LogFactory#getClassLoader(Class)}.
    160     * @since 1.1
    161     */
    162    protected static ClassLoader getClassLoader(final Class<?> clazz) {
    163        return LogFactory.getClassLoader(clazz);
    164    }
    165
    166    /**
    167     * Gets the context ClassLoader.
    168     * This method is a workaround for a Java 1.2 compiler bug.
    169     *
    170     * @return the context ClassLoader
    171     * @since 1.1
    172     */
    173    protected static ClassLoader getContextClassLoader() throws LogConfigurationException {
    174        return LogFactory.getContextClassLoader();
    175    }
    176
    177    /**
    178     * Calls LogFactory.directGetContextClassLoader under the control of an
    179     * AccessController class. This means that Java code running under a
    180     * security manager that forbids access to ClassLoaders will still work
    181     * if this class is given appropriate privileges, even when the caller
    182     * doesn't have such privileges. Without using an AccessController, the
    183     * the entire call stack must have the privilege before the call is
    184     * allowed.
    185     *
    186     * @return the context class loader associated with the current thread,
    187     * or null if security doesn't allow it.
    188     *
    189     * @throws LogConfigurationException if there was some weird error while
    190     * attempting to get the context class loader.
    191     *
    192     * @throws SecurityException if the current Java security policy doesn't
    193     * allow this class to access the context class loader.
    194     */
    195    private static ClassLoader getContextClassLoaderInternal()
    196            throws LogConfigurationException {
    197        return AccessController.doPrivileged((PrivilegedAction<ClassLoader>) LogFactory::directGetContextClassLoader);
    198    }
    199
    200    /**
    201     * Read the specified system property, using an AccessController so that
    202     * the property can be read if JCL has been granted the appropriate
    203     * security rights even if the calling code has not.
    204     * <p>
    205     * Take care not to expose the value returned by this method to the
    206     * calling application in any way; otherwise the calling app can use that
    207     * info to access data that should not be available to it.
    208     */
    209    private static String getSystemProperty(final String key, final String def)
    210            throws SecurityException {
    211        return AccessController.doPrivileged((PrivilegedAction<String>) () -> System.getProperty(key, def));
    212    }
    213
    214    /**
    215     * Workaround for bug in Java1.2; in theory this method is not needed.
    216     *
    217     * @return Same as {@link LogFactory#isDiagnosticsEnabled()}.
    218     * @see LogFactory#isDiagnosticsEnabled()
    219     */
    220    protected static boolean isDiagnosticsEnabled() {
    221        return LogFactory.isDiagnosticsEnabled();
    222    }
    223
    224    /** Utility method to safely trim a string. */
    225    private static String trim(final String src) {
    226        if (src == null) {
    227            return null;
    228        }
    229        return src.trim();
    230    }
    231
    232    /**
    233     * Determines whether logging classes should be loaded using the thread-context
    234     * class loader, or via the class loader that loaded this LogFactoryImpl class.
    235     */
    236    private boolean useTCCL = true;
    237
    238    /**
    239     * The string prefixed to every message output by the logDiagnostic method.
    240     */
    241    private String diagnosticPrefix;
    242
    243    /**
    244     * Configuration attributes.
    245     */
    246    protected Hashtable<String, Object> attributes = new Hashtable<>();
    247
    248    /**
    249     * The {@link org.apache.commons.logging.Log} instances that have
    250     * already been created, keyed by logger name.
    251     */
    252    protected Hashtable<String, Log> instances = new Hashtable<>();
    253
    254    /**
    255     * Name of the class implementing the Log interface.
    256     */
    257    private String logClassName;
    258
    259    /**
    260     * The one-argument constructor of the
    261     * {@link org.apache.commons.logging.Log}
    262     * implementation class that will be used to create new instances.
    263     * This value is initialized by {@code getLogConstructor()},
    264     * and then returned repeatedly.
    265     */
    266    protected Constructor<?> logConstructor;
    267
    268    /**
    269     * The signature of the Constructor to be used.
    270     */
    271    protected Class<?>[] logConstructorSignature = { String.class };
    272
    273    /**
    274     * The one-argument {@code setLogFactory} method of the selected
    275     * {@link org.apache.commons.logging.Log} method, if it exists.
    276     */
    277    protected Method logMethod;
    278
    279    /**
    280     * The signature of the {@code setLogFactory} method to be used.
    281     */
    282    protected Class<?>[] logMethodSignature = { LogFactory.class };
    283
    284    /**
    285     * See getBaseClassLoader and initConfiguration.
    286     */
    287    private boolean allowFlawedContext;
    288
    289    /**
    290     * See handleFlawedDiscovery and initConfiguration.
    291     */
    292    private boolean allowFlawedDiscovery;
    293
    294    /**
    295     * See handleFlawedHierarchy and initConfiguration.
    296     */
    297    private boolean allowFlawedHierarchy;
    298
    299    /**
    300     * Public no-arguments constructor required by the lookup mechanism.
    301     */
    302    public LogFactoryImpl() {
    303        initDiagnostics();  // method on this object
    304        if (isDiagnosticsEnabled()) {
    305            logDiagnostic("Instance created.");
    306        }
    307    }
    308
    309    /**
    310     * Attempts to load the given class, find a suitable constructor,
    311     * and instantiate an instance of Log.
    312     *
    313     * @param logAdapterClassName class name of the Log implementation
    314     * @param logCategory  argument to pass to the Log implementation's constructor
    315     * @param affectState  {@code true} if this object's state should
    316     *  be affected by this method call, {@code false} otherwise.
    317     * @return  an instance of the given class, or null if the logging
    318     *  library associated with the specified adapter is not available.
    319     * @throws LogConfigurationException if there was a serious error with
    320     *  configuration and the handleFlawedDiscovery method decided this
    321     *  problem was fatal.
    322     */
    323    private Log createLogFromClass(final String logAdapterClassName,
    324                                   final String logCategory,
    325                                   final boolean affectState)
    326        throws LogConfigurationException {
    327
    328        if (isDiagnosticsEnabled()) {
    329            logDiagnostic("Attempting to instantiate '" + logAdapterClassName + "'");
    330        }
    331
    332        final Object[] params = { logCategory };
    333        Log logAdapter = null;
    334        Constructor<?> constructor = null;
    335
    336        Class<?> logAdapterClass = null;
    337        ClassLoader currentCL = getBaseClassLoader();
    338
    339        for(;;) {
    340            // Loop through the class loader hierarchy trying to find
    341            // a viable class loader.
    342            logDiagnostic("Trying to load '" + logAdapterClassName + "' from class loader " + objectId(currentCL));
    343            try {
    344                if (isDiagnosticsEnabled()) {
    345                    // Show the location of the first occurrence of the .class file
    346                    // in the classpath. This is the location that ClassLoader.loadClass
    347                    // will load the class from -- unless the class loader is doing
    348                    // something weird.
    349                    URL url;
    350                    final String resourceName = logAdapterClassName.replace('.', '/') + ".class";
    351                    if (currentCL != null) {
    352                        url = currentCL.getResource(resourceName );
    353                    } else {
    354                        url = ClassLoader.getSystemResource(resourceName + ".class");
    355                    }
    356
    357                    if (url == null) {
    358                        logDiagnostic("Class '" + logAdapterClassName + "' [" + resourceName + "] cannot be found.");
    359                    } else {
    360                        logDiagnostic("Class '" + logAdapterClassName + "' was found at '" + url + "'");
    361                    }
    362                }
    363
    364                Class<?> clazz;
    365                try {
    366                    clazz = Class.forName(logAdapterClassName, true, currentCL);
    367                } catch (final ClassNotFoundException originalClassNotFoundException) {
    368                    // The current class loader was unable to find the log adapter
    369                    // in this or any ancestor class loader. There's no point in
    370                    // trying higher up in the hierarchy in this case..
    371                    String msg = originalClassNotFoundException.getMessage();
    372                    logDiagnostic("The log adapter '" + logAdapterClassName + "' is not available via class loader " +
    373                                  objectId(currentCL) + ": " + trim(msg));
    374                    try {
    375                        // Try the class class loader.
    376                        // This may work in cases where the TCCL
    377                        // does not contain the code executed or JCL.
    378                        // This behavior indicates that the application
    379                        // classloading strategy is not consistent with the
    380                        // Java 1.2 classloading guidelines but JCL can
    381                        // and so should handle this case.
    382                        clazz = Class.forName(logAdapterClassName);
    383                    } catch (final ClassNotFoundException secondaryClassNotFoundException) {
    384                        // no point continuing: this adapter isn't available
    385                        msg = secondaryClassNotFoundException.getMessage();
    386                        logDiagnostic("The log adapter '" + logAdapterClassName +
    387                                      "' is not available via the LogFactoryImpl class class loader: " + trim(msg));
    388                        break;
    389                    }
    390                }
    391
    392                constructor = clazz.getConstructor(logConstructorSignature);
    393                final Object o = constructor.newInstance(params);
    394
    395                // Note that we do this test after trying to create an instance
    396                // [rather than testing Log.class.isAssignableFrom(c)] so that
    397                // we don't complain about Log hierarchy problems when the
    398                // adapter couldn't be instantiated anyway.
    399                if (o instanceof Log) {
    400                    logAdapterClass = clazz;
    401                    logAdapter = (Log) o;
    402                    break;
    403                }
    404
    405                // Oops, we have a potential problem here. An adapter class
    406                // has been found and its underlying lib is present too, but
    407                // there are multiple Log interface classes available making it
    408                // impossible to cast to the type the caller wanted. We
    409                // certainly can't use this logger, but we need to know whether
    410                // to keep on discovering or terminate now.
    411                //
    412                // The handleFlawedHierarchy method will throw
    413                // LogConfigurationException if it regards this problem as
    414                // fatal, and just return if not.
    415                handleFlawedHierarchy(currentCL, clazz);
    416            } catch (final NoClassDefFoundError e) {
    417                // We were able to load the adapter but it had references to
    418                // other classes that could not be found. This simply means that
    419                // the underlying logger library is not present in this or any
    420                // ancestor class loader. There's no point in trying higher up
    421                // in the hierarchy in this case..
    422                final String msg = e.getMessage();
    423                logDiagnostic("The log adapter '" + logAdapterClassName +
    424                              "' is missing dependencies when loaded via class loader " + objectId(currentCL) +
    425                              ": " + trim(msg));
    426                break;
    427            } catch (final ExceptionInInitializerError e) {
    428                // A static initializer block or the initializer code associated
    429                // with a static variable on the log adapter class has thrown
    430                // an exception.
    431                //
    432                // We treat this as meaning the adapter's underlying logging
    433                // library could not be found.
    434                final String msg = e.getMessage();
    435                logDiagnostic("The log adapter '" + logAdapterClassName +
    436                              "' is unable to initialize itself when loaded via class loader " + objectId(currentCL) +
    437                              ": " + trim(msg));
    438                break;
    439            } catch (final LogConfigurationException e) {
    440                // call to handleFlawedHierarchy above must have thrown
    441                // a LogConfigurationException, so just throw it on
    442                throw e;
    443            } catch (final Throwable t) {
    444                handleThrowable(t); // may re-throw t
    445                // handleFlawedDiscovery will determine whether this is a fatal
    446                // problem or not. If it is fatal, then a LogConfigurationException
    447                // will be thrown.
    448                handleFlawedDiscovery(logAdapterClassName, t);
    449            }
    450
    451            if (currentCL == null) {
    452                break;
    453            }
    454
    455            // try the parent class loader
    456            // currentCL = currentCL.getParent();
    457            currentCL = getParentClassLoader(currentCL);
    458        }
    459
    460        if (logAdapterClass != null && affectState) {
    461            // We've succeeded, so set instance fields
    462            this.logClassName   = logAdapterClassName;
    463            this.logConstructor = constructor;
    464
    465            // Identify the {@code setLogFactory} method (if there is one)
    466            try {
    467                this.logMethod = logAdapterClass.getMethod("setLogFactory", logMethodSignature);
    468                logDiagnostic("Found method setLogFactory(LogFactory) in '" + logAdapterClassName + "'");
    469            } catch (final Throwable t) {
    470                handleThrowable(t); // may re-throw t
    471                this.logMethod = null;
    472                logDiagnostic("[INFO] '" + logAdapterClassName + "' from class loader " + objectId(currentCL) +
    473                              " does not declare optional method " + "setLogFactory(LogFactory)");
    474            }
    475
    476            logDiagnostic("Log adapter '" + logAdapterClassName + "' from class loader " +
    477                          objectId(logAdapterClass.getClassLoader()) + " has been selected for use.");
    478        }
    479
    480        return logAdapter;
    481    }
    482
    483        // Static Methods
    484    //
    485    // These methods only defined as workarounds for a java 1.2 bug;
    486    // theoretically none of these are needed.
    487
    488    /**
    489     * Attempts to create a Log instance for the given category name.
    490     * Follows the discovery process described in the class Javadoc.
    491     *
    492     * @param logCategory the name of the log category
    493     *
    494     * @throws LogConfigurationException if an error in discovery occurs,
    495     * or if no adapter at all can be instantiated
    496     */
    497    private Log discoverLogImplementation(final String logCategory)
    498        throws LogConfigurationException {
    499        if (isDiagnosticsEnabled()) {
    500            logDiagnostic("Discovering a Log implementation...");
    501        }
    502
    503        initConfiguration();
    504
    505        Log result = null;
    506
    507        // See if the user specified the Log implementation to use
    508        final String specifiedLogClassName = findUserSpecifiedLogClassName();
    509
    510        if (specifiedLogClassName != null) {
    511            if (isDiagnosticsEnabled()) {
    512                logDiagnostic("Attempting to load user-specified log class '" +
    513                    specifiedLogClassName + "'...");
    514            }
    515
    516            result = createLogFromClass(specifiedLogClassName,
    517                                        logCategory,
    518                                        true);
    519            if (result == null) {
    520                final StringBuilder messageBuffer =  new StringBuilder("User-specified log class '");
    521                messageBuffer.append(specifiedLogClassName);
    522                messageBuffer.append("' cannot be found or is not useable.");
    523
    524                // Mistyping or misspelling names is a common fault.
    525                // Construct a good error message, if we can
    526                informUponSimilarName(messageBuffer, specifiedLogClassName, LOGGING_IMPL_LOG4J_LOGGER);
    527                informUponSimilarName(messageBuffer, specifiedLogClassName, LOGGING_IMPL_JDK14_LOGGER);
    528                informUponSimilarName(messageBuffer, specifiedLogClassName, LOGGING_IMPL_LUMBERJACK_LOGGER);
    529                informUponSimilarName(messageBuffer, specifiedLogClassName, LOGGING_IMPL_SIMPLE_LOGGER);
    530                throw new LogConfigurationException(messageBuffer.toString());
    531            }
    532
    533            return result;
    534        }
    535
    536        // No user specified log; try to discover what's on the classpath
    537        //
    538        // Note that we deliberately loop here over classesToDiscover and
    539        // expect method createLogFromClass to loop over the possible source
    540        // class loaders. The effect is:
    541        //   for each discoverable log adapter
    542        //      for each possible class loader
    543        //          see if it works
    544        //
    545        // It appears reasonable at first glance to do the opposite:
    546        //   for each possible class loader
    547        //     for each discoverable log adapter
    548        //        see if it works
    549        //
    550        // The latter certainly has advantages for user-installable logging
    551        // libraries such as Log4j; in a webapp for example this code should
    552        // first check whether the user has provided any of the possible
    553        // logging libraries before looking in the parent class loader.
    554        // Unfortunately, however, Jdk14Logger will always work in jvm>=1.4,
    555        // and SimpleLog will always work in any JVM. So the loop would never
    556        // ever look for logging libraries in the parent classpath. Yet many
    557        // users would expect that putting Log4j there would cause it to be
    558        // detected (and this is the historical JCL behavior). So we go with
    559        // the first approach. A user that has bundled a specific logging lib
    560        // in a webapp should use a commons-logging.properties file or a
    561        // service file in META-INF to force use of that logging lib anyway,
    562        // rather than relying on discovery.
    563
    564        if (isDiagnosticsEnabled()) {
    565            logDiagnostic(
    566                "No user-specified Log implementation; performing discovery" +
    567                " using the standard supported logging implementations...");
    568        }
    569        for(int i=0; i<classesToDiscover.length && result == null; ++i) {
    570            result = createLogFromClass(classesToDiscover[i], logCategory, true);
    571        }
    572
    573        if (result == null) {
    574            throw new LogConfigurationException
    575                        ("No suitable Log implementation");
    576        }
    577
    578        return result;
    579    }
    580
    581    /**
    582     * Checks system properties and the attribute map for
    583     * a Log implementation specified by the user under the
    584     * property names {@link #LOG_PROPERTY} or {@link #LOG_PROPERTY_OLD}.
    585     *
    586     * @return class name specified by the user, or {@code null}
    587     */
    588    private String findUserSpecifiedLogClassName() {
    589        if (isDiagnosticsEnabled()) {
    590            logDiagnostic("Trying to get log class from attribute '" + LOG_PROPERTY + "'");
    591        }
    592        String specifiedClass = (String) getAttribute(LOG_PROPERTY);
    593
    594        if (specifiedClass == null) { // @deprecated
    595            if (isDiagnosticsEnabled()) {
    596                logDiagnostic("Trying to get log class from attribute '" +
    597                              LOG_PROPERTY_OLD + "'");
    598            }
    599            specifiedClass = (String) getAttribute(LOG_PROPERTY_OLD);
    600        }
    601
    602        if (specifiedClass == null) {
    603            if (isDiagnosticsEnabled()) {
    604                logDiagnostic("Trying to get log class from system property '" +
    605                          LOG_PROPERTY + "'");
    606            }
    607            try {
    608                specifiedClass = getSystemProperty(LOG_PROPERTY, null);
    609            } catch (final SecurityException e) {
    610                if (isDiagnosticsEnabled()) {
    611                    logDiagnostic("No access allowed to system property '" +
    612                        LOG_PROPERTY + "' - " + e.getMessage());
    613                }
    614            }
    615        }
    616
    617        if (specifiedClass == null) { // @deprecated
    618            if (isDiagnosticsEnabled()) {
    619                logDiagnostic("Trying to get log class from system property '" +
    620                          LOG_PROPERTY_OLD + "'");
    621            }
    622            try {
    623                specifiedClass = getSystemProperty(LOG_PROPERTY_OLD, null);
    624            } catch (final SecurityException e) {
    625                if (isDiagnosticsEnabled()) {
    626                    logDiagnostic("No access allowed to system property '" +
    627                        LOG_PROPERTY_OLD + "' - " + e.getMessage());
    628                }
    629            }
    630        }
    631
    632        // Remove any whitespace; it's never valid in a class name so its
    633        // presence just means a user mistake. As we know what they meant,
    634        // we may as well strip the spaces.
    635        if (specifiedClass != null) {
    636            specifiedClass = specifiedClass.trim();
    637        }
    638
    639        return specifiedClass;
    640    }
    641
    642    /**
    643     * Gets the configuration attribute with the specified name (if any),
    644     * or {@code null} if there is no such attribute.
    645     *
    646     * @param name Name of the attribute to return
    647     */
    648    @Override
    649    public Object getAttribute(final String name) {
    650        return attributes.get(name);
    651    }
    652
    653    /**
    654     * Gets an array containing the names of all currently defined
    655     * configuration attributes.  If there are no such attributes, a zero
    656     * length array is returned.
    657     */
    658    @Override
    659    public String[] getAttributeNames() {
    660        return attributes.keySet().toArray(EMPTY_STRING_ARRAY);
    661    }
    662
    663    /**
    664     * Gets the class loader from which we should try to load the logging
    665     * adapter classes.
    666     * <p>
    667     * This method usually returns the context class loader. However if it
    668     * is discovered that the class loader which loaded this class is a child
    669     * of the context class loader <em>and</em> the allowFlawedContext option
    670     * has been set then the class loader which loaded this class is returned
    671     * instead.
    672     * <p>
    673     * The only time when the class loader which loaded this class is a
    674     * descendant (rather than the same as or an ancestor of the context
    675     * class loader) is when an app has created custom class loaders but
    676     * failed to correctly set the context class loader. This is a bug in
    677     * the calling application; however we provide the option for JCL to
    678     * simply generate a warning rather than fail outright.
    679     */
    680    private ClassLoader getBaseClassLoader() throws LogConfigurationException {
    681        final ClassLoader thisClassLoader = getClassLoader(LogFactoryImpl.class);
    682
    683        if (!useTCCL) {
    684            return thisClassLoader;
    685        }
    686
    687        final ClassLoader contextClassLoader = getContextClassLoaderInternal();
    688
    689        final ClassLoader baseClassLoader = getLowestClassLoader(
    690                contextClassLoader, thisClassLoader);
    691
    692        if (baseClassLoader == null) {
    693           // The two class loaders are not part of a parent child relationship.
    694           // In some classloading setups (e.g. JBoss with its
    695           // UnifiedLoaderRepository) this can still work, so if user hasn't
    696           // forbidden it, just return the contextClassLoader.
    697           if (!allowFlawedContext) {
    698            throw new LogConfigurationException("Bad class loader hierarchy; LogFactoryImpl was loaded via" +
    699                                                " a class loader that is not related to the current context" +
    700                                                " class loader.");
    701           }
    702        if (isDiagnosticsEnabled()) {
    703               logDiagnostic("[WARNING] the context class loader is not part of a" +
    704                             " parent-child relationship with the class loader that" +
    705                             " loaded LogFactoryImpl.");
    706          }
    707          // If contextClassLoader were null, getLowestClassLoader() would
    708          // have returned thisClassLoader.  The fact we are here means
    709          // contextClassLoader is not null, so we can just return it.
    710          return contextClassLoader;
    711        }
    712
    713        if (baseClassLoader != contextClassLoader) {
    714            // We really should just use the contextClassLoader as the starting
    715            // point for scanning for log adapter classes. However it is expected
    716            // that there are a number of broken systems out there which create
    717            // custom class loaders but fail to set the context class loader so
    718            // we handle those flawed systems anyway.
    719            if (!allowFlawedContext) {
    720                throw new LogConfigurationException(
    721                        "Bad class loader hierarchy; LogFactoryImpl was loaded via" +
    722                        " a class loader that is not related to the current context" +
    723                        " class loader.");
    724            }
    725            if (isDiagnosticsEnabled()) {
    726                logDiagnostic(
    727                        "Warning: the context class loader is an ancestor of the" +
    728                        " class loader that loaded LogFactoryImpl; it should be" +
    729                        " the same or a descendant. The application using" +
    730                        " commons-logging should ensure the context class loader" +
    731                        " is used correctly.");
    732            }
    733        }
    734
    735        return baseClassLoader;
    736    }
    737
    738    /**
    739     * Gets the setting for the user-configurable behavior specified by key.
    740     * If nothing has explicitly been set, then return dflt.
    741     */
    742    private boolean getBooleanConfiguration(final String key, final boolean dflt) {
    743        final String val = getConfigurationValue(key);
    744        if (val == null) {
    745            return dflt;
    746        }
    747        return Boolean.parseBoolean(val);
    748    }
    749
    750    /**
    751     * Attempt to find an attribute (see method setAttribute) or a
    752     * system property with the provided name and return its value.
    753     * <p>
    754     * The attributes associated with this object are checked before
    755     * system properties in case someone has explicitly called setAttribute,
    756     * or a configuration property has been set in a commons-logging.properties
    757     * file.
    758     *
    759     * @return the value associated with the property, or null.
    760     */
    761    private String getConfigurationValue(final String property) {
    762        if (isDiagnosticsEnabled()) {
    763            logDiagnostic("[ENV] Trying to get configuration for item " + property);
    764        }
    765
    766        final Object valueObj =  getAttribute(property);
    767        if (valueObj != null) {
    768            if (isDiagnosticsEnabled()) {
    769                logDiagnostic("[ENV] Found LogFactory attribute [" + valueObj + "] for " + property);
    770            }
    771            return valueObj.toString();
    772        }
    773
    774        if (isDiagnosticsEnabled()) {
    775            logDiagnostic("[ENV] No LogFactory attribute found for " + property);
    776        }
    777
    778        try {
    779            // warning: minor security hole here, in that we potentially read a system
    780            // property that the caller cannot, then output it in readable form as a
    781            // diagnostic message. However it's only ever JCL-specific properties
    782            // involved here, so the harm is truly trivial.
    783            final String value = getSystemProperty(property, null);
    784            if (value != null) {
    785                if (isDiagnosticsEnabled()) {
    786                    logDiagnostic("[ENV] Found system property [" + value + "] for " + property);
    787                }
    788                return value;
    789            }
    790
    791            if (isDiagnosticsEnabled()) {
    792                logDiagnostic("[ENV] No system property found for property " + property);
    793            }
    794        } catch (final SecurityException e) {
    795            if (isDiagnosticsEnabled()) {
    796                logDiagnostic("[ENV] Security prevented reading system property " + property);
    797            }
    798        }
    799
    800        if (isDiagnosticsEnabled()) {
    801            logDiagnostic("[ENV] No configuration defined for item " + property);
    802        }
    803
    804        return null;
    805    }
    806
    807    /**
    808     * Convenience method to derive a name from the specified class and
    809     * call {@code getInstance(String)} with it.
    810     *
    811     * @param clazz Class for which a suitable Log name will be derived
    812     *
    813     * @throws LogConfigurationException if a suitable {@code Log}
    814     *  instance cannot be returned
    815     */
    816    @Override
    817    public Log getInstance(final Class<?> clazz) throws LogConfigurationException {
    818        return getInstance(clazz.getName());
    819    }
    820
    821    /**
    822     * <p>Construct (if necessary) and return a {@code Log} instance,
    823     * using the factory's current set of configuration attributes.</p>
    824     *
    825     * <p><strong>NOTE</strong> - Depending upon the implementation of
    826     * the {@code LogFactory} you are using, the {@code Log}
    827     * instance you are returned may or may not be local to the current
    828     * application, and may or may not be returned again on a subsequent
    829     * call with the same name argument.</p>
    830     *
    831     * @param name Logical name of the {@code Log} instance to be
    832     *  returned (the meaning of this name is only known to the underlying
    833     *  logging implementation that is being wrapped)
    834     *
    835     * @throws LogConfigurationException if a suitable {@code Log}
    836     *  instance cannot be returned
    837     */
    838    @Override
    839    public Log getInstance(final String name) throws LogConfigurationException {
    840        return instances.computeIfAbsent(name, this::newInstance);
    841    }
    842
    843    /**
    844     * Gets the fully qualified Java class name of the {@link Log} implementation we will be using.
    845     *
    846     * @return the fully qualified Java class name of the {@link Log} implementation we will be using.
    847     * @deprecated Never invoked by this class; subclasses should not assume it will be.
    848     */
    849    @Deprecated
    850    protected String getLogClassName() {
    851        if (logClassName == null) {
    852            discoverLogImplementation(getClass().getName());
    853        }
    854
    855        return logClassName;
    856    }
    857
    858    /**
    859     * <p>
    860     * Gets the {@code Constructor} that can be called to instantiate new {@link org.apache.commons.logging.Log} instances.
    861     * </p>
    862     *
    863     * <p>
    864     * <strong>IMPLEMENTATION NOTE</strong> - Race conditions caused by calling this method from more than one thread are ignored, because the same
    865     * {@code Constructor} instance will ultimately be derived in all circumstances.
    866     * </p>
    867     *
    868     * @return the {@code Constructor} that can be called to instantiate new {@link org.apache.commons.logging.Log} instances.
    869     *
    870     * @throws LogConfigurationException if a suitable constructor cannot be returned
    871     *
    872     * @deprecated Never invoked by this class; subclasses should not assume it will be.
    873     */
    874    @Deprecated
    875    protected Constructor<?> getLogConstructor()
    876        throws LogConfigurationException {
    877
    878        // Return the previously identified Constructor (if any)
    879        if (logConstructor == null) {
    880            discoverLogImplementation(getClass().getName());
    881        }
    882
    883        return logConstructor;
    884    }
    885
    886    //  ------------------------------------------------------ Private Methods
    887
    888    /**
    889     * Given two related class loaders, return the one which is a child of
    890     * the other.
    891     * <p>
    892     * @param c1 is a class loader (including the null class loader)
    893     * @param c2 is a class loader (including the null class loader)
    894     *
    895     * @return c1 if it has c2 as an ancestor, c2 if it has c1 as an ancestor,
    896     * and null if neither is an ancestor of the other.
    897     */
    898    private ClassLoader getLowestClassLoader(final ClassLoader c1, final ClassLoader c2) {
    899        // TODO: use AccessController when dealing with class loaders here
    900
    901        if (c1 == null) {
    902            return c2;
    903        }
    904
    905        if (c2 == null) {
    906            return c1;
    907        }
    908
    909        ClassLoader current;
    910
    911        // scan c1's ancestors to find c2
    912        current = c1;
    913        while (current != null) {
    914            if (current == c2) {
    915                return c1;
    916            }
    917            // current = current.getParent();
    918            current = getParentClassLoader(current);
    919        }
    920
    921        // scan c2's ancestors to find c1
    922        current = c2;
    923        while (current != null) {
    924            if (current == c1) {
    925                return c2;
    926            }
    927            // current = current.getParent();
    928            current = getParentClassLoader(current);
    929        }
    930
    931        return null;
    932    }
    933
    934    /**
    935     * Fetch the parent class loader of a specified class loader.
    936     * <p>
    937     * If a SecurityException occurs, null is returned.
    938     * <p>
    939     * Note that this method is non-static merely so logDiagnostic is available.
    940     */
    941    private ClassLoader getParentClassLoader(final ClassLoader cl) {
    942        try {
    943            return AccessController.doPrivileged((PrivilegedAction<ClassLoader>) () -> cl.getParent());
    944        } catch (final SecurityException ex) {
    945            logDiagnostic("[SECURITY] Unable to obtain parent class loader");
    946            return null;
    947        }
    948
    949    }
    950
    951    /**
    952     * Generates an internal diagnostic logging of the discovery failure and
    953     * then throws a {@code LogConfigurationException} that wraps
    954     * the passed {@code Throwable}.
    955     *
    956     * @param logAdapterClassName is the class name of the Log implementation
    957     * that could not be instantiated. Cannot be {@code null}.
    958     * @param discoveryFlaw is the Throwable created by the class loader
    959     *
    960     * @throws LogConfigurationException    ALWAYS
    961     */
    962    private void handleFlawedDiscovery(final String logAdapterClassName,
    963                                       final Throwable discoveryFlaw) {
    964
    965        if (isDiagnosticsEnabled()) {
    966            logDiagnostic("Could not instantiate Log '" +
    967                      logAdapterClassName + "' -- " +
    968                      discoveryFlaw.getClass().getName() + ": " +
    969                      discoveryFlaw.getLocalizedMessage());
    970
    971            if (discoveryFlaw instanceof InvocationTargetException ) {
    972                // Ok, the lib is there but while trying to create a real underlying
    973                // logger something failed in the underlying lib; display info about
    974                // that if possible.
    975                final InvocationTargetException ite = (InvocationTargetException) discoveryFlaw;
    976                final Throwable cause = ite.getTargetException();
    977                if (cause != null) {
    978                    logDiagnostic("... InvocationTargetException: " +
    979                        cause.getClass().getName() + ": " +
    980                        cause.getLocalizedMessage());
    981
    982                    if (cause instanceof ExceptionInInitializerError) {
    983                        final ExceptionInInitializerError eiie = (ExceptionInInitializerError) cause;
    984                        final Throwable cause2 = eiie.getCause();
    985                        if (cause2 != null) {
    986                            final StringWriter sw = new StringWriter();
    987                            cause2.printStackTrace(new PrintWriter(sw, true));
    988                            logDiagnostic("... ExceptionInInitializerError: " + sw.toString());
    989                        }
    990                    }
    991                }
    992            }
    993        }
    994
    995        if (!allowFlawedDiscovery) {
    996            throw new LogConfigurationException(discoveryFlaw);
    997        }
    998    }
    999
    1000    /**
    1001     * Report a problem loading the log adapter, then either return
    1002     * (if the situation is considered recoverable) or throw a
    1003     * LogConfigurationException.
    1004     * <p>
    1005     * There are two possible reasons why we successfully loaded the
    1006     * specified log adapter class then failed to cast it to a Log object:
    1007     * <ol>
    1008     * <li>the specific class just doesn't implement the Log interface
    1009     *     (user screwed up), or
    1010     * <li> the specified class has bound to a Log class loaded by some other
    1011     *      class loader; Log@ClassLoaderX cannot be cast to Log@ClassLoaderY.
    1012     * </ol>
    1013     * <p>
    1014     * Here we try to figure out which case has occurred so we can give the
    1015     * user some reasonable feedback.
    1016     *
    1017     * @param badClassLoader is the class loader we loaded the problem class from,
    1018     * ie it is equivalent to badClass.getClassLoader().
    1019     *
    1020     * @param badClass is a Class object with the desired name, but which
    1021     * does not implement Log correctly.
    1022     *
    1023     * @throws LogConfigurationException when the situation
    1024     * should not be recovered from.
    1025     */
    1026    private void handleFlawedHierarchy(final ClassLoader badClassLoader, final Class<?> badClass)
    1027        throws LogConfigurationException {
    1028
    1029        boolean implementsLog = false;
    1030        final String logInterfaceName = Log.class.getName();
    1031        final Class<?>[] interfaces = badClass.getInterfaces();
    1032        for (final Class<?> element : interfaces) {
    1033            if (logInterfaceName.equals(element.getName())) {
    1034                implementsLog = true;
    1035                break;
    1036            }
    1037        }
    1038
    1039        if (implementsLog) {
    1040            // the class does implement an interface called Log, but
    1041            // it is in the wrong class loader
    1042            if (isDiagnosticsEnabled()) {
    1043                try {
    1044                    final ClassLoader logInterfaceClassLoader = getClassLoader(Log.class);
    1045                    logDiagnostic("Class '" + badClass.getName() + "' was found in class loader " +
    1046                                  objectId(badClassLoader) + ". It is bound to a Log interface which is not" +
    1047                                  " the one loaded from class loader " + objectId(logInterfaceClassLoader));
    1048                } catch (final Throwable t) {
    1049                    handleThrowable(t); // may re-throw t
    1050                    logDiagnostic("Error while trying to output diagnostics about" + " bad class '" + badClass + "'");
    1051                }
    1052            }
    1053
    1054            if (!allowFlawedHierarchy) {
    1055                final StringBuilder msg = new StringBuilder();
    1056                msg.append("Terminating logging for this context ");
    1057                msg.append("due to bad log hierarchy. ");
    1058                msg.append("You have more than one version of '");
    1059                msg.append(Log.class.getName());
    1060                msg.append("' visible.");
    1061                if (isDiagnosticsEnabled()) {
    1062                    logDiagnostic(msg.toString());
    1063                }
    1064                throw new LogConfigurationException(msg.toString());
    1065            }
    1066
    1067            if (isDiagnosticsEnabled()) {
    1068                final StringBuilder msg = new StringBuilder();
    1069                msg.append("Warning: bad log hierarchy. ");
    1070                msg.append("You have more than one version of '");
    1071                msg.append(Log.class.getName());
    1072                msg.append("' visible.");
    1073                logDiagnostic(msg.toString());
    1074            }
    1075        } else {
    1076            // this is just a bad adapter class
    1077            if (!allowFlawedDiscovery) {
    1078                final StringBuilder msg = new StringBuilder();
    1079                msg.append("Terminating logging for this context. ");
    1080                msg.append("Log class '");
    1081                msg.append(badClass.getName());
    1082                msg.append("' does not implement the Log interface.");
    1083                if (isDiagnosticsEnabled()) {
    1084                    logDiagnostic(msg.toString());
    1085                }
    1086
    1087                throw new LogConfigurationException(msg.toString());
    1088            }
    1089
    1090            if (isDiagnosticsEnabled()) {
    1091                final StringBuilder msg = new StringBuilder();
    1092                msg.append("[WARNING] Log class '");
    1093                msg.append(badClass.getName());
    1094                msg.append("' does not implement the Log interface.");
    1095                logDiagnostic(msg.toString());
    1096            }
    1097        }
    1098    }
    1099
    1100    /**
    1101     * Appends message if the given name is similar to the candidate.
    1102     * @param messageBuffer {@code StringBuffer} the message should be appended to,
    1103     * not null
    1104     * @param name the (trimmed) name to be test against the candidate, not null
    1105     * @param candidate the candidate name (not null)
    1106     */
    1107    private void informUponSimilarName(final StringBuilder messageBuffer, final String name,
    1108            final String candidate) {
    1109        if (name.equals(candidate)) {
    1110            // Don't suggest a name that is exactly the same as the one the
    1111            // user tried...
    1112            return;
    1113        }
    1114
    1115        // If the user provides a name that is in the right package, and gets
    1116        // the first 5 characters of the adapter class right (ignoring case),
    1117        // then suggest the candidate adapter class name.
    1118        if (name.regionMatches(true, 0, candidate, 0, PKG_LEN + 5)) {
    1119            messageBuffer.append(" Did you mean '");
    1120            messageBuffer.append(candidate);
    1121            messageBuffer.append("'?");
    1122        }
    1123    }
    1124
    1125    /**
    1126     * Initialize a number of variables that control the behavior of this
    1127     * class and that can be tweaked by the user. This is done when the first
    1128     * logger is created, not in the constructor of this class, because we
    1129     * need to give the user a chance to call method setAttribute in order to
    1130     * configure this object.
    1131     */
    1132    private void initConfiguration() {
    1133        allowFlawedContext = getBooleanConfiguration(ALLOW_FLAWED_CONTEXT_PROPERTY, true);
    1134        allowFlawedDiscovery = getBooleanConfiguration(ALLOW_FLAWED_DISCOVERY_PROPERTY, true);
    1135        allowFlawedHierarchy = getBooleanConfiguration(ALLOW_FLAWED_HIERARCHY_PROPERTY, true);
    1136    }
    1137
    1138    /**
    1139     * Calculate and cache a string that uniquely identifies this instance,
    1140     * including which class loader the object was loaded from.
    1141     * <p>
    1142     * This string will later be prefixed to each "internal logging" message
    1143     * emitted, so that users can clearly see any unexpected behavior.
    1144     * <p>
    1145     * Note that this method does not detect whether internal logging is
    1146     * enabled or not, nor where to output stuff if it is; that is all
    1147     * handled by the parent LogFactory class. This method just computes
    1148     * its own unique prefix for log messages.
    1149     */
    1150    private void initDiagnostics() {
    1151        // It would be nice to include an identifier of the context class loader
    1152        // that this LogFactoryImpl object is responsible for. However that
    1153        // isn't possible as that information isn't available. It is possible
    1154        // to figure this out by looking at the logging from LogFactory to
    1155        // see the context & impl ids from when this object was instantiated,
    1156        // in order to link the impl id output as this object's prefix back to
    1157        // the context it is intended to manage.
    1158        // Note that this prefix should be kept consistent with that
    1159        // in LogFactory.
    1160        @SuppressWarnings("unchecked")
    1161        final Class<LogFactoryImpl> clazz = (Class<LogFactoryImpl>) this.getClass();
    1162        final ClassLoader classLoader = getClassLoader(clazz);
    1163        String classLoaderName;
    1164        try {
    1165            if (classLoader == null) {
    1166                classLoaderName = "BOOTLOADER";
    1167            } else {
    1168                classLoaderName = objectId(classLoader);
    1169            }
    1170        } catch (final SecurityException e) {
    1171            classLoaderName = "UNKNOWN";
    1172        }
    1173        diagnosticPrefix = "[LogFactoryImpl@" + System.identityHashCode(this) + " from " + classLoaderName + "] ";
    1174    }
    1175
    1176    /**
    1177     * Tests whether <em>JDK 1.3 with Lumberjack</em> logging available.
    1178     *
    1179     * @return whether <em>JDK 1.3 with Lumberjack</em> logging available.
    1180     * @deprecated Never invoked by this class; subclasses should not assume it will be.
    1181     */
    1182    @Deprecated
    1183    protected boolean isJdk13LumberjackAvailable() {
    1184        return isLogLibraryAvailable(
    1185                "Jdk13Lumberjack",
    1186                "org.apache.commons.logging.impl.Jdk13LumberjackLogger");
    1187    }
    1188
    1189    /**
    1190     * Tests {@code true} whether <em>JDK 1.4 or later</em> logging is available. Also checks that the {@code Throwable} class supports {@code getStackTrace()},
    1191     * which is required by Jdk14Logger.
    1192     *
    1193     * @return Whether <em>JDK 1.4 or later</em> logging is available.
    1194     *
    1195     * @deprecated Never invoked by this class; subclasses should not assume it will be.
    1196     */
    1197    @Deprecated
    1198    protected boolean isJdk14Available() {
    1199        return isLogLibraryAvailable("Jdk14", "org.apache.commons.logging.impl.Jdk14Logger");
    1200    }
    1201
    1202    /**
    1203     * Tests whether a <em>Log4J</em> implementation available.
    1204     *
    1205     * @return whether a <em>Log4J</em> implementation available.
    1206     *
    1207     * @deprecated Never invoked by this class; subclasses should not assume it will be.
    1208     */
    1209    @Deprecated
    1210    protected boolean isLog4JAvailable() {
    1211        return isLogLibraryAvailable("Log4J", LOGGING_IMPL_LOG4J_LOGGER);
    1212    }
    1213
    1214    /**
    1215     * Utility method to check whether a particular logging library is
    1216     * present and available for use. Note that this does <em>not</em>
    1217     * affect the future behavior of this class.
    1218     */
    1219    private boolean isLogLibraryAvailable(final String name, final String className) {
    1220        if (isDiagnosticsEnabled()) {
    1221            logDiagnostic("Checking for '" + name + "'.");
    1222        }
    1223        try {
    1224            final Log log = createLogFromClass(
    1225                        className,
    1226                        this.getClass().getName(), // dummy category
    1227                        false);
    1228
    1229            if (log == null) {
    1230                if (isDiagnosticsEnabled()) {
    1231                    logDiagnostic("Did not find '" + name + "'.");
    1232                }
    1233                return false;
    1234            }
    1235            if (isDiagnosticsEnabled()) {
    1236                logDiagnostic("Found '" + name + "'.");
    1237            }
    1238            return true;
    1239        } catch (final LogConfigurationException e) {
    1240            if (isDiagnosticsEnabled()) {
    1241                logDiagnostic("Logging system '" + name + "' is available but not useable.");
    1242            }
    1243            return false;
    1244        }
    1245    }
    1246
    1247    /**
    1248     * Output a diagnostic message to a user-specified destination (if the
    1249     * user has enabled diagnostic logging).
    1250     *
    1251     * @param msg diagnostic message
    1252     * @since 1.1
    1253     */
    1254    protected void logDiagnostic(final String msg) {
    1255        if (isDiagnosticsEnabled()) {
    1256            logRawDiagnostic(diagnosticPrefix + msg);
    1257        }
    1258    }
    1259
    1260    /**
    1261     * Create and return a new {@link org.apache.commons.logging.Log} instance for the specified name.
    1262     *
    1263     * @param name Name of the new logger
    1264     * @return a new {@link org.apache.commons.logging.Log}
    1265     *
    1266     * @throws LogConfigurationException if a new instance cannot be created
    1267     */
    1268    protected Log newInstance(final String name) throws LogConfigurationException {
    1269        Log instance;
    1270        try {
    1271            if (logConstructor == null) {
    1272                instance = discoverLogImplementation(name);
    1273            }
    1274            else {
    1275                final Object[] params = { name };
    1276                instance = (Log) logConstructor.newInstance(params);
    1277            }
    1278
    1279            if (logMethod != null) {
    1280                final Object[] params = { this };
    1281                logMethod.invoke(instance, params);
    1282            }
    1283
    1284            return instance;
    1285
    1286        } catch (final LogConfigurationException lce) {
    1287
    1288            // this type of exception means there was a problem in discovery
    1289            // and we've already output diagnostics about the issue, etc.;
    1290            // just pass it on
    1291            throw lce;
    1292
    1293        } catch (final InvocationTargetException e) {
    1294            // A problem occurred invoking the Constructor or Method
    1295            // previously discovered
    1296            final Throwable c = e.getTargetException();
    1297            throw new LogConfigurationException(c == null ? e : c);
    1298        } catch (final Throwable t) {
    1299            handleThrowable(t); // may re-throw t
    1300            // A problem occurred invoking the Constructor or Method
    1301            // previously discovered
    1302            throw new LogConfigurationException(t);
    1303        }
    1304    }
    1305
    1306    /**
    1307     * Release any internal references to previously created
    1308     * {@link org.apache.commons.logging.Log}
    1309     * instances returned by this factory.  This is useful in environments
    1310     * like servlet containers, which implement application reloading by
    1311     * throwing away a ClassLoader.  Dangling references to objects in that
    1312     * class loader would prevent garbage collection.
    1313     */
    1314    @Override
    1315    public void release() {
    1316
    1317        logDiagnostic("Releasing all known loggers");
    1318        instances.clear();
    1319    }
    1320
    1321    /**
    1322     * Remove any configuration attribute associated with the specified name.
    1323     * If there is no such attribute, no action is taken.
    1324     *
    1325     * @param name Name of the attribute to remove
    1326     */
    1327    @Override
    1328    public void removeAttribute(final String name) {
    1329        attributes.remove(name);
    1330    }
    1331
    1332    /**
    1333     * Sets the configuration attribute with the specified name.  Calling
    1334     * this with a {@code null} value is equivalent to calling
    1335     * {@code removeAttribute(name)}.
    1336     * <p>
    1337     * This method can be used to set logging configuration programmatically
    1338     * rather than via system properties. It can also be used in code running
    1339     * within a container (such as a webapp) to configure behavior on a
    1340     * per-component level instead of globally as system properties would do.
    1341     * To use this method instead of a system property, call
    1342     * <pre>
    1343     * LogFactory.getFactory().setAttribute(...)
    1344     * </pre>
    1345     * This must be done before the first Log object is created; configuration
    1346     * changes after that point will be ignored.
    1347     * <p>
    1348     * This method is also called automatically if LogFactory detects a
    1349     * commons-logging.properties file; every entry in that file is set
    1350     * automatically as an attribute here.
    1351     *
    1352     * @param name Name of the attribute to set
    1353     * @param value Value of the attribute to set, or {@code null}
    1354     *  to remove any setting for this attribute
    1355     */
    1356    @Override
    1357    public void setAttribute(final String name, final Object value) {
    1358        if (logConstructor != null) {
    1359            logDiagnostic("setAttribute: call too late; configuration already performed.");
    1360        }
    1361
    1362        if (value == null) {
    1363            attributes.remove(name);
    1364        } else {
    1365            attributes.put(name, value);
    1366        }
    1367
    1368        if (name.equals(TCCL_KEY)) {
    1369            useTCCL = value != null && Boolean.parseBoolean(value.toString());
    1370        }
    1371    }
    1372}