1 /*
2 * jDTAUS Core API
3 * Copyright (C) 2005 Christian Schulte
4 * <cs@schulte.it>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 *
20 */
21 package org.jdtaus.core.container;
22
23 import java.io.Serializable;
24 import java.util.Collection;
25
26 /**
27 * Object context.
28 * <p>The context stores key-value pairs bound to a client. For every method
29 * invocation identical clients get identical contexts.</p>
30 *
31 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
32 * @version $JDTAUS: Context.java 8641 2012-09-27 06:45:17Z schulte $
33 *
34 * @see ContextFactory
35 */
36 public interface Context
37 {
38 //--Context-----------------------------------------------------------------
39
40 /**
41 * Gets an attribute from the context.
42 *
43 * @param key Key of the attribute to return.
44 *
45 * @return The attribute with key {@code key} or {@code null} if no
46 * such attribute is held by the context. Returning {@code null} may also
47 * indicate that the context associated {@code null} with the specified key
48 * if the implementation supports {@code null} values.
49 *
50 * @throws NullPointerException if {@code key} is {@code null}.
51 * @deprecated Replaced by {@link #getObject(java.lang.String)}.
52 */
53 Object getAttribute( String key );
54
55 /**
56 * Sets an attribute in the context.
57 *
58 * @param key Key of the attribute to store {@code o} with.
59 * @param o Object to store with key {@code key}.
60 *
61 * @return The previous value associated with {@code key} or {@code null}
62 * if there was no attribute for {@code key}. Returning {@code null} may
63 * also indicate that the context previously associated {@code null} with
64 * the specified key if the implementation supports {@code null} values.
65 *
66 * @throws NullPointerException if {@code key} is {@code null}.
67 * @deprecated Replaced by {@link #setObject(java.lang.String, java.lang.Object)}.
68 */
69 Object setAttribute( String key, Serializable o );
70
71 /**
72 * Removes an attribute from the context.
73 *
74 * @param key Key of the attribute to remove.
75 *
76 * @return The previous value associated with {@code key} or {@code null}
77 * if there was no attribute for {@code key}. Returning {@code null} may
78 * also indicate that the context previously associated {@code null} with
79 * the specified key if the implementation supports {@code null} values.
80 *
81 * @throws NullPointerException if {@code key} is {@code null}.
82 * @deprecated Replaced by {@link #removeObject(java.lang.String)}.
83 */
84 Object removeAttribute( String key );
85
86 /**
87 * Gets a collection containing all object keys from the context.
88 *
89 * @return A collection containing all object keys from the context.
90 */
91 Collection getObjectKeys();
92
93 /**
94 * Gets an object from the context.
95 *
96 * @param key Key of the object to return.
97 *
98 * @return The object with key {@code key} or {@code null} if no
99 * 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 }