1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util;
19
20/**
21 * <strong>Note: Do not use this class since it is obsolete. Please use the
22 * {@link Map} interface for new implementations.</strong>
23 * <p>
24 * Dictionary is an abstract class which is the superclass of all classes that
25 * associate keys with values, such as {@code Hashtable}.
26 *
27 * @see Hashtable
28 * @since 1.0
29 */
30public abstract class Dictionary<K, V> {
31    /**
32     * Constructs a new instance of this class.
33     */
34    public Dictionary() {
35    }
36
37    /**
38     * Returns an enumeration on the elements of this dictionary.
39     *
40     * @return an enumeration of the values of this dictionary.
41     * @see #keys
42     * @see #size
43     * @see Enumeration
44     */
45    public abstract Enumeration<V> elements();
46
47    /**
48     * Returns the value which is associated with {@code key}.
49     *
50     * @param key
51     *            the key of the value returned.
52     * @return the value associated with {@code key}, or {@code null} if the
53     *         specified key does not exist.
54     * @see #put
55     */
56    public abstract V get(Object key);
57
58    /**
59     * Returns true if this dictionary has no key/value pairs.
60     *
61     * @return {@code true} if this dictionary has no key/value pairs,
62     *         {@code false} otherwise.
63     * @see #size
64     */
65    public abstract boolean isEmpty();
66
67    /**
68     * Returns an enumeration on the keys of this dictionary.
69     *
70     * @return an enumeration of the keys of this dictionary.
71     * @see #elements
72     * @see #size
73     * @see Enumeration
74     */
75    public abstract Enumeration<K> keys();
76
77    /**
78     * Associate {@code key} with {@code value} in this dictionary. If {@code
79     * key} exists in the dictionary before this call, the old value in the
80     * dictionary is replaced by {@code value}.
81     *
82     * @param key
83     *            the key to add.
84     * @param value
85     *            the value to add.
86     * @return the old value previously associated with {@code key} or {@code
87     *         null} if {@code key} is new to the dictionary.
88     * @see #elements
89     * @see #get
90     * @see #keys
91     */
92    public abstract V put(K key, V value);
93
94    /**
95     * Removes the key/value pair with the specified {@code key} from this
96     * dictionary.
97     *
98     * @param key
99     *            the key to remove.
100     * @return the associated value before the deletion or {@code null} if
101     *         {@code key} was not known to this dictionary.
102     * @see #get
103     * @see #put
104     */
105    public abstract V remove(Object key);
106
107    /**
108     * Returns the number of key/value pairs in this dictionary.
109     *
110     * @return the number of key/value pairs in this dictionary.
111     * @see #elements
112     * @see #keys
113     */
114    public abstract int size();
115}
116