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 <a href="http://mina.apache.org">Apache MINA Project</a>
30 */
31 public interface IoSessionAttributeMap {
32 /**
33 * @return the value of user defined attribute associated with the
34 * specified key. If there's no such attribute, the specified default
35 * value is associated with the specified key, and the default value is
36 * returned. This method is same with the following code except that the
37 * operation is performed atomically.
38 * <pre>
39 * if (containsAttribute(key)) {
40 * return getAttribute(key);
41 * } else {
42 * setAttribute(key, defaultValue);
43 * return defaultValue;
44 * }
45 * </pre>
46 *
47 * @param session the session for which we want to get an attribute
48 * @param key The key we are looking for
49 * @param defaultValue The default returned value if the attribute is not found
50 */
51 Object getAttribute(IoSession session, Object key, Object defaultValue);
52
53 /**
54 * Sets a user-defined attribute.
55 *
56 * @param session the session for which we want to set an attribute
57 * @param key the key of the attribute
58 * @param value the value of the attribute
59 * @return The old value of the attribute. <tt>null</tt> if it is new.
60 */
61 Object setAttribute(IoSession session, Object key, Object value);
62
63 /**
64 * Sets a user defined attribute if the attribute with the specified key
65 * is not set yet. This method is same with the following code except
66 * that the operation is performed atomically.
67 * <pre>
68 * if (containsAttribute(key)) {
69 * return getAttribute(key);
70 * } else {
71 * return setAttribute(key, value);
72 * }
73 * </pre>
74 *
75 * @param session the session for which we want to set an attribute
76 * @param key The key we are looking for
77 * @param value The value to inject
78 * @return The previous attribute
79 */
80 Object setAttributeIfAbsent(IoSession session, Object key, Object value);
81
82 /**
83 * Removes a user-defined attribute with the specified key.
84 *
85 * @return The old value of the attribute. <tt>null</tt> if not found.
86 * @param session the session for which we want to remove an attribute
87 * @param key The key we are looking for
88 */
89 Object removeAttribute(IoSession session, Object key);
90
91 /**
92 * Removes a user defined attribute with the specified key if the current
93 * attribute value is equal to the specified value. This method is same
94 * with the following code except that the operation is performed
95 * atomically.
96 * <pre>
97 * if (containsAttribute(key) && getAttribute(key).equals(value)) {
98 * removeAttribute(key);
99 * return true;
100 * } else {
101 * return false;
102 * }
103 * </pre>
104 *
105 * @param session the session for which we want to remove a value
106 * @param key The key we are looking for
107 * @param value The value to remove
108 * @return <tt>true</tt> if the value has been removed, <tt>false</tt> if the key was
109 * not found of the value not removed
110 */
111 boolean removeAttribute(IoSession session, Object key, Object value);
112
113 /**
114 * Replaces a user defined attribute with the specified key if the
115 * value of the attribute is equals to the specified old value.
116 * This method is same with the following code except that the operation
117 * is performed atomically.
118 * <pre>
119 * if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
120 * setAttribute(key, newValue);
121 * return true;
122 * } else {
123 * return false;
124 * }
125 * </pre>
126 *
127 * @param session the session for which we want to replace an attribute
128 * @param key The key we are looking for
129 * @param oldValue The old value to replace
130 * @param newValue The new value to set
131 * @return <tt>true</tt> if the value has been replaced, <tt>false</tt> if the key was
132 * not found of the value not replaced
133 */
134 boolean replaceAttribute(IoSession session, Object key, Object oldValue, Object newValue);
135
136 /**
137 * @return <tt>true</tt> if this session contains the attribute with
138 * the specified <tt>key</tt>.
139 *
140 * @param session the session for which wa want to check if an attribute is present
141 * @param key The key we are looking for
142 */
143 boolean containsAttribute(IoSession session, Object key);
144
145 /**
146 * @return the set of keys of all user-defined attributes.
147 *
148 * @param session the session for which we want the set of attributes
149 */
150 Set<Object> getAttributeKeys(IoSession session);
151
152 /**
153 * Disposes any releases associated with the specified session.
154 * This method is invoked on disconnection.
155 *
156 * @param session the session to be disposed
157 * @throws Exception If the session can't be disposed
158 */
159 void dispose(IoSession session) throws Exception;
160 }