/*
 * Copyright 2005 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */ 


package org.apache.commons.logging.impl;

import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;

import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

import org.apache.commons.logging.LogFactory;


/**
 * This class is capable of receiving notifications about the undeployment of
 * a webapp, and responds by ensuring that commons-logging releases all
 * memory associated with the undeployed webapp.
 * <p>
 * This class is necessary when code using commons-logging is deployed within
 * a servlet container and commons-logging is deployed via a shared classloader.
 * When commons-logging is deployed in a "shared" classloader that is visible 
 * to all webapps, commons-logging still ensures that each webapp gets its own
 * logging configuration by setting up a separate LogFactory object for each 
 * context classloader, and ensuring that the correct LogFactory object is 
 * used based on the context classloader set whenever LogFactory.getLog is 
 * called. However the negative side of this is that LogFactory needs to keep 
 * a static map of LogFactory objects keyed by context classloader; when the 
 * webapp is "undeployed" this means there is still a reference to the 
 * undeployed classloader preventing the memory used by all its classes from 
 * being reclaimed.  
 * <p>
 * To use this class, configure the webapp deployment descriptor to call
 * this class on webapp undeploy; the contextDestroyed method will tell
 * LogFactory that the entry in its map for the current webapp's context
 * classloader should be cleared.
 * 
 * @since 1.1
 */

public class ServletContextCleaner implements ServletContextListener {

    private Class[] RELEASE_SIGNATURE = {ClassLoader.class};
    
    /**
     * Invoked when a webapp is undeployed, this tells the LogFactory
     * class to release any logging information related to the current
     * contextClassloader.
     */
    public void contextDestroyed(ServletContextEvent sce) {
        ClassLoader tccl = Thread.currentThread().getContextClassLoader();

        Object[] params = new Object[1];
        params[0] = tccl;

        // Walk up the tree of classloaders, finding all the available
        // LogFactory classes and releasing any objects associated with
        // the tccl (ie the webapp).
        //
        // When there is only one LogFactory in the classpath, and it
        // is within the webapp being undeployed then there is no problem;
        // garbage collection works fine.
        //
        // When there are multiple LogFactory classes in the classpath but
        // parent-first classloading is used everywhere, this loop is really
        // short. The first instance of LogFactory found will
        // be the highest in the classpath, and then no more will be found.
        // This is ok, as with this setup this will be the only LogFactory
        // holding any data associated with the tccl being released.
        //
        // When there are multiple LogFactory classes in the classpath and
        // child-first classloading is used in any classloader, then multiple
        // LogFactory instances may hold info about this TCCL; whenever the
        // webapp makes a call into a class loaded via an ancestor classloader
        // and that class calls LogFactory the tccl gets registered in
        // the LogFactory instance that is visible from the ancestor
        // classloader. However the concrete logging library it points
        // to is expected to have been loaded via the TCCL, so the 
        // underlying logging lib is only initialised/configured once.
        // These references from ancestor LogFactory classes down to
        // TCCL classloaders are held via weak references and so should
        // be released but there are circumstances where they may not.
        // Walking up the classloader ancestry ladder releasing
        // the current tccl at each level tree, though, will definitely
        // clear any problem references.
        ClassLoader loader = tccl;
        while (loader != null) {
            // Load via the current loader. Note that if the class is not accessable
            // via this loader, but is accessable via some ancestor then that class
            // will be returned.
            try {
                Class logFactoryClass = loader.loadClass("org.apache.commons.logging.LogFactory");
                Method releaseMethod = logFactoryClass.getMethod("release", RELEASE_SIGNATURE);
                releaseMethod.invoke(null, params);
                loader = logFactoryClass.getClassLoader().getParent();
            } catch(ClassNotFoundException ex) {
                // Neither the current classloader nor any of its ancestors could find
                // the LogFactory class, so we can stop now.
                loader = null;
            } catch(NoSuchMethodException ex) {
                // This is not expected; every version of JCL has this method
                System.err.println("LogFactory instance found which does not support release method!");
                loader = null;
            } catch(IllegalAccessException ex) {
                // This is not expected; every ancestor class should be accessable
                System.err.println("LogFactory instance found which is not accessable!");
                loader = null;
            } catch(InvocationTargetException ex) {
                // This is not expected
                System.err.println("LogFactory instance release method failed!");
                loader = null;
            }
        }
        
        // Just to be sure, invoke release on the LogFactory that is visible from
        // this ServletContextCleaner class too. This should already have been caught
        // by the above loop but just in case...
        LogFactory.release(tccl);
    }
    
    /**
     * Invoked when a webapp is deployed. Nothing needs to be done here.
     */
    public void contextInitialized(ServletContextEvent sce) {
        // do nothing
    }
}

@@ -1096,47 +1096,54 @@
 %0A * 
-This class is necessary when code us
+In general, the WeakHashtable support added 
 in
-g
  com
@@ -1159,824 +1159,541 @@
 ing 
-is deployed within%0A * a servlet container and commons-logging is deployed via a shared classloader.%0A * When commons-logging is deployed in a %22shared%22 classloader that is visible %0A * to all webapps, commons-logging still ensures that each webapp gets its own%0A * logging configuration by setting up a separate LogFactory object for each %0A * context classloader, and ensuring that the correct LogFactory object is %0A * used based on the context classloader set whenever LogFactory.getLog is %0A * called. However the negative side of this is that LogFactory needs to keep %0A * a static map of LogFactory objects keyed by context classloader; when
+release 1.1%0A * ensures that logging classes do not hold references that prevent an%0A * undeployed webapp's memory from being garbage-collected even when multiple%0A * copies of commons-logging are deployed via multiple classloaders (a%0A * situation that earlier versions had problems with). However there are%0A * some rare cases where the WeakHashtable approach does not work; in these%0A * situations specifying this class as a listener for
  the 
-%0A * 
 web
+ 
 app
- is %22undeployed%22 this means there is still a reference to the %0A * undeployed classloader preventing the memory used by all its classes from %0A * being reclaim
+lication will%0A * ensure that all references held by commons-logging are fully releas
 ed.
-  
 %0A * 
@@ -1843,16 +1843,33 @@
  tell%0A *
+ every accessable
  LogFact
@@ -1868,24 +1868,30 @@
  LogFactory 
+class 
 that the ent
@@ -1907,24 +1907,27 @@
  map for the
+%0A *
  current web
@@ -1939,19 +1939,16 @@
  context
-%0A *
  classlo

Update javadoc now that WeakHashtable is part of the standard distribution. ServletContextCleaner is only a backup for odd corner cases.