home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / Dictionary.java < prev    next >
Text File  |  1998-09-22  |  4KB  |  120 lines
  1. /*
  2.  * @(#)Dictionary.java    1.8 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * The <code>Dictionary</code> class is the abstract parent of any 
  19.  * class, such as <code>Hashtable</code>, which maps keys to values. 
  20.  * Any non-<code>null</code> object can be used as a key and as a value.
  21.  * <p>
  22.  * As a rule, the <code>equals</code> method should be used by 
  23.  * implementations of this class to decide if two keys are the same. 
  24.  *
  25.  * @author  unascribed
  26.  * @version 1.8, 07/01/98
  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 {
  34.     /**
  35.      * Returns the number of keys in this dictionary.
  36.      *
  37.      * @return  the number of keys in this dictionary.
  38.      * @since   JDK1.0
  39.      */
  40.     abstract public int size();
  41.  
  42.     /**
  43.      * Tests if this dictionary maps no keys to value.
  44.      *
  45.      * @return  <code>true</code> if this dictionary maps no keys to values;
  46.      *          <code>false</code> otherwise.
  47.      * @since   JDK1.0
  48.      */
  49.     abstract public boolean isEmpty();
  50.  
  51.     /**
  52.      * Returns an enumeration of the keys in this dictionary.
  53.      *
  54.      * @return  an enumeration of the keys in this dictionary.
  55.      * @see     java.util.Dictionary#elements()
  56.      * @see     java.util.Enumeration
  57.      * @since   JDK1.0
  58.      */
  59.     abstract public Enumeration keys();
  60.  
  61.     /**
  62.      * Returns an enumeration of the values in this dictionary.
  63.      * the Enumeration methods on the returned object to fetch the elements
  64.      * sequentially.
  65.      *
  66.      * @return  an enumeration of the values in this dictionary.
  67.      * @see     java.util.Dictionary#keys()
  68.      * @see     java.util.Enumeration
  69.      * @since   JDK1.0
  70.      */
  71.     abstract public Enumeration elements();
  72.  
  73.     /**
  74.      * Returns the value to which the key is mapped in this dictionary.
  75.      *
  76.      * @return  the value to which the key is mapped in this dictionary;
  77.      * @param   key   a key in this dictionary.
  78.      *          <code>null</code> if the key is not mapped to any value in
  79.      *          this dictionary.
  80.      * @see     java.util.Dictionary#put(java.lang.Object, java.lang.Object)
  81.      * @since   JDK1.0
  82.      */
  83.     abstract public Object get(Object key);
  84.  
  85.     /**
  86.      * Maps the specified <code>key</code> to the specified 
  87.      * <code>value</code> in this dictionary. Neither the key nor the 
  88.      * value can be <code>null</code>.
  89.      * <p>
  90.      * The <code>value</code> can be retrieved by calling the 
  91.      * <code>get</code> method with a <code>key</code> that is equal to 
  92.      * the original <code>key</code>. 
  93.      *
  94.      * @param      key     the hashtable key.
  95.      * @param      value   the value.
  96.      * @return     the previous value to which the <code>key</code> was mapped
  97.      *             in this dictionary, or <code>null</code> if the key did not
  98.      *             have a previous mapping.
  99.      * @exception  NullPointerException  if the <code>key</code> or
  100.      *               <code>value</code> is <code>null</code>.
  101.      * @see        java.lang.Object#equals(java.lang.Object)
  102.      * @see        java.util.Dictionary#get(java.lang.Object)
  103.      * @since      JDK1.0
  104.      */
  105.     abstract public Object put(Object key, Object value);
  106.  
  107.     /**
  108.      * Removes the <code>key</code> (and its corresponding 
  109.      * <code>value</code>) from this dictionary. This method does nothing 
  110.      * if the <code>key</code> is not in this dictionary. 
  111.      *
  112.      * @param   key   the key that needs to be removed.
  113.      * @return  the value to which the <code>key</code> had been mapped in this
  114.      *          dictionary, or <code>null</code> if the key did not have a
  115.      *          mapping.
  116.      * @since   JDK1.0
  117.      */
  118.     abstract public Object remove(Object key);
  119. }
  120.