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 }