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 The Apache MINA Project (dev@mina.apache.org)
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 }