Add BoundedCollection, from Herve Quiroz

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130871 13f79535-47bb-0310-9956-ffa450edef68

STATUS.html

@@ -7,7 +7,7 @@
 
 <div align="center">
 <h1>The Jakarta Commons <em>Collections</em> Package</h1>
-$Id: STATUS.html,v 1.20 2002/11/21 23:09:57 scolebourne Exp $<br>
+$Id: STATUS.html,v 1.21 2002/11/24 16:23:20 scolebourne Exp $<br>
 <a href="#Introduction">[Introduction]</a>
 <a href="#Dependencies">[Dependencies]</a>
 <a href="#Release Info">[Release Info]</a>
@@ -40,6 +40,8 @@ The following classes are included:</p>
     keys of the map and the property values are the values of the map.</li>
 <li><strong>BinaryHeap</strong> - Binary heap implementation 
     of PriorityQueue and Buffer.</li>
+<li><strong>BoundedCollection</strong> - an interface used by collections that can 
+have a variable number of elements up to a fixed bound.</li>
 <li><strong>BoundedFifoBuffer</strong> - a very efficient implementation of 
     Buffer that does not alter the size of the buffer at runtime.</li>
 <li><strong>Buffer</strong> - a collection that allows objects to be removed 

src/java/org/apache/commons/collections/BoundedCollection.java

@@ -0,0 +1,89 @@
+/*
+ *
+ * ====================================================================
+ *
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2002 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Commons", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.commons.collections;
+
+import java.util.Collection;
+/**
+ * A BoundedCollection is a collection that is bounded in size.
+ * <p>
+ * The size of the collection can vary, but it can never exceed a preset 
+ * maximum number of elements. This interface allows the querying of details
+ * associated with the maximum number of elements.
+ *
+ * @since 2.2
+ * @author <a href="herve.quiroz@esil.univ-mrs.fr">Herve Quiroz</a>
+ * @author Stephen Colebourne
+ * @version $Id: BoundedCollection.java,v 1.1 2002/11/24 16:23:21 scolebourne Exp $
+ */
+public interface BoundedCollection extends Collection {
+
+    /**
+     * Returns true if this collection is full and no new elements can be added.
+     *
+     * @return <code>true</code> if the collection is full
+     */
+    boolean isFull();
+    
+    /**
+     * Gets the maximum size of the collection (the bound).
+     *
+     * @return the maximum number of elements the collection can hold
+     */
+    int maxSize();
+    
+}

src/java/org/apache/commons/collections/BoundedFifoBuffer.java

@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BoundedFifoBuffer.java,v 1.5 2002/10/13 12:59:04 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BoundedFifoBuffer.java,v 1.6 2002/11/24 16:23:21 scolebourne Exp $
- * $Revision: 1.5 $
+ * $Revision: 1.6 $
- * $Date: 2002/10/13 12:59:04 $
+ * $Date: 2002/11/24 16:23:21 $
  *
  * ====================================================================
  *
@@ -85,14 +85,15 @@ import java.util.NoSuchElementException;
  * <p>
  * This buffer prevents null objects from being added.
  *
+ * @since 2.1
  * @author Avalon
  * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  * @author Paul Jack
  * @author Stephen Colebourne
- * @since 2.1
+ * @author <a href="herve.quiroz@esil.univ-mrs.fr">Herve Quiroz</a>
- * @version $Id: BoundedFifoBuffer.java,v 1.5 2002/10/13 12:59:04 scolebourne Exp $
+ * @version $Id: BoundedFifoBuffer.java,v 1.6 2002/11/24 16:23:21 scolebourne Exp $
  */
-public class BoundedFifoBuffer extends AbstractCollection implements Buffer {
+public class BoundedFifoBuffer extends AbstractCollection implements Buffer, BoundedCollection {
     private final Object[] m_elements;
     private int m_start = 0;
     private int m_end = 0;
@@ -160,6 +161,24 @@ public class BoundedFifoBuffer extends AbstractCollection implements Buffer {
         return size() == 0;
     }
 
+    /**
+     * Returns true if this collection is full and no new elements can be added.
+     *
+     * @return <code>true</code> if the collection is full
+     */
+    public boolean isFull() {
+        return size() == m_elements.length;
+    }
+    
+    /**
+     * Gets the maximum size of the collection (the bound).
+     *
+     * @return the maximum number of elements the collection can hold
+     */
+    public int maxSize() {
+        return m_elements.length;
+    }
+    
     /**
      * Clears this buffer.
      */

src/java/org/apache/commons/collections/CollectionUtils.java

@@ -1,7 +1,7 @@
 /*
- * $Id: CollectionUtils.java,v 1.19 2002/11/01 19:54:26 rwaldhoff Exp $
+ * $Id: CollectionUtils.java,v 1.20 2002/11/24 16:23:21 scolebourne Exp $
- * $Revision: 1.19 $
+ * $Revision: 1.20 $
- * $Date: 2002/11/01 19:54:26 $
+ * $Date: 2002/11/24 16:23:21 $
  *
  * ====================================================================
  *
@@ -58,7 +58,6 @@
  * <http://www.apache.org/>.
  *
  */
-
 package org.apache.commons.collections;
 
 import java.util.ArrayList;
@@ -75,7 +74,6 @@ import java.util.Set;
 
 import org.apache.commons.collections.iterators.ArrayIterator;
 import org.apache.commons.collections.iterators.EnumerationIterator;
-
 /**
  * A set of {@link Collection} related utility methods.
  *
@@ -84,7 +82,8 @@ import org.apache.commons.collections.iterators.EnumerationIterator;
  * @author Paul Jack
  * @author Stephen Colebourne
  * @author Steve Downey
- * @version $Revision: 1.19 $ $Date: 2002/11/01 19:54:26 $
+ * @author <a href="herve.quiroz@esil.univ-mrs.fr">Herve Quiroz</a>
+ * @version $Revision: 1.20 $ $Date: 2002/11/24 16:23:21 $
  */
 public class CollectionUtils {
 
@@ -706,13 +705,17 @@ public class CollectionUtils {
     }
 
 
-    /** Reverses the order of the given array */
+    /** 
+     * Reverses the order of the given array 
+     * 
+     * @param array  the array to reverse
+     */
     public static void reverseArray(Object[] array) {
         int i = 0;
         int j = array.length - 1;
         Object tmp;
-        
+
-        while(j>i) {
+        while (j > i) {
             tmp = array[j];
             array[j] = array[i];
             array[i] = tmp;
@@ -732,6 +735,80 @@ public class CollectionUtils {
         return 0;
     }
 
+    /**
+     * Returns true if no more elements can be added to the Collection.
+     * <p>
+     * This method uses the {@link BoundedCollection} class to determine the
+     * full status. If the collection does not implement this interface then
+     * false is returned.
+     * <p>
+     * This method handles the synchronized, blocking, unmodifiable 
+     * and predicated decorators.
+     *
+     * @return  true if the Collection is full
+     * @throws NullPointerException if the collection is null
+     */
+    public static boolean isFull(Collection coll) {
+        if (coll == null) {
+            throw new NullPointerException("The collection must not be null");
+        }
+        Collection unwrappedCollection = coll;
+        
+        // handle decorators
+        while (true) {
+            if (unwrappedCollection instanceof CollectionUtils.CollectionWrapper) {
+                unwrappedCollection = ((CollectionUtils.CollectionWrapper) unwrappedCollection).collection;
+            } else if (unwrappedCollection instanceof CollectionUtils.SynchronizedCollection) {
+                unwrappedCollection = ((CollectionUtils.SynchronizedCollection) unwrappedCollection).collection;
+            } else {
+                break;
+            }
+        }
+        
+        // is it full
+        if (unwrappedCollection instanceof BoundedCollection) {
+            return ((BoundedCollection) unwrappedCollection).isFull();
+        }
+        return false;
+    }
+
+    /**
+     * Get the maximum number of elements that the Collection can contain.
+     * <p>
+     * This method uses the {@link BoundedCollection} class to determine the
+     * maximum size. If the collection does not implement this interface then
+     * -1 is returned.
+     * <p>
+     * This method handles the synchronized, blocking, unmodifiable 
+     * and predicated decorators.
+     *
+     * @return the maximum size of the Collection, -1 if no maximum size
+     * @throws NullPointerException if the collection is null
+     */
+    public static int maxSize(Collection coll) {
+        if (coll == null) {
+            throw new NullPointerException("The collection must not be null");
+        }
+        Collection unwrappedCollection = coll;
+        
+        // handle decorators
+        while (true) {
+            if (unwrappedCollection instanceof CollectionUtils.CollectionWrapper) {
+                unwrappedCollection = ((CollectionUtils.CollectionWrapper) unwrappedCollection).collection;
+            } else if (unwrappedCollection instanceof CollectionUtils.SynchronizedCollection) {
+                unwrappedCollection = ((CollectionUtils.SynchronizedCollection) unwrappedCollection).collection;
+            } else {
+                break;
+            }
+        }
+        
+        // get max size
+        if (unwrappedCollection instanceof BoundedCollection) {
+            return ((BoundedCollection) unwrappedCollection).maxSize();
+        }
+        return -1;
+    }
+
     /**
      * Base class for collection decorators.  I decided to do it this way
      * because it seemed to result in the most reuse.  

src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java

@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java,v 1.3 2002/10/12 22:36:21 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java,v 1.4 2002/11/24 16:23:21 scolebourne Exp $
- * $Revision: 1.3 $
+ * $Revision: 1.4 $
- * $Date: 2002/10/12 22:36:21 $
+ * $Date: 2002/11/24 16:23:21 $
  *
  * ====================================================================
  *
@@ -134,5 +134,29 @@ public class TestBoundedFifoBuffer2 extends TestBoundedFifoBuffer {
         verify();
     }
 
+    /**
+     * Tests is full
+     */
+    public void testIsFull() {
+        resetFull();
+        assertEquals(true, ((BoundedCollection) collection).isFull());
+        ((BoundedFifoBuffer) collection).remove();
+        assertEquals(false, ((BoundedCollection) collection).isFull());
+        ((BoundedFifoBuffer) collection).add("jj");
+        assertEquals(true, ((BoundedCollection) collection).isFull());
+    }
+
+    /**
+     * Tests max size
+     */
+    public void testMaxSize() {
+        resetFull();
+        assertEquals(getFullElements().length, ((BoundedCollection) collection).maxSize());
+        ((BoundedFifoBuffer) collection).remove();
+        assertEquals(getFullElements().length, ((BoundedCollection) collection).maxSize());
+        ((BoundedFifoBuffer) collection).add("jj");
+        assertEquals(getFullElements().length, ((BoundedCollection) collection).maxSize());
+    }
+
 }
 

src/test/org/apache/commons/collections/TestCollectionUtils.java

@@ -1,7 +1,7 @@
 /*
- * $Id: TestCollectionUtils.java,v 1.7 2002/11/01 19:54:27 rwaldhoff Exp $
+ * $Id: TestCollectionUtils.java,v 1.8 2002/11/24 16:23:21 scolebourne Exp $
- * $Revision: 1.7 $
+ * $Revision: 1.8 $
- * $Date: 2002/11/01 19:54:27 $
+ * $Date: 2002/11/24 16:23:21 $
  *
  * ====================================================================
  *
@@ -66,7 +66,7 @@ import java.util.*;
 
 /**
  * @author Rodney Waldhoff
- * @version $Revision: 1.7 $ $Date: 2002/11/01 19:54:27 $
+ * @version $Revision: 1.8 $ $Date: 2002/11/24 16:23:21 $
  */
 public class TestCollectionUtils extends TestCase {
     public TestCollectionUtils(String testName) {
@@ -498,4 +498,56 @@ public class TestCollectionUtils extends TestCase {
         };
     }
 
+    public void testIsFull() {
+        Set set = new HashSet();
+        set.add("1");
+        set.add("2");
+        set.add("3");
+        try {
+            CollectionUtils.isFull(null);
+            fail();
+        } catch (NullPointerException ex) {}
+        assertEquals(false, CollectionUtils.isFull(set));
+        
+        BoundedFifoBuffer buf = new BoundedFifoBuffer(set);
+        assertEquals(true, CollectionUtils.isFull(buf));
+        buf.remove("2");
+        assertEquals(false, CollectionUtils.isFull(buf));
+        buf.add("2");
+        assertEquals(true, CollectionUtils.isFull(buf));
+        
+        Buffer buf2 = BufferUtils.synchronizedBuffer(buf);
+        assertEquals(true, CollectionUtils.isFull(buf2));
+        buf2.remove("2");
+        assertEquals(false, CollectionUtils.isFull(buf2));
+        buf2.add("2");
+        assertEquals(true, CollectionUtils.isFull(buf2));
+    }
+
+    public void testMaxSize() {
+        Set set = new HashSet();
+        set.add("1");
+        set.add("2");
+        set.add("3");
+        try {
+            CollectionUtils.maxSize(null);
+            fail();
+        } catch (NullPointerException ex) {}
+        assertEquals(-1, CollectionUtils.maxSize(set));
+        
+        BoundedFifoBuffer buf = new BoundedFifoBuffer(set);
+        assertEquals(3, CollectionUtils.maxSize(buf));
+        buf.remove("2");
+        assertEquals(3, CollectionUtils.maxSize(buf));
+        buf.add("2");
+        assertEquals(3, CollectionUtils.maxSize(buf));
+        
+        Buffer buf2 = BufferUtils.synchronizedBuffer(buf);
+        assertEquals(3, CollectionUtils.maxSize(buf2));
+        buf2.remove("2");
+        assertEquals(3, CollectionUtils.maxSize(buf2));
+        buf2.add("2");
+        assertEquals(3, CollectionUtils.maxSize(buf2));
+    }
+
 }