001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.core.session;
021
022import java.util.Set;
023
024/**
025 * Stores the user-defined attributes which is provided per {@link IoSession}.
026 * All user-defined attribute accesses in {@link IoSession} are forwarded to
027 * the instance of {@link IoSessionAttributeMap}. 
028 * 
029 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
030 */
031public interface IoSessionAttributeMap {
032
033    /**
034     * @return the value of user defined attribute associated with the
035     * specified key.  If there's no such attribute, the specified default
036     * value is associated with the specified key, and the default value is
037     * returned.  This method is same with the following code except that the
038     * operation is performed atomically.
039     * <pre>
040     * if (containsAttribute(key)) {
041     *     return getAttribute(key);
042     * } else {
043     *     setAttribute(key, defaultValue);
044     *     return defaultValue;
045     * }
046     * </pre>
047     * 
048     * @param session the session for which we want to get an attribute
049     * @param key The key we are looking for
050     * @param defaultValue The default returned value if the attribute is not found
051     */
052    Object getAttribute(IoSession session, Object key, Object defaultValue);
053
054    /**
055     * Sets a user-defined attribute.
056     *
057     * @param session the session for which we want to set an attribute
058     * @param key the key of the attribute
059     * @param value the value of the attribute
060     * @return The old value of the attribute.  <tt>null</tt> if it is new.
061     */
062    Object setAttribute(IoSession session, Object key, Object value);
063
064    /**
065     * Sets a user defined attribute if the attribute with the specified key
066     * is not set yet.  This method is same with the following code except
067     * that the operation is performed atomically.
068     * <pre>
069     * if (containsAttribute(key)) {
070     *     return getAttribute(key);
071     * } else {
072     *     return setAttribute(key, value);
073     * }
074     * </pre>
075     * 
076     * @param session the session for which we want to set an attribute
077     * @param key The key we are looking for
078     * @param value The value to inject
079     * @return The previous attribute
080     */
081    Object setAttributeIfAbsent(IoSession session, Object key, Object value);
082
083    /**
084     * Removes a user-defined attribute with the specified key.
085     *
086     * @return The old value of the attribute.  <tt>null</tt> if not found.
087     * @param session the session for which we want to remove an attribute
088     * @param key The key we are looking for
089     */
090    Object removeAttribute(IoSession session, Object key);
091
092    /**
093     * Removes a user defined attribute with the specified key if the current
094     * attribute value is equal to the specified value.  This method is same
095     * with the following code except that the operation is performed
096     * atomically.
097     * <pre>
098     * if (containsAttribute(key) &amp;&amp; getAttribute(key).equals(value)) {
099     *     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}