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 /**
34 * Returns the value of user defined attribute associated with the
35 * specified key. If there's no such attribute, the specified default
36 * value is associated with the specified key, and the default value is
37 * returned. This method is same with the following code except that the
38 * operation is performed atomically.
39 * <pre>
40 * if (containsAttribute(key)) {
41 * return getAttribute(key);
42 * } else {
43 * setAttribute(key, defaultValue);
44 * return defaultValue;
45 * }
46 * </pre>
47 */
48 Object getAttribute(IoSession session, Object key, Object defaultValue);
49
50 /**
51 * Sets a user-defined attribute.
52 *
53 * @param key the key of the attribute
54 * @param value the value of the attribute
55 * @return The old value of the attribute. <tt>null</tt> if it is new.
56 */
57 Object setAttribute(IoSession session, Object key, Object value);
58
59 /**
60 * Sets a user defined attribute if the attribute with the specified key
61 * is not set yet. This method is same with the following code except
62 * that the operation is performed atomically.
63 * <pre>
64 * if (containsAttribute(key)) {
65 * return getAttribute(key);
66 * } else {
67 * return setAttribute(key, value);
68 * }
69 * </pre>
70 */
71 Object setAttributeIfAbsent(IoSession session, Object key, Object value);
72
73 /**
74 * Removes a user-defined attribute with the specified key.
75 *
76 * @return The old value of the attribute. <tt>null</tt> if not found.
77 */
78 Object removeAttribute(IoSession session, Object key);
79
80 /**
81 * Removes a user defined attribute with the specified key if the current
82 * attribute value is equal to the specified value. This method is same
83 * with the following code except that the operation is performed
84 * atomically.
85 * <pre>
86 * if (containsAttribute(key) && getAttribute(key).equals(value)) {
87 * removeAttribute(key);
88 * return true;
89 * } else {
90 * return false;
91 * }
92 * </pre>
93 */
94 boolean removeAttribute(IoSession session, Object key, Object value);
95
96 /**
97 * Replaces a user defined attribute with the specified key if the
98 * value of the attribute is equals to the specified old value.
99 * This method is same with the following code except that the operation
100 * is performed atomically.
101 * <pre>
102 * if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
103 * setAttribute(key, newValue);
104 * return true;
105 * } else {
106 * return false;
107 * }
108 * </pre>
109 */
110 boolean replaceAttribute(IoSession session, Object key, Object oldValue, Object newValue);
111
112 /**
113 * Returns <tt>true</tt> if this session contains the attribute with
114 * the specified <tt>key</tt>.
115 */
116 boolean containsAttribute(IoSession session, Object key);
117
118 /**
119 * Returns the set of keys of all user-defined attributes.
120 */
121 Set<Object> getAttributeKeys(IoSession session);
122
123 /**
124 * Disposes any releases associated with the specified session.
125 * This method is invoked on disconnection.
126 */
127 void dispose(IoSession session) throws Exception;
128 }