KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > Dictionary


1 /*
2  * @(#)Dictionary.java 1.23 04/01/12
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.util;
9
10 /**
11  * The <code>Dictionary</code> class is the abstract parent of any
12  * class, such as <code>Hashtable</code>, which maps keys to values.
13  * Every key and every value is an object. In any one <tt>Dictionary</tt>
14  * object, every key is associated with at most one value. Given a
15  * <tt>Dictionary</tt> and a key, the associated element can be looked up.
16  * Any non-<code>null</code> object can be used as a key and as a value.
17  * <p>
18  * As a rule, the <code>equals</code> method should be used by
19  * implementations of this class to decide if two keys are the same.
20  * <p>
21  * <strong>NOTE: This class is obsolete. New implementations should
22  * implement the Map interface, rather than extending this class.</strong>
23  *
24  * @author unascribed
25  * @version 1.23, 01/12/04
26  * @see java.util.Map
27  * @see java.lang.Object#equals(java.lang.Object)
28  * @see java.lang.Object#hashCode()
29  * @see java.util.Hashtable
30  * @since JDK1.0
31  */
32 public abstract
33 class Dictionary<K,V> {
34     /**
35      * Sole constructor. (For invocation by subclass constructors, typically
36      * implicit.)
37      */
38     public Dictionary() {
39     }
40
41     /**
42      * Returns the number of entries (distinct keys) in this dictionary.
43      *
44      * @return the number of keys in this dictionary.
45      */
46     abstract public int size();
47
48     /**
49      * Tests if this dictionary maps no keys to value. The general contract
50      * for the <tt>isEmpty</tt> method is that the result is true if and only
51      * if this dictionary contains no entries.
52      *
53      * @return <code>true</code> if this dictionary maps no keys to values;
54      * <code>false</code> otherwise.
55      */
56     abstract public boolean isEmpty();
57
58     /**
59      * Returns an enumeration of the keys in this dictionary. The general
60      * contract for the keys method is that an <tt>Enumeration</tt> object
61      * is returned that will generate all the keys for which this dictionary
62      * contains entries.
63      *
64      * @return an enumeration of the keys in this dictionary.
65      * @see java.util.Dictionary#elements()
66      * @see java.util.Enumeration
67      */
68     abstract public Enumeration JavaDoc<K> keys();
69
70     /**
71      * Returns an enumeration of the values in this dictionary. The general
72      * contract for the <tt>elements</tt> method is that an
73      * <tt>Enumeration</tt> is returned that will generate all the elements
74      * contained in entries in this dictionary.
75      *
76      * @return an enumeration of the values in this dictionary.
77      * @see java.util.Dictionary#keys()
78      * @see java.util.Enumeration
79      */
80     abstract public Enumeration JavaDoc<V> elements();
81
82     /**
83      * Returns the value to which the key is mapped in this dictionary.
84      * The general contract for the <tt>isEmpty</tt> method is that if this
85      * dictionary contains an entry for the specified key, the associated
86      * value is returned; otherwise, <tt>null</tt> is returned.
87      *
88      * @return the value to which the key is mapped in this dictionary;
89      * @param key a key in this dictionary.
90      * <code>null</code> if the key is not mapped to any value in
91      * this dictionary.
92      * @exception NullPointerException if the <tt>key</tt> is <tt>null</tt>.
93      * @see java.util.Dictionary#put(java.lang.Object, java.lang.Object)
94      */
95     abstract public V get(Object JavaDoc key);
96
97     /**
98      * Maps the specified <code>key</code> to the specified
99      * <code>value</code> in this dictionary. Neither the key nor the
100      * value can be <code>null</code>.
101      * <p>
102      * If this dictionary already contains an entry for the specified
103      * <tt>key</tt>, the value already in this dictionary for that
104      * <tt>key</tt> is returned, after modifying the entry to contain the
105      * new element. <p>If this dictionary does not already have an entry
106      * for the specified <tt>key</tt>, an entry is created for the
107      * specified <tt>key</tt> and <tt>value</tt>, and <tt>null</tt> is
108      * returned.
109      * <p>
110      * The <code>value</code> can be retrieved by calling the
111      * <code>get</code> method with a <code>key</code> that is equal to
112      * the original <code>key</code>.
113      *
114      * @param key the hashtable key.
115      * @param value the value.
116      * @return the previous value to which the <code>key</code> was mapped
117      * in this dictionary, or <code>null</code> if the key did not
118      * have a previous mapping.
119      * @exception NullPointerException if the <code>key</code> or
120      * <code>value</code> is <code>null</code>.
121      * @see java.lang.Object#equals(java.lang.Object)
122      * @see java.util.Dictionary#get(java.lang.Object)
123      */
124     abstract public V put(K key, V value);
125
126     /**
127      * Removes the <code>key</code> (and its corresponding
128      * <code>value</code>) from this dictionary. This method does nothing
129      * if the <code>key</code> is not in this dictionary.
130      *
131      * @param key the key that needs to be removed.
132      * @return the value to which the <code>key</code> had been mapped in this
133      * dictionary, or <code>null</code> if the key did not have a
134      * mapping.
135      * @exception NullPointerException if <tt>key</tt> is <tt>null</tt>.
136      */
137     abstract public V remove(Object JavaDoc key);
138 }
139
Popular Tags