ContextMap


1   /* 
2    * Copyright 1999-2004 The Apache Software Foundation
3    * Licensed  under the  Apache License,  Version 2.0  (the "License");
4    * you may not use  this file  except in  compliance with the License.
5    * You may obtain a copy of the License at 
6    * 
7    *   http://www.apache.org/licenses/LICENSE-2.0
8    * 
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed  under the  License is distributed on an "AS IS" BASIS,
11   * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
12   * implied.
13   * 
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.log;
18  
19  import java.io.Serializable  ;
20  import java.util.Hashtable  ;
21  
22  /**
23   * The ContextMap contains non-hierarchical context information
24   * relevant to a particular LogEvent. It may include information
25   * such as;
26   *
27   * <ul>
28   * <li>user      -&gt;fred</li>
29   * <li>hostname  -&gt;helm.realityforge.org</li>
30   * <li>ipaddress -&gt;1.2.3.4</li>
31   * <li>interface -&gt;127.0.0.1</li>
32   * <li>caller � �-&gt;com.biz.MyCaller.method(MyCaller.java:18)</li>
33   * <li>source � �-&gt;1.6.3.2:33</li>
34   * </ul>
35   * The context is bound to a thread (and inherited by sub-threads) but
36   * it can also be added to by LogTargets.
37   *
38   * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
39   * @author Peter Donald
40   */
41  public final class ContextMap
42      implements Serializable  
43  {
44      ///Thread local for holding instance of map associated with current thread
45      private static final ThreadLocal   c_localContext = new InheritableThreadLocal  ();
46  
47      private final ContextMap m_parent;
48  
49      ///Container to hold map of elements
50      private Hashtable   m_map = new Hashtable  ();
51  
52      ///Flag indicating whether this map should be readonly
53      private transient boolean m_readOnly;
54  
55      /**
56       * Get the Current ContextMap.
57       * This method returns a ContextMap associated with current thread. If the
58       * thread doesn't have a ContextMap associated with it then a new
59       * ContextMap is created.
60       *
61       * @return the current ContextMap
62       */
63      public static final ContextMap getCurrentContext()
64      {
65          return getCurrentContext( true );
66      }
67  
68      /**
69       * Get the Current ContextMap.
70       * This method returns a ContextMap associated with current thread.
71       * If the thread doesn't have a ContextMap associated with it and
72       * autocreate is true then a new ContextMap is created.
73       *
74       * @param autocreate true if a ContextMap is to be created if it doesn't exist
75       * @return the current ContextMap
76       */
77      public static final ContextMap getCurrentContext( final boolean autocreate )
78      {
79          //Check security permission here???
80          ContextMap context = (ContextMap)c_localContext.get();
81  
82          if( null == context && autocreate )
83          {
84              context = new ContextMap();
85              c_localContext.set( context );
86          }
87  
88          return context;
89      }
90  
91      /**
92       * Bind a particular ContextMap to current thread.
93       *
94       * @param context the context map (may be null)
95       */
96      public static final void bind( final ContextMap context )
97      {
98          //Check security permission here??
99          c_localContext.set( context );
100     }
101 
102     /**
103      * Default constructor.
104      */
105     public ContextMap()
106     {
107         this( null );
108     }
109 
110     /**
111      * Constructor that sets parent contextMap.
112      *
113      * @param parent the parent ContextMap
114      */
115     public ContextMap( final ContextMap parent )
116     {
117         m_parent = parent;
118     }
119 
120     /**
121      * Make the context read-only.
122      * This makes it safe to allow untrusted code reference
123      * to ContextMap.
124      */
125     public void makeReadOnly()
126     {
127         m_readOnly = true;
128     }
129 
130     /**
131      * Determine if context is read-only.
132      *
133      * @return true if Context is read only, false otherwise
134      */
135     public boolean isReadOnly()
136     {
137         return m_readOnly;
138     }
139 
140     /**
141      * Empty the context map.
142      *
143      */
144     public void clear()
145     {
146         checkReadable();
147 
148         m_map.clear();
149     }
150 
151     /**
152      * Get an entry from the context.
153      *
154      * @param key the key to map
155      * @param defaultObject a default object to return if key does not exist
156      * @return the object in context
157      */
158     public Object   get( final String   key, final Object   defaultObject )
159     {
160         final Object   object = get( key );
161 
162         if( null != object )
163         {
164             return object;
165         }
166         else
167         {
168             return defaultObject;
169         }
170     }
171 
172     /**
173      * Get an entry from the context.
174      *
175      * @param key the key to map
176      * @return the object in context or null if none with specified key
177      */
178     public Object   get( final String   key )
179     {
180         if( key == null )
181             return null;
182             
183         final Object   result = m_map.get( key );
184 
185         if( null == result && null != m_parent )
186         {
187             return m_parent.get( key );
188         }
189 
190         return result;
191     }
192 
193     /**
194      * Set a value in context
195      *
196      * @param key the key
197      * @param value the value (may be null)
198      */
199     public void set( final String   key, final Object   value )
200     {
201         checkReadable();
202 
203         if( value == null )
204         {
205             m_map.remove( key );
206         }
207         else
208         {
209             m_map.put( key, value );
210         }
211     }
212 
213     /**
214      * Retrieve keys of entries into context map.
215      *
216      * @return the keys of items in context
217      */
218     /*
219     public String[] getKeys()
220     {
221         return (String[])m_map.keySet().toArray( new String[ 0 ] );
222     }
223     */
224 
225     /**
226      * Get the number of contexts in map.
227      *
228      * @return the number of contexts in map
229      */
230     public int getSize()
231     {
232         return m_map.size();
233     }
234 
235     /**
236      * Helper method that sets context to read-only after de-serialization.
237      *
238      * @return the corrected object version
239      */
240     private Object   readResolve()
241     {
242         makeReadOnly();
243         return this;
244     }
245 
246     /**
247      * Utility method to verify that Context is read-only.
248      */
249     private void checkReadable()
250     {
251         if( isReadOnly() )
252         {
253             throw new IllegalStateException  ( "ContextMap is read only and can not be modified" );
254         }
255     }
256 }
257
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags