View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  package org.apache.commons.beanutils;
    19
    20  import java.util.Map;
    21  import java.util.WeakHashMap;
    22
    23  /***
    24   * An instance of this class represents a value that is provided per (thread)
    25   * context classloader.
    26   *
    27   * <p>Occasionally it is necessary to store data in "global" variables
    28   * (including uses of the Singleton pattern). In applications which have only
    29   * a single classloader such data can simply be stored as "static" members on
    30   * some class. When multiple classloaders are involved, however, this approach
    31   * can fail; in particular, this doesn't work when the code may be run within a
    32   * servlet container or a j2ee container, and the class on which the static
    33   * member is defined is loaded via a "shared" classloader that is visible to all
    34   * components running within the container. This class provides a mechanism for
    35   * associating data with a ClassLoader instance, which ensures that when the
    36   * code runs in such a container each component gets its own copy of the
    37   * "global" variable rather than unexpectedly sharing a single copy of the
    38   * variable with other components that happen to be running in the same
    39   * container at the same time (eg servlets or EJBs.)</p>
    40   *
    41   * <p>This class is strongly patterned after the java.lang.ThreadLocal
    42   * class, which performs a similar task in allowing data to be associated
    43   * with a particular thread.</p>
    44   *
    45   * <p>When code that uses this class is run as a "normal" application, ie
    46   * not within a container, the effect is identical to just using a static
    47   * member variable to store the data, because Thread.getContextClassLoader
    48   * always returns the same classloader (the system classloader).</p>
    49   *
    50   * <p>Expected usage is as follows:<br>
    51   * <pre>
    52   *  public class SomeClass {
    53   *    private static final ContextClassLoaderLocal global
    54   *      = new ContextClassLoaderLocal() {
    55   *          protected Object initialValue() {
    56   *              return new String("Initial value");
    57   *          };
    58   *
    59   *    public void testGlobal() {
    60   *      String s = (String) global.get();
    61   *      System.out.println("global value:" + s);
    62   *      buf.set("New Value");
    63   *    }
    64   * </pre>
    65   * </p>
    66   *
    67   * <p><strong>Note:</strong> This class takes some care to ensure that when
    68   * a component which uses this class is "undeployed" by a container the
    69   * component-specific classloader and all its associated classes (and their
    70   * static variables) are garbage-collected. Unfortunately there is one
    71   * scenario in which this does <i>not</i> work correctly and there
    72   * is unfortunately no known workaround other than ensuring that the
    73   * component (or its container) calls the "unset" method on this class for
    74   * each instance of this class when the component is undeployed. The problem
    75   * occurs if:
    76   * <ul>
    77   * <li>the class containing a static instance of this class was loaded via
    78   * a shared classloader, and</li>
    79   * <li>the value stored in the instance is an object whose class was loaded
    80   * via the component-specific classloader (or any of the objects it refers
    81   * to were loaded via that classloader).</li>
    82   * </ul>
    83   * The result is that the map managed by this object still contains a strong
    84   * reference to the stored object, which contains a strong reference to the
    85   * classloader that loaded it, meaning that although the container has
    86   * "undeployed" the component the component-specific classloader and all the
    87   * related classes and static variables cannot be garbage-collected. This is
    88   * not expected to be an issue with the commons-beanutils library as the only
    89   * classes which use this class are BeanUtilsBean and ConvertUtilsBean and
    90   * there is no obvious reason for a user of the beanutils library to subclass
    91   * either of those classes.</p>
    92   *
    93   * <p><strong>Note:</strong> A WeakHashMap bug in several 1.3 JVMs results in
    94   * a memory leak for those JVMs.</p>
    95   *
    96   * <p><strong>Note:</strong> Of course all of this would be unnecessary if
    97   * containers required each component to load the full set of classes it
    98   * needs, ie avoided providing classes loaded via a "shared" classloader.</p>
    99   *
    100  * @see java.lang.Thread#getContextClassLoader
    101  * @author Eric Pabst
    102  */
    103 public class ContextClassLoaderLocal {
    104     private Map valueByClassLoader = new WeakHashMap();
    105     private boolean globalValueInitialized = false;
    106     private Object globalValue;
    107
    108     /***
    109      * Construct a context classloader instance
    110      */
    111     public ContextClassLoaderLocal() {
    112         super();
    113     }
    114
    115     /***
    116      * Returns the initial value for this ContextClassLoaderLocal
    117      * variable. This method will be called once per Context ClassLoader for
    118      * each ContextClassLoaderLocal, the first time it is accessed
    119      * with get or set.  If the programmer desires ContextClassLoaderLocal variables
    120      * to be initialized to some value other than null, ContextClassLoaderLocal must
    121      * be subclassed, and this method overridden.  Typically, an anonymous
    122      * inner class will be used.  Typical implementations of initialValue
    123      * will call an appropriate constructor and return the newly constructed
    124      * object.
    125      *
    126      * @return a new Object to be used as an initial value for this ContextClassLoaderLocal
    127      */
    128     protected Object initialValue() {
    129         return null;
    130     }
    131
    132     /***
    133      * Gets the instance which provides the functionality for {@link BeanUtils}.
    134      * This is a pseudo-singleton - an single instance is provided per (thread) context classloader.
    135      * This mechanism provides isolation for web apps deployed in the same container.
    136      * @return the object currently associated with the context-classloader of the current thread.
    137      */
    138     public synchronized Object get() {
    139         // synchronizing the whole method is a bit slower
    140         // but guarantees no subtle threading problems, and there's no
    141         // need to synchronize valueByClassLoader
    142
    143         // make sure that the map is given a change to purge itself
    144         valueByClassLoader.isEmpty();
    145         try {
    146
    147             ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    148             if (contextClassLoader != null) {
    149
    150                 Object value = valueByClassLoader.get(contextClassLoader);
    151                 if ((value == null)
    152                 && !valueByClassLoader.containsKey(contextClassLoader)) {
    153                     value = initialValue();
    154                     valueByClassLoader.put(contextClassLoader, value);
    155                 }
    156                 return value;
    157
    158             }
    159
    160         } catch (SecurityException e) { /* SWALLOW - should we log this? */ }
    161
    162         // if none or exception, return the globalValue
    163         if (!globalValueInitialized) {
    164             globalValue = initialValue();
    165             globalValueInitialized = true;
    166         }//else already set
    167         return globalValue;
    168     }
    169
    170     /***
    171      * Sets the value - a value is provided per (thread) context classloader.
    172      * This mechanism provides isolation for web apps deployed in the same container.
    173      *
    174      * @param value the object to be associated with the entrant thread's context classloader
    175      */
    176     public synchronized void set(Object value) {
    177         // synchronizing the whole method is a bit slower
    178         // but guarentees no subtle threading problems
    179
    180         // make sure that the map is given a change to purge itself
    181         valueByClassLoader.isEmpty();
    182         try {
    183
    184             ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    185             if (contextClassLoader != null) {
    186                 valueByClassLoader.put(contextClassLoader, value);
    187                 return;
    188             }
    189
    190         } catch (SecurityException e) { /* SWALLOW - should we log this? */ }
    191
    192         // if in doubt, set the global value
    193         globalValue = value;
    194         globalValueInitialized = true;
    195     }
    196
    197     /***
    198      * Unsets the value associated with the current thread's context classloader
    199      */
    200     public synchronized void unset() {
    201         try {
    202
    203             ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
    204             unset(contextClassLoader);
    205
    206         } catch (SecurityException e) { /* SWALLOW - should we log this? */ }
    207     }
    208
    209     /***
    210      * Unsets the value associated with the given classloader
    211      * @param classLoader The classloader to <i>unset</i> for
    212      */
    213     public synchronized void unset(ClassLoader classLoader) {
    214         valueByClassLoader.remove(classLoader);
    215     }
    216 }