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