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 }