From e02e9818cf3e5c125e5fbc8417afd892c8dfeed0 Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sun, 24 Nov 2002 16:23:21 +0000 Subject: [PATCH] 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 | 4 +- .../collections/BoundedCollection.java | 89 +++++++++++++++++ .../collections/BoundedFifoBuffer.java | 31 ++++-- .../commons/collections/CollectionUtils.java | 95 +++++++++++++++++-- .../collections/TestBoundedFifoBuffer2.java | 30 +++++- .../collections/TestCollectionUtils.java | 60 +++++++++++- 6 files changed, 286 insertions(+), 23 deletions(-) create mode 100644 src/java/org/apache/commons/collections/BoundedCollection.java diff --git a/STATUS.html b/STATUS.html index 01910e811..eda57b71c 100644 --- a/STATUS.html +++ b/STATUS.html @@ -7,7 +7,7 @@

The Jakarta Commons Collections Package

-$Id: STATUS.html,v 1.20 2002/11/21 23:09:57 scolebourne Exp $
+$Id: STATUS.html,v 1.21 2002/11/24 16:23:20 scolebourne Exp $
[Introduction] [Dependencies] [Release Info] @@ -40,6 +40,8 @@ The following classes are included:

keys of the map and the property values are the values of the map.
  • BinaryHeap - Binary heap implementation of PriorityQueue and Buffer.
    • +
  • BoundedCollection - an interface used by collections that can +have a variable number of elements up to a fixed bound.
  • BoundedFifoBuffer - a very efficient implementation of Buffer that does not alter the size of the buffer at runtime.
  • Buffer - a collection that allows objects to be removed diff --git a/src/java/org/apache/commons/collections/BoundedCollection.java b/src/java/org/apache/commons/collections/BoundedCollection.java new file mode 100644 index 000000000..2ae0c997c --- /dev/null +++ b/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 + * . + * + */ +package org.apache.commons.collections; + +import java.util.Collection; +/** + * A BoundedCollection is a collection that is bounded in size. + *

    + * 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 Herve Quiroz + * @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 true 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(); + +} diff --git a/src/java/org/apache/commons/collections/BoundedFifoBuffer.java b/src/java/org/apache/commons/collections/BoundedFifoBuffer.java index c531929a6..a40d28774 100644 --- a/src/java/org/apache/commons/collections/BoundedFifoBuffer.java +++ b/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 $ - * $Revision: 1.5 $ - * $Date: 2002/10/13 12:59:04 $ + * $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.6 $ + * $Date: 2002/11/24 16:23:21 $ * * ==================================================================== * @@ -85,14 +85,15 @@ import java.util.NoSuchElementException; *

    * This buffer prevents null objects from being added. * + * @since 2.1 * @author Avalon * @author Berin Loritsch * @author Paul Jack * @author Stephen Colebourne - * @since 2.1 - * @version $Id: BoundedFifoBuffer.java,v 1.5 2002/10/13 12:59:04 scolebourne Exp $ + * @author Herve Quiroz + * @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 true 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. */ diff --git a/src/java/org/apache/commons/collections/CollectionUtils.java b/src/java/org/apache/commons/collections/CollectionUtils.java index c4ced82c9..1b6b6a944 100644 --- a/src/java/org/apache/commons/collections/CollectionUtils.java +++ b/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 $ - * $Revision: 1.19 $ - * $Date: 2002/11/01 19:54:26 $ + * $Id: CollectionUtils.java,v 1.20 2002/11/24 16:23:21 scolebourne Exp $ + * $Revision: 1.20 $ + * $Date: 2002/11/24 16:23:21 $ * * ==================================================================== * @@ -58,7 +58,6 @@ * . * */ - 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 Herve Quiroz + * @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. + *

    + * This method uses the {@link BoundedCollection} class to determine the + * full status. If the collection does not implement this interface then + * false is returned. + *

    + * 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. + *

    + * This method uses the {@link BoundedCollection} class to determine the + * maximum size. If the collection does not implement this interface then + * -1 is returned. + *

    + * 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. diff --git a/src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java b/src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java index 24df0e3a1..dd7b8f220 100644 --- a/src/test/org/apache/commons/collections/TestBoundedFifoBuffer2.java +++ b/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 $ - * $Revision: 1.3 $ - * $Date: 2002/10/12 22:36:21 $ + * $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.4 $ + * $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()); + } + } diff --git a/src/test/org/apache/commons/collections/TestCollectionUtils.java b/src/test/org/apache/commons/collections/TestCollectionUtils.java index 9f3a1fb1f..7fbb60663 100644 --- a/src/test/org/apache/commons/collections/TestCollectionUtils.java +++ b/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 $ - * $Revision: 1.7 $ - * $Date: 2002/11/01 19:54:27 $ + * $Id: TestCollectionUtils.java,v 1.8 2002/11/24 16:23:21 scolebourne Exp $ + * $Revision: 1.8 $ + * $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)); + } + }