    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.beanutils;
    019
    020import java.util.Map;
    021import java.util.WeakHashMap;
    022
    023/**
    024 * An instance of this class represents a value that is provided per (thread)
    025 * context classloader.
    026 *
    027 * <p>Occasionally it is necessary to store data in "global" variables
    028 * (including uses of the Singleton pattern). In applications which have only
    029 * a single classloader such data can simply be stored as "static" members on
    030 * some class. When multiple classloaders are involved, however, this approach
    031 * can fail; in particular, this doesn't work when the code may be run within a
    032 * servlet container or a j2ee container, and the class on which the static
    033 * member is defined is loaded via a "shared" classloader that is visible to all
    034 * components running within the container. This class provides a mechanism for
    035 * associating data with a ClassLoader instance, which ensures that when the
    036 * code runs in such a container each component gets its own copy of the
    037 * "global" variable rather than unexpectedly sharing a single copy of the
    038 * variable with other components that happen to be running in the same
    039 * container at the same time (eg servlets or EJBs.)</p>
    040 *
    041 * <p>This class is strongly patterned after the java.lang.ThreadLocal
    042 * class, which performs a similar task in allowing data to be associated
    043 * with a particular thread.</p>
    044 *
    045 * <p>When code that uses this class is run as a "normal" application, ie
    046 * not within a container, the effect is identical to just using a static
    047 * member variable to store the data, because Thread.getContextClassLoader
    048 * always returns the same classloader (the system classloader).</p>
    049 *
    050 * <p>Expected usage is as follows:<br>
    051 * <pre>
    052 *  public class SomeClass {
    053 *    private static final ContextClassLoaderLocal&lt;String&gt; global
    054 *      = new ContextClassLoaderLocal&lt;String&gt;() {
    055 *          protected String initialValue() {
    056 *              return new String("Initial value");
    057 *          };
    058 *
    059 *    public void testGlobal() {
    060 *      String s = global.get();
    061 *      System.out.println("global value:" + s);
    062 *      buf.set("New Value");
    063 *    }
    064 * </pre>
    065 * <p><strong>Note:</strong> This class takes some care to ensure that when
    066 * a component which uses this class is "undeployed" by a container the
    067 * component-specific classloader and all its associated classes (and their
    068 * static variables) are garbage-collected. Unfortunately there is one
    069 * scenario in which this does <em>not</em> work correctly and there
    070 * is unfortunately no known workaround other than ensuring that the
    071 * component (or its container) calls the "unset" method on this class for
    072 * each instance of this class when the component is undeployed. The problem
    073 * occurs if:
    074 * </p>
    075 * <ul>
    076 * <li>the class containing a static instance of this class was loaded via
    077 * a shared classloader, and</li>
    078 * <li>the value stored in the instance is an object whose class was loaded
    079 * via the component-specific classloader (or any of the objects it refers
    080 * to were loaded via that classloader).</li>
    081 * </ul>
    082 * <p>
    083 * The result is that the map managed by this object still contains a strong
    084 * reference to the stored object, which contains a strong reference to the
    085 * classloader that loaded it, meaning that although the container has
    086 * "undeployed" the component the component-specific classloader and all the
    087 * related classes and static variables cannot be garbage-collected. This is
    088 * not expected to be an issue with the commons-beanutils library as the only
    089 * classes which use this class are BeanUtilsBean and ConvertUtilsBean and
    090 * there is no obvious reason for a user of the beanutils library to subclass
    091 * either of those classes.</p>
    092 *
    093 * <p><strong>Note:</strong> A WeakHashMap bug in several 1.3 JVMs results in
    094 * a memory leak for those JVMs.</p>
    095 *
    096 * <p><strong>Note:</strong> Of course all of this would be unnecessary if
    097 * containers required each component to load the full set of classes it
    098 * needs, ie avoided providing classes loaded via a "shared" classloader.</p>
    099 *
    100 * @param <T> the type of data stored in an instance
    101 * @see java.lang.Thread#getContextClassLoader
    102 */
    103public class ContextClassLoaderLocal<T> {
    104    private final Map<ClassLoader, T> valueByClassLoader = new WeakHashMap<>();
    105    private boolean globalValueInitialized;
    106    private T globalValue;
    107
    108    /**
    109     * Construct a context classloader instance
    110     */
    111    public ContextClassLoaderLocal() {
    112    }
    113
    114    /**
    115     * Gets the instance which provides the functionality for {@link BeanUtils}.
    116     * This is a pseudo-singleton - an single instance is provided per (thread) context classloader.
    117     * This mechanism provides isolation for web apps deployed in the same container.
    118     * @return the object currently associated with the context-classloader of the current thread.
    119     */
    120    public synchronized T get() {
    121        // synchronizing the whole method is a bit slower
    122        // but guarantees no subtle threading problems, and there's no
    123        // need to synchronize valueByClassLoader
    124
    125        // make sure that the map is given a change to purge itself
    126        valueByClassLoader.isEmpty();
    127        try {
    128
    129            final ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    130            if (contextClassLoader != null) {
    131
    132                T value = valueByClassLoader.get(contextClassLoader);
    133                if (value == null
    134                && !valueByClassLoader.containsKey(contextClassLoader)) {
    135                    value = initialValue();
    136                    valueByClassLoader.put(contextClassLoader, value);
    137                }
    138                return value;
    139
    140            }
    141
    142        } catch (final SecurityException e) { /* SWALLOW - should we log this? */ }
    143
    144        // if none or exception, return the globalValue
    145        if (!globalValueInitialized) {
    146            globalValue = initialValue();
    147            globalValueInitialized = true;
    148        }//else already set
    149        return globalValue;
    150    }
    151
    152    /**
    153     * Returns the initial value for this ContextClassLoaderLocal
    154     * variable. This method will be called once per Context ClassLoader for
    155     * each ContextClassLoaderLocal, the first time it is accessed
    156     * with get or set.  If the programmer desires ContextClassLoaderLocal variables
    157     * to be initialized to some value other than null, ContextClassLoaderLocal must
    158     * be subclassed, and this method overridden.  Typically, an anonymous
    159     * inner class will be used.  Typical implementations of initialValue
    160     * will call an appropriate constructor and return the newly constructed
    161     * object.
    162     *
    163     * @return a new Object to be used as an initial value for this ContextClassLoaderLocal
    164     */
    165    protected T initialValue() {
    166        return null;
    167    }
    168
    169    /**
    170     * Sets the value - a value is provided per (thread) context classloader.
    171     * This mechanism provides isolation for web apps deployed in the same container.
    172     *
    173     * @param value the object to be associated with the entrant thread's context classloader
    174     */
    175    public synchronized void set(final T value) {
    176        // synchronizing the whole method is a bit slower
    177        // but guarentees no subtle threading problems
    178
    179        // make sure that the map is given a change to purge itself
    180        valueByClassLoader.isEmpty();
    181        try {
    182
    183            final ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    184            if (contextClassLoader != null) {
    185                valueByClassLoader.put(contextClassLoader, value);
    186                return;
    187            }
    188
    189        } catch (final SecurityException e) { /* SWALLOW - should we log this? */ }
    190
    191        // if in doubt, set the global value
    192        globalValue = value;
    193        globalValueInitialized = true;
    194    }
    195
    196    /**
    197     * Unsets the value associated with the current thread's context classloader
    198     */
    199    public synchronized void unset() {
    200        try {
    201
    202            final ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    203            unset(contextClassLoader);
    204
    205        } catch (final SecurityException e) { /* SWALLOW - should we log this? */ }
    206    }
    207
    208    /**
    209     * Unsets the value associated with the given classloader
    210     * @param classLoader The classloader to <em>unset</em> for
    211     */
    212    public synchronized void unset(final ClassLoader classLoader) {
    213        valueByClassLoader.remove(classLoader);
    214    }
    215}