    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&uuml;lc&uuml;
    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}