// Copyright(c) 1997 ObjectSpace, Inc.

package COM.objectspace.jgl;

import java.util.Dictionary;
import java.util.Enumeration;

/**
 * Map is the abstract class that in implemented by all JGL maps.
 * <p>
 * This abstract class was deprecated because it wasn't deemed to give
 * enough value for the added complexity.  No functionality is lost from the
 * concrete classes as Map is effectively just an interface.
 * <p>
 * @deprecated
 * @see COM.objectspace.jgl.HashMap
 * @see COM.objectspace.jgl.OrderedMap
 * @version 2.0.2
 * @author ObjectSpace, Inc.
 */

public abstract class Map extends Dictionary implements Container
  {
  /**
   * Return the number of key/value pairs that match a particular key.
   * @param key The key to match against.
   */
  public abstract int count( Object key );

  /**
   * Return the number of values that match a given object.
   * @param value The value to match against.
   */
  public abstract int countValues( Object value );

  /**
   * Return an Enumeration of all my keys that are associated with a particular value.
   * @param value The value to match.
   */
  public abstract Enumeration keys( Object value );

  /**
   * Return an Enumeration of all my values that are associated with a particular key.
   * @param key The key to match.
   */
  public abstract Enumeration values( Object key );

  //
  // The following methods are all from the Container interface.
  // They are listed here again to avoid a compiler bug.
  //

  /**
   * Return a shallow copy of myself.
   */
  public abstract Object clone();

  /**
   * Return a string that describes me.
   */
  public abstract String toString();

  /**
   * Return true if I'm equal to a specified object.
   * @param object The object to compare myself against.
   * @return true if I'm equal to the specified object.
   */
  public abstract boolean equals( Object object );

  /**
   * Return the number of objects that I contain.
   */
  public abstract int size();

  /**
   * Return the maximum number of objects that I can contain.
   */
  public abstract int maxSize();

  /**
   * Return true if I contain no objects.
   */
  public abstract boolean isEmpty();

  /**
   * Remove all of my objects.
   */
  public abstract void clear();

  /**
   * Return an Enumeration of the components in this container
   */
  public abstract Enumeration elements();

  /**
   * Return an iterator positioned at my first item.
   */
  public abstract ForwardIterator start();

  /**
   * Return an iterator positioned immediately after my last item.
   */
  public abstract ForwardIterator finish();

  /**
   * Add an object to myself. If appropriate, return the object that it replaced, otherwise
   * return null.
   */
  public abstract Object add( Object object );
  }