1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.mina.core.session;
21
22 import java.util.Set;
23
24 /**
25 * Stores the user-defined attributes which is provided per {@link IoSession}.
26 * All user-defined attribute accesses in {@link IoSession} are forwarded to
27 * the instance of {@link IoSessionAttributeMap}.
28 *
29 * @author The Apache MINA Project (dev@mina.apache.org)
30 * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
31 */
32 public interface IoSessionAttributeMap {
33
34 /**
35 * Returns the value of user defined attribute associated with the
36 * specified key. If there's no such attribute, the specified default
37 * value is associated with the specified key, and the default value is
38 * returned. This method is same with the following code except that the
39 * operation is performed atomically.
40 * <pre>
41 * if (containsAttribute(key)) {
42 * return getAttribute(key);
43 * } else {
44 * setAttribute(key, defaultValue);
45 * return defaultValue;
46 * }
47 * </pre>
48 */
49 Object getAttribute(IoSession session, Object key, Object defaultValue);
50
51 /**
52 * Sets a user-defined attribute.
53 *
54 * @param key the key of the attribute
55 * @param value the value of the attribute
56 * @return The old value of the attribute. <tt>null</tt> if it is new.
57 */
58 Object setAttribute(IoSession session, Object key, Object value);
59
60 /**
61 * Sets a user defined attribute if the attribute with the specified key
62 * is not set yet. This method is same with the following code except
63 * that the operation is performed atomically.
64 * <pre>
65 * if (containsAttribute(key)) {
66 * return getAttribute(key);
67 * } else {
68 * return setAttribute(key, value);
69 * }
70 * </pre>
71 */
72 Object setAttributeIfAbsent(IoSession session, Object key, Object value);
73
74 /**
75 * Removes a user-defined attribute with the specified key.
76 *
77 * @return The old value of the attribute. <tt>null</tt> if not found.
78 */
79 Object removeAttribute(IoSession session, Object key);
80
81 /**
82 * Removes a user defined attribute with the specified key if the current
83 * attribute value is equal to the specified value. This method is same
84 * with the following code except that the operation is performed
85 * atomically.
86 * <pre>
87 * if (containsAttribute(key) && getAttribute(key).equals(value)) {
88 * removeAttribute(key);
89 * return true;
90 * } else {
91 * return false;
92 * }
93 * </pre>
94 */
95 boolean removeAttribute(IoSession session, Object key, Object value);
96
97 /**
98 * Replaces a user defined attribute with the specified key if the
99 * value of the attribute is equals to the specified old value.
100 * This method is same with the following code except that the operation
101 * is performed atomically.
102 * <pre>
103 * if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
104 * setAttribute(key, newValue);
105 * return true;
106 * } else {
107 * return false;
108 * }
109 * </pre>
110 */
111 boolean replaceAttribute(IoSession session, Object key, Object oldValue, Object newValue);
112
113 /**
114 * Returns <tt>true</tt> if this session contains the attribute with
115 * the specified <tt>key</tt>.
116 */
117 boolean containsAttribute(IoSession session, Object key);
118
119 /**
120 * Returns the set of keys of all user-defined attributes.
121 */
122 Set<Object> getAttributeKeys(IoSession session);
123
124 /**
125 * Disposes any releases associated with the specified session.
126 * This method is invoked on disconnection.
127 */
128 void dispose(IoSession session) throws Exception;
129 }