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