home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / AbstractCollection.java next >
Encoding:
Java Source  |  1998-03-20  |  14.2 KB  |  395 lines
  1. /*
  2.  * @(#)AbstractCollection.java    1.9 98/03/18
  3.  *
  4.  * Copyright 1997, 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.  * This class provides a skeletal implementation of the Collection
  19.  * interface, to minimize the effort required to implement this interface.
  20.  * <p>
  21.  * To implement an unmodifiable Collection, the programmer needs only to
  22.  * extend this class and provide implementations for the iterator and size
  23.  * methods.  (The Iterator returned by the iterator method must implement
  24.  * hasNext and next.)
  25.  * <p>
  26.  * To implement a modifiable Collection, the programmer must additionally
  27.  * override this class's add method (which otherwise throws an
  28.  * UnsupportedOperationException), and the Iterator returned by the
  29.  * iterator method must additionally implement its remove method.
  30.  * <p>
  31.  * The programmer should generally provide a void (no argument) and
  32.  * Collection constructor, as per the recommendation in the Collection
  33.  * interface specification.
  34.  * <p>
  35.  * The documentation for each non-abstract methods in this class describes its
  36.  * implementation in detail.  Each of these methods may be overridden if
  37.  * the Collection being implemented admits a more efficient implementation.
  38.  *
  39.  * @author  Josh Bloch
  40.  * @version 1.9 03/18/98
  41.  * @see Collection
  42.  * @since JDK1.2
  43.  */
  44.  
  45. public abstract class AbstractCollection implements Collection {
  46.     // Query Operations
  47.  
  48.     /**
  49.      * Returns an Iterator over the elements contained in this Collection.
  50.      */
  51.     public abstract Iterator iterator();
  52.  
  53.     /**
  54.      * Returns the number of elements in this Collection.
  55.      */
  56.     public abstract int size();
  57.  
  58.     /**
  59.      * Returns true if this Collection contains no elements.
  60.      *
  61.      * This implementation returns <code>size() == 0</code>.
  62.      */
  63.     public boolean isEmpty() {
  64.     return size() == 0;
  65.     }
  66.  
  67.     /**
  68.      * Returns true if this Collection contains the specified element.  More
  69.      * formally, returns true if and only if this Collection contains at least
  70.      * one element <code>e</code> such that <code>(o==null ? e==null :
  71.      * o.equals(e))</code>.
  72.      * <p>
  73.      * This implementation iterates over the elements in the Collection,
  74.      * checking each element in turn for equality with o.
  75.      */
  76.     public boolean contains(Object o) {
  77.     Iterator e = iterator();
  78.     if (o==null) {
  79.         while (e.hasNext())
  80.         if (e.next()==null)
  81.             return true;
  82.     } else {
  83.         while (e.hasNext())
  84.         if (o.equals(e.next()))
  85.             return true;
  86.     }
  87.     return false;
  88.     }
  89.  
  90.     /**
  91.      * Returns an array containing all of the elements in this Collection.  If
  92.      * the Collection makes any guarantees as to what order its elements are
  93.      * returned by its Iterator, this method must return the elements in the
  94.      * same order.  The returned array will be "safe" in that no references to
  95.      * it are maintained by the Collection.  (In other words, this method must
  96.      * allocate a new array even if the Collection is backed by an Array).
  97.      * The caller is thus free to modify the returned array.
  98.      * <p>
  99.      * This implementation allocates the array to be returned, and iterates
  100.      * over the elements in the Collection, storing each object reference in
  101.      * the next consecutive element of the array, starting with element 0.
  102.      */
  103.     public Object[] toArray() {
  104.     Object[] result = new Object[size()];
  105.     Iterator e = iterator();
  106.     for (int i=0; e.hasNext(); i++)
  107.         result[i] = e.next();
  108.     return result;
  109.     }
  110.  
  111.     /**
  112.      * Returns an array containing all of the elements in this Collection,
  113.      * whose runtime type is that of the specified array.  If the Collection
  114.      * fits in the specified array, it is returned therein.  Otherwise,
  115.      * a new array is allocated with the runtime type of the specified array
  116.      * and the size of this Collection.
  117.      * <p>
  118.      * If the Collection fits in the specified array with room to spare
  119.      * (i.e., the array has more elements than the Collection), 
  120.      * the element in the array immediately following the end of the
  121.      * collection is set to null.  This is useful in determining the length
  122.      * of the Collection <em>only</em> if the caller knows that the Collection
  123.      * does not contain any null elements.)
  124.      * <p>
  125.      * If this Collection makes any guarantees as to what order its elements
  126.      * are returned by its Iterator, this method must return the elements in
  127.      * the same order. 
  128.      * <p>
  129.      * This implementation checks if the array is large enough to contain
  130.      * the Collection; if not, it allocates a new array of the correct
  131.      * size and type (using reflection).  Then, it iterates over the
  132.      * Collection, storing each object reference in the next consecutive
  133.      * element of the array, starting with element 0.  If the array is larger
  134.      * than the Collection, a null is stored in the first location after the
  135.      * end of the Collection.
  136.      *
  137.      * @param a the array into which the elements of the Collection are to
  138.      *        be stored, if it is big enough; otherwise, a new array of the
  139.      *         same runtime type is allocated for this purpose.
  140.      * @return an array containing the elements of the Collection.
  141.      * @exception NullPointerException The specified array, a, is null.
  142.      * @exception ArrayStoreException the runtime type of a is not a supertype
  143.      *          of the runtime type of every element in this Collection.
  144.      */
  145.     public Object[] toArray(Object a[]) {
  146.         int size = size();
  147.         if (a.length < size)
  148.             a = (Object[])java.lang.reflect.Array.newInstance(
  149.                                   a.getClass().getComponentType(), size);
  150.  
  151.         Iterator it=iterator();
  152.         for (int i=0; i<size; i++)
  153.             a[i] = it.next();
  154.  
  155.         if (a.length > size)
  156.             a[size] = null;
  157.  
  158.         return a;
  159.     }
  160.  
  161.     // Modification Operations
  162.  
  163.     /**
  164.      * Ensures that this Collection contains the specified element (optional
  165.      * operation).  Returns true if the Collection changed as a result of the
  166.      * call.  (Returns false if this Collection does not permit duplicates and
  167.      * already contains the specified element.)  Collections that support this
  168.      * operation may place limitations on what elements may be added to the
  169.      * Collection.  In particular, some Collections will refuse to add null
  170.      * elements, and others will impose restrictions on the type of elements
  171.      * that may be added.  Collection classes should clearly specify in their
  172.      * documentation any restrictions on what elements may be added.
  173.      * <p>
  174.      * This implementation always throws an UnsupportedOperationException.
  175.      *
  176.      * @param o element whose presence in this Collection is to be ensured.
  177.      * @return true if the Collection changed as a result of the call.
  178.      * @exception UnsupportedOperationException add is not supported by this
  179.      *          Collection.
  180.      * @exception NullPointerException this Collection does not permit null
  181.      *           elements, and the specified element is null.
  182.      * @exception ClassCastException class of the specified element
  183.      *           prevents it from being added to this Collection.
  184.      * @exception IllegalArgumentException some aspect of this element prevents
  185.      *          it from being added to this Collection.
  186.      */
  187.     public boolean add(Object o) {
  188.     throw new UnsupportedOperationException();
  189.     }
  190.  
  191.     /**
  192.      * Removes a single instance of the specified element from this Collection,
  193.      * if it is present (optional operation).  More formally, removes an
  194.      * element <code>e</code> such that <code>(o==null ? e==null :
  195.      * o.equals(e))</code>, if the Collection contains one or more such
  196.      * elements.  Returns true if the Collection contained the specified
  197.      * element (or equivalently, if the Collection changed as a result of the
  198.      * call).
  199.      * <p>
  200.      * This implementation iterates over the Collection looking for the
  201.      * specified element.  If it finds the element, it removes the element
  202.      * from the Collection using the iterator's remove method.
  203.      * <p>
  204.      * Note that this implementation will throw an
  205.      * UnsupportedOperationException if the Iterator returned by this
  206.      * Collection's iterator method does not implement the remove method.
  207.      *
  208.      * @param o element to be removed from this Collection, if present.
  209.      * @return true if the Collection contained the specified element.
  210.      * @exception UnsupportedOperationException remove is not supported
  211.      *           by this Collection.
  212.      */
  213.     public boolean remove(Object o) {
  214.     Iterator e = iterator();
  215.     if (o==null) {
  216.         while (e.hasNext()) {
  217.         if (e.next()==null) {
  218.             e.remove();
  219.             return true;
  220.         }
  221.         }
  222.     } else {
  223.         while (e.hasNext()) {
  224.         if (o.equals(e.next())) {
  225.             e.remove();
  226.             return true;
  227.         }
  228.         }
  229.     }
  230.     return false;
  231.     }
  232.  
  233.  
  234.     // Bulk Operations
  235.  
  236.     /**
  237.      * Returns true if this Collection contains all of the elements in the
  238.      * specified Collection.
  239.      * <p>
  240.      * This implementation iterates over the specified Collection, checking
  241.      * each element returned by the Iterator in turn to see if it's
  242.      * contained in this Collection.  If all elements are so contained
  243.      * true is returned, otherwise false.
  244.      *
  245.      * @see #contains(Object)
  246.      */
  247.     public boolean containsAll(Collection c) {
  248.     Iterator e = c.iterator();
  249.     while (e.hasNext())
  250.         if(!contains(e.next()))
  251.         return false;
  252.  
  253.     return true;
  254.     }
  255.  
  256.     /**
  257.      * Adds all of the elements in the specified Collection to this Collection
  258.      * (optional operation).  The behavior of this operation is undefined if
  259.      * the specified Collection is modified while the operation is in progress.
  260.      * (This implies that the behavior of this call is undefined if the the
  261.      * specified Collection is this Collection, and this Collection is
  262.      * nonempty.) 
  263.      * <p>
  264.      * This implementation iterates over the specified Collection,
  265.      * and adds each object returned by the Iterator to this Collection,
  266.      * in turn.
  267.      * <p>
  268.      * Note that this implementation will throw an
  269.      * UnsupportedOperationException unless add is overridden.
  270.      *
  271.      * @exception UnsupportedOperationException addAll is not supported
  272.      *           by this Collection.
  273.      * @see #add(Object)
  274.      */
  275.     public boolean addAll(Collection c) {
  276.     boolean modified = false;
  277.     Iterator e = c.iterator();
  278.     while (e.hasNext()) {
  279.         if(add(e.next()))
  280.         modified = true;
  281.     }
  282.     return modified;
  283.     }
  284.  
  285.     /**
  286.      * Removes from this Collection all of its elements that are contained in
  287.      * the specified Collection (optional operation).
  288.      * <p>
  289.      * This implementation iterates over this Collection, checking each
  290.      * element returned by the Iterator in turn to see if it's contained
  291.      * in the specified Collection.  If it's so contained, it's removed from
  292.      * this Collection with the Iterator's remove method.
  293.      * <p>
  294.      * Note that this implementation will throw an
  295.      * UnsupportedOperationException if the Iterator returned by
  296.      * iterator does not implement the remove method.
  297.      *
  298.      * @return true if this Collection changed as a result of the call.
  299.      * @exception UnsupportedOperationException removeAll is not supported
  300.      *           by this Collection.
  301.      * @see #remove(Object)
  302.      * @see #contains(Object)
  303.      */
  304.     public boolean removeAll(Collection c) {
  305.     boolean modified = false;
  306.     Iterator e = iterator();
  307.     while (e.hasNext()) {
  308.         if(c.contains(e.next())) {
  309.         e.remove();
  310.         modified = true;
  311.         }
  312.     }
  313.     return modified;
  314.     }
  315.  
  316.     /**
  317.      * Retains only the elements in this Collection that are contained in the
  318.      * specified Collection (optional operation).  In other words, removes from
  319.      * this Collection all of its elements that are not contained in the
  320.      * specified Collection. 
  321.      * <p>
  322.      * This implementation iterates over this Collection, checking each
  323.      * element returned by the Iterator in turn to see if it's contained
  324.      * in the specified Collection.  If it's not so contained, it's removed
  325.      * from this Collection with the Iterator's remove method.
  326.      * <p>
  327.      * Note that this implementation will throw an
  328.      * UnsupportedOperationException if the Iterator returned by
  329.      * iterator does not implement the remove method.
  330.      *
  331.      * @return true if this Collection changed as a result of the call.
  332.      * @exception UnsupportedOperationException retainAll is not supported
  333.      *           by this Collection.
  334.      * @see #remove(Object)
  335.      * @see #contains(Object)
  336.      */
  337.     public boolean retainAll(Collection c) {
  338.     boolean modified = false;
  339.     Iterator e = iterator();
  340.     while (e.hasNext()) {
  341.         if(!c.contains(e.next())) {
  342.         e.remove();
  343.         modified = true;
  344.         }
  345.     }
  346.     return modified;
  347.     }
  348.  
  349.     /**
  350.      * Removes all of the elements from this Collection (optional operation).
  351.      * The Collection will be empty after this call returns (unless it throws
  352.      * an exception).
  353.      * <p>
  354.      * This implementation iterates over this Collection, removing each
  355.      * element using the Iterator.remove operation.
  356.      * Most implementations will probably choose to override this method
  357.      * for efficiency.
  358.      * <p>
  359.      * Note that this implementation will throw an
  360.      * UnsupportedOperationException if the Iterator returned by this
  361.      * Collection's iterator method does not implement the remove method.
  362.      *
  363.      * @exception UnsupportedOperationException remove is not supported
  364.      *           by this Collection.
  365.      */
  366.     public void clear() {
  367.     Iterator e = iterator();
  368.     while (e.hasNext()) {
  369.         e.next();
  370.         e.remove();
  371.     }
  372.     }
  373.  
  374.  
  375.     //  String conversion
  376.  
  377.     /**
  378.      * Returns a string representation of this Collection, containing
  379.      * the String representation of each element.
  380.      */
  381.     public String toString() {
  382.     StringBuffer buf = new StringBuffer();
  383.     Iterator e = iterator();
  384.     buf.append("[");
  385.     int maxIndex = size() - 1;
  386.     for (int i = 0; i <= maxIndex; i++) {
  387.         buf.append(String.valueOf(e.next()));
  388.         if (i < maxIndex)
  389.         buf.append(", ");
  390.     }
  391.     buf.append("]");
  392.     return buf.toString();
  393.     }
  394. }
  395.