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.session;
    21
    22  import java.util.Collections;
    23  import java.util.Set;
    24
    25  /**
    26   * An interface exposing the getters and setters on Attributes
    27   *
    28   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    29   */
    30  interface AttributeContainer {
    31      /**
    32       * Returns the value of the user-defined attribute for the given
    33       * <code>key</code>.
    34       *
    35       * @param key
    36       *            the attribute's key, must not be <code>null</code>
    37       * @return <tt>null</tt> if there is no attribute with the specified key
    38       * @exception IllegalArgumentException
    39       *                if <code>key==null</code>
    40       * @see #setAttribute(AttributeKey, Object)
    41       */
    42      <T> T getAttribute(AttributeKey<T> key);
    43
    44      /**
    45       * Returns the value of the user-defined attribute for the given
    46       * <code>key</code>.
    47       *
    48       * @param key
    49       *            the attribute's key, must not be <code>null</code>
    50       * @return <tt>null</tt> if there is no attribute with the specified key
    51       * @exception IllegalArgumentException
    52       *                if <code>key==null</code>
    53       * @see #setAttribute(AttributeKey, Object)
    54       */
    55      <T> T getAttribute(AttributeKey<T> key, T value);
    56
    57      /**
    58       * Removes the specified Attribute from this container. The old value will
    59       * be returned, <code>null</code> will be returned if there is no such
    60       * attribute in this container.<br>
    61       * <br>
    62       * This method is equivalent to <code>setAttribute(key,null)</code>.
    63       *
    64       * @param key
    65       *            of the attribute to be removed,must not be <code>null</code>
    66       * @return the removed value, <code>null</code> if this container doesn't
    67       *         contain the specified attribute
    68       * @exception IllegalArgumentException
    69       *                if <code>key==null</code>
    70       */
    71      <T> T removeAttribute(AttributeKey<T> key);
    72
    73      /**
    74       * Sets a user-defined attribute. If the <code>value</code> is
    75       * <code>null</code> the attribute will be removed from this container.
    76       *
    77       * @param key
    78       *            the attribute's key, must not be <code>null</code>
    79       * @param value
    80       *            the attribute's value, <code>null</code> to remove the
    81       *            attribute
    82       * @return The old attribute's value. <code>null</code> if there is no
    83       *         previous value or if the value is <code>null</code>
    84       * @exception IllegalArgumentException
    85       *                if {@code value!=null} and not an instance of type that is
    86       *                specified in the key (see {@link AttributeKey#getType()})
    87       *
    88       * @see #getAttribute(AttributeKey)
    89       */
    90      <T> T setAttribute(AttributeKey<? extends T> key, T value);
    91
    92      /**
    93       * Returns an unmodifiable {@link Set} including all Keys of this container. If
    94       * this container contains no key's an empty {@link Set} will be returned.
    95       *
    96       * @return all Keys, never <code>null</code>
    97       * @see Collections#unmodifiableSet(Set)
    98       */
    99      Set<AttributeKey<?>> getAttributeKeys();
    100 }