From 44709d8b2a99a9ac12619ba0c65196c06178e53b Mon Sep 17 00:00:00 2001
From: Thomas Neidhart <tn@apache.org>
Date: Sat, 23 Jun 2012 15:05:20 +0000
Subject: [PATCH] [COLLECTIONS-231] return specific type rather than base type
 in factory methods, javadoc cleanup.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1353139 13f79535-47bb-0310-9956-ffa450edef68
---
 .../buffer/AbstractBufferDecorator.java        |  7 +++++++
 .../collections/buffer/BlockingBuffer.java     | 15 ++++++++++-----
 .../collections/buffer/BoundedBuffer.java      |  8 ++++++++
 .../collections/buffer/PredicatedBuffer.java   | 12 ++++++++++--
 .../collections/buffer/SynchronizedBuffer.java | 13 ++++++++++---
 .../collections/buffer/TransformedBuffer.java  | 18 +++++++++++++++---
 .../buffer/UnboundedFifoBuffer.java            |  2 +-
 .../collections/buffer/UnmodifiableBuffer.java |  1 +
 8 files changed, 62 insertions(+), 14 deletions(-)

diff --git a/src/main/java/org/apache/commons/collections/buffer/AbstractBufferDecorator.java b/src/main/java/org/apache/commons/collections/buffer/AbstractBufferDecorator.java
index 8863c14ef..79b9d5491 100644
--- a/src/main/java/org/apache/commons/collections/buffer/AbstractBufferDecorator.java
+++ b/src/main/java/org/apache/commons/collections/buffer/AbstractBufferDecorator.java
@@ -65,10 +65,17 @@ public abstract class AbstractBufferDecorator<E> extends AbstractCollectionDecor
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E get() {
         return decorated().get();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E remove() {
         return decorated().remove();
     }
diff --git a/src/main/java/org/apache/commons/collections/buffer/BlockingBuffer.java b/src/main/java/org/apache/commons/collections/buffer/BlockingBuffer.java
index 276bbb1a8..3e186e063 100644
--- a/src/main/java/org/apache/commons/collections/buffer/BlockingBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/BlockingBuffer.java
@@ -59,26 +59,27 @@ public class BlockingBuffer<E> extends SynchronizedBuffer<E> {
     /**
      * Factory method to create a blocking buffer.
      *
-     * @param <T> the type of the elements in the buffer
+     * @param <E> the type of the elements in the buffer
      * @param buffer the buffer to decorate, must not be null
      * @return a new blocking Buffer
      * @throws IllegalArgumentException if buffer is null
      */
-    public static <T> Buffer<T> blockingBuffer(Buffer<T> buffer) {
-        return new BlockingBuffer<T>(buffer);
+    public static <E> BlockingBuffer<E> blockingBuffer(Buffer<E> buffer) {
+        return new BlockingBuffer<E>(buffer);
     }
 
     /**
      * Factory method to create a blocking buffer with a timeout value.
      *
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param timeoutMillis  the timeout value in milliseconds, zero or less for no timeout
      * @return a new blocking buffer
      * @throws IllegalArgumentException if the buffer is null
      * @since Commons Collections 3.2
      */
-    public static <T> Buffer<T> blockingBuffer(Buffer<T> buffer, long timeoutMillis) {
-        return new BlockingBuffer<T>(buffer, timeoutMillis);
+    public static <E> BlockingBuffer<E> blockingBuffer(Buffer<E> buffer, long timeoutMillis) {
+        return new BlockingBuffer<E>(buffer, timeoutMillis);
     }
 
     //-----------------------------------------------------------------------    
@@ -131,6 +132,7 @@ public class BlockingBuffer<E> extends SynchronizedBuffer<E> {
      * set in the constructor.
      *
      * @throws BufferUnderflowException if an interrupt is received
+     * {@inheritDoc}
      */
     @Override
     public E get() {
@@ -157,6 +159,7 @@ public class BlockingBuffer<E> extends SynchronizedBuffer<E> {
      * added for up to the specified timeout value if the buffer is empty.
      *
      * @param timeout  the timeout value in milliseconds
+     * @return the next object in the buffer
      * @throws BufferUnderflowException if an interrupt is received
      * @throws BufferUnderflowException if the timeout expires
      * @since Commons Collections 3.2
@@ -188,6 +191,7 @@ public class BlockingBuffer<E> extends SynchronizedBuffer<E> {
      * set in the constructor.
      *
      * @throws BufferUnderflowException if an interrupt is received
+     * {@inheritDoc}
      */
     @Override
     public E remove() {
@@ -214,6 +218,7 @@ public class BlockingBuffer<E> extends SynchronizedBuffer<E> {
      * added for up to the specified timeout value if the buffer is empty.
      *
      * @param timeout  the timeout value in milliseconds
+     * @return the next object in the buffer, which is also removed
      * @throws BufferUnderflowException if an interrupt is received
      * @throws BufferUnderflowException if the timeout expires
      * @since Commons Collections 3.2
diff --git a/src/main/java/org/apache/commons/collections/buffer/BoundedBuffer.java b/src/main/java/org/apache/commons/collections/buffer/BoundedBuffer.java
index 49cbcb661..1ff85eb77 100644
--- a/src/main/java/org/apache/commons/collections/buffer/BoundedBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/BoundedBuffer.java
@@ -61,6 +61,7 @@ public class BoundedBuffer<E> extends SynchronizedBuffer<E> implements BoundedCo
      * When the buffer is full, it will immediately throw a
      * <code>BufferOverflowException</code> on calling <code>add()</code>.
      *
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param maximumSize  the maximum size, must be size one or greater
      * @return a new bounded buffer
@@ -75,6 +76,7 @@ public class BoundedBuffer<E> extends SynchronizedBuffer<E> implements BoundedCo
      * Factory method to create a bounded buffer that blocks for a maximum
      * amount of time.
      *
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param maximumSize  the maximum size, must be size one or greater
      * @param timeout  the maximum amount of time to wait in milliseconds
@@ -169,11 +171,17 @@ public class BoundedBuffer<E> extends SynchronizedBuffer<E> implements BoundedCo
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean isFull() {
         // size() is synchronized
         return (size() == maxSize());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public int maxSize() {
         return maximumSize;
     }
diff --git a/src/main/java/org/apache/commons/collections/buffer/PredicatedBuffer.java b/src/main/java/org/apache/commons/collections/buffer/PredicatedBuffer.java
index a85122607..d8517c1b8 100644
--- a/src/main/java/org/apache/commons/collections/buffer/PredicatedBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/PredicatedBuffer.java
@@ -50,14 +50,15 @@ public class PredicatedBuffer<E> extends PredicatedCollection<E> implements Buff
      * If there are any elements already in the buffer being decorated, they
      * are validated.
      * 
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
      * @return a new predicated Buffer
      * @throws IllegalArgumentException if buffer or predicate is null
      * @throws IllegalArgumentException if the buffer contains invalid elements
      */
-    public static <T> Buffer<T> predicatedBuffer(Buffer<T> buffer, Predicate<? super T> predicate) {
-        return new PredicatedBuffer<T>(buffer, predicate);
+    public static <E> PredicatedBuffer<E> predicatedBuffer(Buffer<E> buffer, Predicate<? super E> predicate) {
+        return new PredicatedBuffer<E>(buffer, predicate);
     }
     
     //-----------------------------------------------------------------------
@@ -87,10 +88,17 @@ public class PredicatedBuffer<E> extends PredicatedCollection<E> implements Buff
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E get() {
         return decorated().get();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E remove() {
         return decorated().remove();
     }
diff --git a/src/main/java/org/apache/commons/collections/buffer/SynchronizedBuffer.java b/src/main/java/org/apache/commons/collections/buffer/SynchronizedBuffer.java
index ca9b2b581..2ae6a145a 100644
--- a/src/main/java/org/apache/commons/collections/buffer/SynchronizedBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/SynchronizedBuffer.java
@@ -43,13 +43,13 @@ public class SynchronizedBuffer<E>
     /**
      * Factory method to create a synchronized buffer.
      * 
-     * @param <T> the type of the elements in the buffer
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @return a new synchronized Buffer
      * @throws IllegalArgumentException if buffer is null
      */
-    public static <T> Buffer<T> synchronizedBuffer(Buffer<T> buffer) {
-        return new SynchronizedBuffer<T>(buffer);
+    public static <E> SynchronizedBuffer<E> synchronizedBuffer(Buffer<E> buffer) {
+        return new SynchronizedBuffer<E>(buffer);
     }
 
     //-----------------------------------------------------------------------
@@ -85,12 +85,19 @@ public class SynchronizedBuffer<E>
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E get() {
         synchronized (lock) {
             return decorated().get();
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E remove() {
         synchronized (lock) {
             return decorated().remove();
diff --git a/src/main/java/org/apache/commons/collections/buffer/TransformedBuffer.java b/src/main/java/org/apache/commons/collections/buffer/TransformedBuffer.java
index 6d5e02b74..11c5de4c7 100644
--- a/src/main/java/org/apache/commons/collections/buffer/TransformedBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/TransformedBuffer.java
@@ -47,12 +47,14 @@ public class TransformedBuffer<E> extends TransformedCollection<E> implements Bu
      * are NOT transformed.
      * Contrast this with {@link #transformedBuffer(Buffer, Transformer)}.
      * 
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed Buffer
      * @throws IllegalArgumentException if buffer or transformer is null
      */
-    public static <E> Buffer<E> transformingBuffer(Buffer<E> buffer, Transformer<? super E, ? extends E> transformer) {
+    public static <E> TransformedBuffer<E> transformingBuffer(Buffer<E> buffer,
+                                                              Transformer<? super E, ? extends E> transformer) {
         return new TransformedBuffer<E>(buffer, transformer);
     }
     
@@ -64,14 +66,17 @@ public class TransformedBuffer<E> extends TransformedCollection<E> implements Bu
      * will be transformed by this method.
      * Contrast this with {@link #transformingBuffer(Buffer, Transformer)}.
      * 
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed Buffer
      * @throws IllegalArgumentException if buffer or transformer is null
      * @since Commons Collections 3.3
      */
-    public static <E> Buffer<E> transformedBuffer(Buffer<E> buffer, Transformer<? super E, ? extends E> transformer) {
-        TransformedBuffer<E> decorated = new TransformedBuffer<E>(buffer, transformer); // throws IAE if buffer or transformer is null
+    public static <E> TransformedBuffer<E> transformedBuffer(Buffer<E> buffer,
+                                                             Transformer<? super E, ? extends E> transformer) {
+        // throws IAE if buffer or transformer is null
+        final TransformedBuffer<E> decorated = new TransformedBuffer<E>(buffer, transformer); 
         if (buffer.size() > 0) {
             @SuppressWarnings("unchecked") // buffer is type <E>
             E[] values = (E[]) buffer.toArray();
@@ -108,10 +113,17 @@ public class TransformedBuffer<E> extends TransformedCollection<E> implements Bu
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E get() {
         return getBuffer().get();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E remove() {
         return getBuffer().remove();
     }
diff --git a/src/main/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java b/src/main/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java
index cd14d4661..836dbb95e 100644
--- a/src/main/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java
@@ -67,7 +67,7 @@ public class UnboundedFifoBuffer<E> extends AbstractCollection<E> implements Buf
     // invariant: buffer.length > size()
     //   ie.buffer always has at least one empty entry
 
-    /** Serialization vesrion */
+    /** Serialization version */
     private static final long serialVersionUID = -3482960336579541419L;
 
     /** The array of objects in the buffer. */
diff --git a/src/main/java/org/apache/commons/collections/buffer/UnmodifiableBuffer.java b/src/main/java/org/apache/commons/collections/buffer/UnmodifiableBuffer.java
index bb89f5a5c..63b752993 100644
--- a/src/main/java/org/apache/commons/collections/buffer/UnmodifiableBuffer.java
+++ b/src/main/java/org/apache/commons/collections/buffer/UnmodifiableBuffer.java
@@ -51,6 +51,7 @@ public final class UnmodifiableBuffer<E>
      * <p>
      * If the buffer passed in is already unmodifiable, it is returned.
      * 
+     * @param <E> the type of the elements in the buffer
      * @param buffer  the buffer to decorate, must not be null
      * @return an unmodifiable Buffer
      * @throws IllegalArgumentException if buffer is null