Implement BoundedCollection, Add javadoc

rfe 37473

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

src/java/org/apache/commons/collections/buffer/BoundedBuffer.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2005 The Apache Software Foundation
+ *  Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -15,24 +15,33 @@
  */
 package org.apache.commons.collections.buffer;
 
-import org.apache.commons.collections.Buffer;
-import org.apache.commons.collections.BufferOverflowException;
-import org.apache.commons.collections.BufferUnderflowException;
-import org.apache.commons.collections.iterators.AbstractIteratorDecorator;
-
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.util.Collection;
 import java.util.Iterator;
 
+import org.apache.commons.collections.BoundedCollection;
+import org.apache.commons.collections.Buffer;
+import org.apache.commons.collections.BufferOverflowException;
+import org.apache.commons.collections.BufferUnderflowException;
+import org.apache.commons.collections.iterators.AbstractIteratorDecorator;
+
 /**
- * A wrapper class for buffers which makes them bounded.
+ * Decorates another <code>Buffer</code> to ensure a fixed maximum size.
+ * <p>
+ * Note: This class should only be used if you need to add bounded
+ * behaviour to another buffer. If you just want a bounded buffer then
+ * you should use {@link BoundedFifoBuffer} or {@link CircularFifoBuffer}.
+ * <p>
+ * The decoration methods allow you to specify a timeout value, which
+ * causes the add methods to wait for up to the specified wait period.
  *
  * @author James Carman
- * @version $Revision: $ $Date: $
+ * @author Stephen Colebourne
+ * @version $Revision$ $Date$
  * @since Commons Collections 3.2
  */
-public class BoundedBuffer extends SynchronizedBuffer {
+public class BoundedBuffer extends SynchronizedBuffer implements BoundedCollection {
 
     /** The serialization version. */
     private static final long serialVersionUID = 1536432911093974264L;
@@ -134,6 +143,14 @@ public class BoundedBuffer extends SynchronizedBuffer {
         }
     }
 
+    public boolean isFull() {
+        return (collection.size() == maxSize());
+    }
+
+    public int maxSize() {
+        return maximumSize;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * BoundedBuffer iterator.

src/test/org/apache/commons/collections/buffer/TestAll.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2004,2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -48,6 +48,7 @@ public class TestAll extends TestCase {
         suite.addTest(TestUnboundedFifoBuffer.suite());
         
         suite.addTest(TestBlockingBuffer.suite());
+        suite.addTest(TestBoundedBuffer.suite());
         suite.addTest(TestPredicatedBuffer.suite());
         suite.addTest(TestSynchronizedBuffer.suite());
         suite.addTest(TestTransformedBuffer.suite());

src/test/org/apache/commons/collections/buffer/TestBoundedBuffer.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2005 The Apache Software Foundation
+ *  Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 package org.apache.commons.collections.buffer;
 
 import org.apache.commons.collections.AbstractTestObject;
+import org.apache.commons.collections.BoundedCollection;
 import org.apache.commons.collections.Buffer;
 import org.apache.commons.collections.BufferOverflowException;
 
@@ -23,12 +24,24 @@ import java.util.Iterator;
 import java.util.Collections;
 import java.util.Arrays;
 
+import junit.framework.Test;
+import junit.framework.TestSuite;
+
 public class TestBoundedBuffer extends AbstractTestObject {
 
     public TestBoundedBuffer(String testName) {
         super(testName);
     }
 
+    public static Test suite() {
+        return new TestSuite(TestBoundedBuffer.class);
+    }
+
+    public static void main(String args[]) {
+        String[] testCaseName = { TestBoundedBuffer.class.getName() };
+        junit.textui.TestRunner.main(testCaseName);
+    }
+
     public String getCompatibilityVersion() {
         return "3.2";
     }
@@ -41,6 +54,20 @@ public class TestBoundedBuffer extends AbstractTestObject {
         return BoundedBuffer.decorate(new UnboundedFifoBuffer(), 1);
     }
 
+    //-----------------------------------------------------------------------
+    public void testMaxSize() {
+        final Buffer bounded = BoundedBuffer.decorate(new UnboundedFifoBuffer(), 2, 500);
+        BoundedCollection bc = (BoundedCollection) bounded;
+        assertEquals(2, bc.maxSize());
+        assertEquals(false, bc.isFull());
+        bounded.add("A");
+        assertEquals(false, bc.isFull());
+        bounded.add("B");
+        assertEquals(true, bc.isFull());
+        bounded.remove();
+        assertEquals(false, bc.isFull());
+    }
+
     public void testAddToFullBufferNoTimeout() {
         final Buffer bounded = BoundedBuffer.decorate(new UnboundedFifoBuffer(), 1);
         bounded.add( "Hello" );