/*
 * Created on Jan 29, 2005
 *
 * Advanced Data Management Group
 * Center for Advanced Computing and Informatics Studies
 * University of Puerto Rico, Mayaguez
 * 
 */
package ece.uprm.admg.cs2.util;

/**
 * Interface Map specifies the methods that a class implementing the 
 * Map ADT must follow. The Map stores values by associating a key
 * with each value. Access to the value can then be obtained by passing 
 * the key as parameter to various methods in the ADT.
 * 
 * @author Manuel Rodriguez
 *
 */

public interface Map {
    /**
     * Returns the object that is associated with a given key.
     * @param key - the key of the value to search for.
     * @return the value associated with the given key, or null if no value is found.
     */
    public Object get(Object key);
    
    /**
     * Associates a object with a given key, and stores this information into the Map.
     * @param key - the key to be associated with the object value.
     * @param value - the object that needs to be stored in the Map.
     */
    public void put(Object key, Object value);
    
   /**
    * Removes the object associated with a given key from the Map.
    * @param key - the key of the object to be removed.
    * @return true if the object is removed, or false otherwise.
    */
    public boolean remove(Object key);
    
    /**
     * Determines if the Map contains an object that is associated with a key.
     * @param key - the key of the object to be searched.
     * @return true if there is an object in the Map associated with the key or false
     * otherwise.
     */
    public boolean containsKey(Object key);
    
    /**
     * Determines is the Map is empty or not.
     * @return true if the Map is empty, or false otherwise.
     */
    public boolean isEmpty();
    
    /**
     * Removes all elements from the Map. 
     */
    public void makeEmpty();
    
    /**
     * Returns the number of elements in the Map.
     * @return
     */
    public int size();   
    
    /**
     * Returns all the values stored in the map in an array of 
     * Object. If the Map is empty, the function returns null.
     * @return an array with the values stored in the Map,
     * or null if the Map is empty.
     */
    public Object[] toArray();
}
