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 }