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 }