001/** 002 * Copyright (c) 2004-2011 QOS.ch 003 * All rights reserved. 004 * 005 * Permission is hereby granted, free of charge, to any person obtaining 006 * a copy of this software and associated documentation files (the 007 * "Software"), to deal in the Software without restriction, including 008 * without limitation the rights to use, copy, modify, merge, publish, 009 * distribute, sublicense, and/or sell copies of the Software, and to 010 * permit persons to whom the Software is furnished to do so, subject to 011 * the following conditions: 012 * 013 * The above copyright notice and this permission notice shall be 014 * included in all copies or substantial portions of the Software. 015 * 016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 017 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 018 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 021 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 023 * 024 */ 025package org.slf4j.spi; 026 027import java.util.Map; 028 029/** 030 * This interface abstracts the service offered by various MDC 031 * implementations. 032 * 033 * @author Ceki Gülcü 034 * @since 1.4.1 035 */ 036public interface MDCAdapter { 037 038 /** 039 * Put a context value (the <code>val</code> parameter) as identified with 040 * the <code>key</code> parameter into the current thread's context map. 041 * The <code>key</code> parameter cannot be null. The <code>val</code> parameter 042 * can be null only if the underlying implementation supports it. 043 * 044 * <p>If the current thread does not have a context map it is created as a side 045 * effect of this call. 046 */ 047 public void put(String key, String val); 048 049 /** 050 * Get the context identified by the <code>key</code> parameter. 051 * The <code>key</code> parameter cannot be null. 052 * 053 * @return the string value identified by the <code>key</code> parameter. 054 */ 055 public String get(String key); 056 057 /** 058 * Remove the the context identified by the <code>key</code> parameter. 059 * The <code>key</code> parameter cannot be null. 060 * 061 * <p> 062 * This method does nothing if there is no previous value 063 * associated with <code>key</code>. 064 */ 065 public void remove(String key); 066 067 /** 068 * Clear all entries in the MDC. 069 */ 070 public void clear(); 071 072 /** 073 * Return a copy of the current thread's context map, with keys and 074 * values of type String. Returned value may be null. 075 * 076 * @return A copy of the current thread's context map. May be null. 077 * @since 1.5.1 078 */ 079 public Map<String, String> getCopyOfContextMap(); 080 081 /** 082 * Set the current thread's context map by first clearing any existing 083 * map and then copying the map passed as parameter. The context map 084 * parameter must only contain keys and values of type String. 085 * 086 * @param contextMap must contain only keys and values of type String 087 * 088 * @since 1.5.1 089 */ 090 public void setContextMap(Map<String, String> contextMap); 091}