java.util.Dictionary Maven / Gradle / Ivy
/*
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below. For
example, no permission is given for you to incorporate this file, in
whole or in part, in an implementation of a Java specification.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative, as opposed to normative, use. The file and any
files generated from it may be used to generate other informative
documentation, such as a unified set of documents of API signatures for
a platform that includes technologies expressed as Java APIs. The file
may also be used to produce "compilation stubs," which allow
applications to be compiled and validated for such platforms.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 219: Foundation
Profile 1.1. In the event of a discrepency between this work and the
JSR 219 specification, which is available at
http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence.
*/
package java.util;
/**
* The Dictionary class is the abstract parent of any
* class, such as Hashtable, which maps keys to values.
* Every key and every value is an object. In any one Dictionary
* object, every key is associated with at most one value. Given a
* Dictionary and a key, the associated element can be looked up.
* Any non-null object can be used as a key and as a value.
*
* As a rule, the equals method should be used by
* implementations of this class to decide if two keys are the same.
*
* NOTE: This class is obsolete. New implementations should
* implement the Map interface, rather than extending this class.
*
* @author unascribed
* @version 1.15, 02/02/00
* @see java.util.Map
* @see java.lang.Object#equals(java.lang.Object)
* @see java.lang.Object#hashCode()
* @see java.util.Hashtable
* @since JDK1.0
*/
public abstract class Dictionary
{
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
public Dictionary() { }
/**
* Returns the number of entries (dinstint keys) in this dictionary.
*
* @return the number of keys in this dictionary.
*/
public abstract int size();
/**
* Tests if this dictionary maps no keys to value. The general contract
* for the isEmpty method is that the result is true if and only
* if this dictionary contains no entries.
*
* @return true if this dictionary maps no keys to values;
* false otherwise.
*/
public abstract boolean isEmpty();
/**
* Returns an enumeration of the keys in this dictionary. The general
* contract for the keys method is that an Enumeration object
* is returned that will generate all the keys for which this dictionary
* contains entries.
*
* @return an enumeration of the keys in this dictionary.
* @see java.util.Dictionary#elements()
* @see java.util.Enumeration
*/
public abstract Enumeration keys();
/**
* Returns an enumeration of the values in this dictionary. The general
* contract for the elements method is that an
* Enumeration is returned that will generate all the elements
* contained in entries in this dictionary.
*
* @return an enumeration of the values in this dictionary.
* @see java.util.Dictionary#keys()
* @see java.util.Enumeration
*/
public abstract Enumeration elements();
/**
* Returns the value to which the key is mapped in this dictionary.
* The general contract for the isEmpty method is that if this
* dictionary contains an entry for the specified key, the associated
* value is returned; otherwise, null is returned.
*
* @return the value to which the key is mapped in this dictionary;
* @param key a key in this dictionary.
* null if the key is not mapped to any value in
* this dictionary.
* @exception NullPointerException if the key is null.
* @see java.util.Dictionary#put(java.lang.Object, java.lang.Object)
*/
public abstract Object get(Object key);
/**
* Maps the specified key to the specified
* value in this dictionary. Neither the key nor the
* value can be null.
*
* If this dictionary already contains an entry for the specified
* key, the value already in this dictionary for that
* key is returned, after modifying the entry to contain the
* new element.
If this dictionary does not already have an entry
* for the specified key, an entry is created for the
* specified key and value, and null is
* returned.
*
* The value can be retrieved by calling the
* get method with a key that is equal to
* the original key.
*
* @param key the hashtable key.
* @param value the value.
* @return the previous value to which the key was mapped
* in this dictionary, or null if the key did not
* have a previous mapping.
* @exception NullPointerException if the key or
* value is null.
* @see java.lang.Object#equals(java.lang.Object)
* @see java.util.Dictionary#get(java.lang.Object)
*/
public abstract Object put(Object key, Object value);
/**
* Removes the key (and its corresponding
* value) from this dictionary. This method does nothing
* if the key is not in this dictionary.
*
* @param key the key that needs to be removed.
* @return the value to which the key had been mapped in this
* dictionary, or null if the key did not have a
* mapping.
* @exception NullPointerException if key is null.
*/
public abstract Object remove(Object key);
}