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: */
020: package org.apache.mina.common;
021:
022: import 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 The Apache MINA Project (dev@mina.apache.org)
030: * @version $Rev: 601679 $, $Date: 2007-12-06 03:13:21 -0700 (Thu, 06 Dec 2007) $
031: */
032: public interface IoSessionAttributeMap {
033:
034: /**
035: * Returns the value of user defined attribute associated with the
036: * specified key. If there's no such attribute, the specified default
037: * value is associated with the specified key, and the default value is
038: * returned. This method is same with the following code except that the
039: * operation is performed atomically.
040: * <pre>
041: * if (containsAttribute(key)) {
042: * return getAttribute(key);
043: * } else {
044: * setAttribute(key, defaultValue);
045: * return defaultValue;
046: * }
047: * </pre>
048: */
049: Object getAttribute(IoSession session, Object key,
050: Object defaultValue);
051:
052: /**
053: * Sets a user-defined attribute.
054: *
055: * @param key the key of the attribute
056: * @param value the value of the attribute
057: * @return The old value of the attribute. <tt>null</tt> if it is new.
058: */
059: Object setAttribute(IoSession session, Object key, Object value);
060:
061: /**
062: * Sets a user defined attribute if the attribute with the specified key
063: * is not set yet. This method is same with the following code except
064: * that the operation is performed atomically.
065: * <pre>
066: * if (containsAttribute(key)) {
067: * return getAttribute(key);
068: * } else {
069: * return setAttribute(key, value);
070: * }
071: * </pre>
072: */
073: Object setAttributeIfAbsent(IoSession session, Object key,
074: Object value);
075:
076: /**
077: * Removes a user-defined attribute with the specified key.
078: *
079: * @return The old value of the attribute. <tt>null</tt> if not found.
080: */
081: Object removeAttribute(IoSession session, Object key);
082:
083: /**
084: * Removes a user defined attribute with the specified key if the current
085: * attribute value is equal to the specified value. This method is same
086: * with the following code except that the operation is performed
087: * atomically.
088: * <pre>
089: * if (containsAttribute(key) && getAttribute(key).equals(value)) {
090: * removeAttribute(key);
091: * return true;
092: * } else {
093: * return false;
094: * }
095: * </pre>
096: */
097: boolean removeAttribute(IoSession session, Object key, Object value);
098:
099: /**
100: * Replaces a user defined attribute with the specified key if the
101: * value of the attribute is equals to the specified old value.
102: * This method is same with the following code except that the operation
103: * is performed atomically.
104: * <pre>
105: * if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
106: * setAttribute(key, newValue);
107: * return true;
108: * } else {
109: * return false;
110: * }
111: * </pre>
112: */
113: boolean replaceAttribute(IoSession session, Object key,
114: Object oldValue, Object newValue);
115:
116: /**
117: * Returns <tt>true</tt> if this session contains the attribute with
118: * the specified <tt>key</tt>.
119: */
120: boolean containsAttribute(IoSession session, Object key);
121:
122: /**
123: * Returns the set of keys of all user-defined attributes.
124: */
125: Set<Object> getAttributeKeys(IoSession session);
126:
127: /**
128: * Disposes any releases associated with the specified session.
129: * This method is invoked on disconnection.
130: */
131: void dispose(IoSession session) throws Exception;
132: }
|