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) && 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) && 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}