001: /* ====================================================================
002: * The Apache Software License, Version 1.1
003: *
004: * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
005: * reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The end-user documentation included with the redistribution,
020: * if any, must include the following acknowledgment:
021: * "This product includes software developed by the
022: * Apache Software Foundation (http://www.apache.org/)."
023: * Alternately, this acknowledgment may appear in the software
024: * itself, if and wherever such third-party acknowledgments
025: * normally appear.
026: *
027: * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
028: * must not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation. For more
052: * information on the Apache Software Foundation, please see
053: * <http://www.apache.org/>.
054: */
055: package org.apache.log;
056:
057: import java.io.ObjectStreamException;
058: import java.io.Serializable;
059: import java.util.Hashtable;
060:
061: /**
062: * The ContextMap contains non-hierarchical context information
063: * relevant to a particular LogEvent. It may include information
064: * such as;
065: *
066: * <ul>
067: * <li>user ->fred</li>
068: * <li>hostname ->helm.realityforge.org</li>
069: * <li>ipaddress ->1.2.3.4</li>
070: * <li>interface ->127.0.0.1</li>
071: * <li>caller ->com.biz.MyCaller.method(MyCaller.java:18)</li>
072: * <li>source ->1.6.3.2:33</li>
073: * </ul>
074: * The context is bound to a thread (and inherited by sub-threads) but
075: * it can also be added to by LogTargets.
076: *
077: * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
078: * @author <a href="mailto:peter@apache.org">Peter Donald</a>
079: */
080: public final class ContextMap implements Serializable {
081: ///Thread local for holding instance of map associated with current thread
082: private static final ThreadLocal LOCAL_CONTEXT = new InheritableThreadLocal();
083:
084: private final ContextMap m_parent;
085:
086: ///Container to hold map of elements
087: private Hashtable m_map = new Hashtable();
088:
089: ///Flag indicating whether this map should be readonly
090: private transient boolean m_readOnly;
091:
092: /**
093: * Get the Current ContextMap.
094: * This method returns a ContextMap associated with current thread. If the
095: * thread doesn't have a ContextMap associated with it then a new
096: * ContextMap is created.
097: *
098: * @return the current ContextMap
099: */
100: public static final ContextMap getCurrentContext() {
101: return getCurrentContext(true);
102: }
103:
104: /**
105: * Get the Current ContextMap.
106: * This method returns a ContextMap associated with current thread.
107: * If the thread doesn't have a ContextMap associated with it and
108: * autocreate is true then a new ContextMap is created.
109: *
110: * @param autocreate true if a ContextMap is to be created if it doesn't exist
111: * @return the current ContextMap
112: */
113: public static final ContextMap getCurrentContext(
114: final boolean autocreate) {
115: //Check security permission here???
116: ContextMap context = (ContextMap) LOCAL_CONTEXT.get();
117:
118: if (null == context && autocreate) {
119: context = new ContextMap();
120: LOCAL_CONTEXT.set(context);
121: }
122:
123: return context;
124: }
125:
126: /**
127: * Bind a particular ContextMap to current thread.
128: *
129: * @param context the context map (may be null)
130: */
131: public static final void bind(final ContextMap context) {
132: //Check security permission here??
133: LOCAL_CONTEXT.set(context);
134: }
135:
136: /**
137: * Default constructor.
138: */
139: public ContextMap() {
140: this (null);
141: }
142:
143: /**
144: * Constructor that sets parent contextMap.
145: *
146: * @param parent the parent ContextMap
147: */
148: public ContextMap(final ContextMap parent) {
149: m_parent = parent;
150: }
151:
152: /**
153: * Make the context read-only.
154: * This makes it safe to allow untrusted code reference
155: * to ContextMap.
156: */
157: public void makeReadOnly() {
158: m_readOnly = true;
159: }
160:
161: /**
162: * Determine if context is read-only.
163: *
164: * @return true if Context is read only, false otherwise
165: */
166: public boolean isReadOnly() {
167: return m_readOnly;
168: }
169:
170: /**
171: * Empty the context map.
172: *
173: */
174: public void clear() {
175: checkReadable();
176:
177: m_map.clear();
178: }
179:
180: /**
181: * Get an entry from the context.
182: *
183: * @param key the key to map
184: * @param defaultObject a default object to return if key does not exist
185: * @return the object in context
186: */
187: public Object get(final String key, final Object defaultObject) {
188: final Object object = get(key);
189:
190: if (null != object) {
191: return object;
192: } else {
193: return defaultObject;
194: }
195: }
196:
197: /**
198: * Get an entry from the context.
199: *
200: * @param key the key to map
201: * @return the object in context or null if none with specified key
202: */
203: public Object get(final String key) {
204: final Object result = m_map.get(key);
205:
206: if (null == result && null != m_parent) {
207: return m_parent.get(key);
208: }
209:
210: return result;
211: }
212:
213: /**
214: * Set a value in context
215: *
216: * @param key the key
217: * @param value the value (may be null)
218: */
219: public void set(final String key, final Object value) {
220: checkReadable();
221:
222: if (value == null) {
223: m_map.remove(key);
224: } else {
225: m_map.put(key, value);
226: }
227: }
228:
229: /**
230: * Retrieve keys of entries into context map.
231: *
232: * @return the keys of items in context
233: */
234: /*
235: public String[] getKeys()
236: {
237: return (String[])m_map.keySet().toArray( new String[ 0 ] );
238: }
239: */
240:
241: /**
242: * Get the number of contexts in map.
243: *
244: * @return the number of contexts in map
245: */
246: public int getSize() {
247: return m_map.size();
248: }
249:
250: /**
251: * Helper method that sets context to read-only after de-serialization.
252: *
253: * @return the corrected object version
254: * @exception ObjectStreamException if an error occurs
255: */
256: private Object readResolve() throws ObjectStreamException {
257: makeReadOnly();
258: return this ;
259: }
260:
261: /**
262: * Utility method to verify that Context is read-only.
263: */
264: private void checkReadable() {
265: if (isReadOnly()) {
266: throw new IllegalStateException(
267: "ContextMap is read only and can not be modified");
268: }
269: }
270: }
|