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 <a href="http://mina.apache.org">Apache MINA Project</a>
    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 }