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