001/*
002 *  jDTAUS Core API
003 *  Copyright (C) 2005 Christian Schulte
004 *  <cs@schulte.it>
005 *
006 *  This library is free software; you can redistribute it and/or
007 *  modify it under the terms of the GNU Lesser General Public
008 *  License as published by the Free Software Foundation; either
009 *  version 2.1 of the License, or any later version.
010 *
011 *  This library is distributed in the hope that it will be useful,
012 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 *  Lesser General Public License for more details.
015 *
016 *  You should have received a copy of the GNU Lesser General Public
017 *  License along with this library; if not, write to the Free Software
018 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
019 *
020 */
021package org.jdtaus.core.container;
022
023import java.io.Serializable;
024import java.util.Collection;
025
026/**
027 * Object context.
028 * <p>The context stores key-value pairs bound to a client. For every method
029 * invocation identical clients get identical contexts.</p>
030 *
031 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
032 * @version $JDTAUS: Context.java 8641 2012-09-27 06:45:17Z schulte $
033 *
034 * @see ContextFactory
035 */
036public interface Context
037{
038    //--Context-----------------------------------------------------------------
039
040    /**
041     * Gets an attribute from the context.
042     *
043     * @param key Key of the attribute to return.
044     *
045     * @return The attribute with key {@code key} or {@code null} if no
046     * such attribute is held by the context. Returning {@code null} may also
047     * indicate that the context associated {@code null} with the specified key
048     * if the implementation supports {@code null} values.
049     *
050     * @throws NullPointerException if {@code key} is {@code null}.
051     * @deprecated Replaced by {@link #getObject(java.lang.String)}.
052     */
053     Object getAttribute( String key );
054
055    /**
056     * Sets an attribute in the context.
057     *
058     * @param key Key of the attribute to store {@code o} with.
059     * @param o Object to store with key {@code key}.
060     *
061     * @return The previous value associated with {@code key} or {@code null}
062     * if there was no attribute for {@code key}. Returning {@code null} may
063     * also indicate that the context previously associated {@code null} with
064     * the specified key if the implementation supports {@code null} values.
065     *
066     * @throws NullPointerException if {@code key} is {@code null}.
067     * @deprecated Replaced by {@link #setObject(java.lang.String, java.lang.Object)}.
068     */
069     Object setAttribute( String key, Serializable o );
070
071    /**
072     * Removes an attribute from the context.
073     *
074     * @param key Key of the attribute to remove.
075     *
076     * @return The previous value associated with {@code key} or {@code null}
077     * if there was no attribute for {@code key}. Returning {@code null} may
078     * also indicate that the context previously associated {@code null} with
079     * the specified key if the implementation supports {@code null} values.
080     *
081     * @throws NullPointerException if {@code key} is {@code null}.
082     * @deprecated Replaced by {@link #removeObject(java.lang.String)}.
083     */
084     Object removeAttribute( String key );
085
086    /**
087     * Gets a collection containing all object keys from the context.
088     *
089     * @return A collection containing all object keys from the context.
090     */
091    Collection getObjectKeys();
092
093    /**
094     * Gets an object from the context.
095     *
096     * @param key Key of the object to return.
097     *
098     * @return The object with key {@code key} or {@code null} if no
099     * such object is held by the context. Returning {@code null} may also
100     * indicate that the context associated {@code null} with the specified key
101     * if the implementation supports {@code null} values.
102     *
103     * @throws NullPointerException if {@code key} is {@code null}.
104     */
105    Object getObject( String key );
106
107    /**
108     * Sets an object in the context.
109     *
110     * @param key Key to store {@code o} with.
111     * @param o Object to store with key {@code key}.
112     *
113     * @return The previous value associated with {@code key} or {@code null}
114     * if there was no object for {@code key}. Returning {@code null} may
115     * also indicate that the context previously associated {@code null} with
116     * the specified key if the implementation supports {@code null} values.
117     *
118     * @throws NullPointerException if {@code key} is {@code null}.
119     */
120    Object setObject( String key, Object o );
121
122    /**
123     * Removes an object from the context.
124     *
125     * @param key Key of the object to remove.
126     *
127     * @return The previous value associated with {@code key} or {@code null}
128     * if there was no object for {@code key}. Returning {@code null} may
129     * also indicate that the context previously associated {@code null} with
130     * the specified key if the implementation supports {@code null} values.
131     *
132     * @throws NullPointerException if {@code key} is {@code null}.
133     */
134    Object removeObject( String key );
135
136    //-----------------------------------------------------------------Context--
137}