Abstract*Decorator - Generify and use covariant return types

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

RELEASE-NOTES.txt

@@ -38,6 +38,10 @@ Changes from commons-collections
 - Removed Typed* containers such as TypedList and TypedMap
   - use generics for type safety, or Collections.checked*()
 
+- Switch Abstract*Decorator classes to expose decorated() protected method
+  instead of the decorated collection directly. Each class overrides decorated()
+  to add its type covariantly, thus getList()/getSet() etc. methods are removed
+
 
 Feedback
 --------

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

@@ -53,18 +53,28 @@ public abstract class AbstractBufferDecorator extends AbstractCollectionDecorato
      * Gets the buffer being decorated.
      * 
      * @return the decorated buffer
+     * @deprecated use decorated()
      */
     protected Buffer getBuffer() {
-        return (Buffer) getCollection();
+        return decorated();
+    }
+
+    /**
+     * Gets the buffer being decorated.
+     * 
+     * @return the decorated buffer
+     */
+    protected Buffer decorated() {
+        return (Buffer) super.decorated();
     }
 
     //-----------------------------------------------------------------------
     public Object get() {
-        return getBuffer().get();
+        return decorated().get();
     }
 
     public Object remove() {
-        return getBuffer().remove();
+        return decorated().remove();
     }
 
 }

src/java/org/apache/commons/collections/collection/AbstractCollectionDecorator.java

@@ -34,16 +34,17 @@ import java.util.Iterator;
  * wrapped collection. This may be undesirable, for example if you are trying
  * to write an unmodifiable implementation it might provide a loophole.
  *
+ * @param <E> the type of the elements in the collection
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  * 
  * @author Stephen Colebourne
  * @author Paul Jack
  */
-public abstract class AbstractCollectionDecorator implements Collection {
+public abstract class AbstractCollectionDecorator<E> implements Collection<E> {
 
     /** The collection being decorated */
-    protected Collection collection;
+    protected Collection<E> collection;
 
     /**
      * Constructor only used in deserialization, do not use otherwise.
@@ -59,7 +60,7 @@ public abstract class AbstractCollectionDecorator implements Collection {
      * @param coll  the collection to decorate, must not be null
      * @throws IllegalArgumentException if the collection is null
      */
-    protected AbstractCollectionDecorator(Collection coll) {
+    protected AbstractCollectionDecorator(Collection<E> coll) {
         if (coll == null) {
             throw new IllegalArgumentException("Collection must not be null");
         }
@@ -70,77 +71,88 @@ public abstract class AbstractCollectionDecorator implements Collection {
      * Gets the collection being decorated.
      * 
      * @return the decorated collection
+     * @deprecated use decorated()
      */
-    protected Collection getCollection() {
+    protected Collection<E> getCollection() {
+        return decorated();
+    }
+
+    /**
+     * Gets the collection being decorated.
+     * All access to the decorated collection goes via this method.
+     * 
+     * @return the decorated collection
+     */
+    protected Collection<E> decorated() {
         return collection;
     }
 
     //-----------------------------------------------------------------------
-    public boolean add(Object object) {
+    public boolean add(E object) {
-        return collection.add(object);
+        return decorated().add(object);
     }
 
-    public boolean addAll(Collection coll) {
+    public boolean addAll(Collection<? extends E> coll) {
-        return collection.addAll(coll);
+        return decorated().addAll(coll);
     }
 
     public void clear() {
-        collection.clear();
+        decorated().clear();
     }
 
     public boolean contains(Object object) {
-        return collection.contains(object);
+        return decorated().contains(object);
     }
 
     public boolean isEmpty() {
-        return collection.isEmpty();
+        return decorated().isEmpty();
     }
 
-    public Iterator iterator() {
+    public Iterator<E> iterator() {
-        return collection.iterator();
+        return decorated().iterator();
     }
 
     public boolean remove(Object object) {
-        return collection.remove(object);
+        return decorated().remove(object);
     }
 
     public int size() {
-        return collection.size();
+        return decorated().size();
     }
 
     public Object[] toArray() {
-        return collection.toArray();
+        return decorated().toArray();
     }
 
-    public Object[] toArray(Object[] object) {
+    public <T> T[] toArray(T[] object) {
-        return collection.toArray(object);
+        return decorated().toArray(object);
     }
 
-    public boolean containsAll(Collection coll) {
+    public boolean containsAll(Collection<?> coll) {
-        return collection.containsAll(coll);
+        return decorated().containsAll(coll);
     }
 
-    public boolean removeAll(Collection coll) {
+    public boolean removeAll(Collection<?> coll) {
-        return collection.removeAll(coll);
+        return decorated().removeAll(coll);
     }
 
-    public boolean retainAll(Collection coll) {
+    public boolean retainAll(Collection<?> coll) {
-        return collection.retainAll(coll);
+        return decorated().retainAll(coll);
     }
 
     public boolean equals(Object object) {
         if (object == this) {
             return true;
         }
-        return collection.equals(object);
+        return decorated().equals(object);
     }
 
     public int hashCode() {
-        return collection.hashCode();
+        return decorated().hashCode();
     }
 
     public String toString() {
-        return collection.toString();
+        return decorated().toString();
     }
 
 }

src/java/org/apache/commons/collections/list/AbstractListDecorator.java

@@ -27,12 +27,15 @@ import org.apache.commons.collections.collection.AbstractCollectionDecorator;
  * <p>
  * Methods are forwarded directly to the decorated list.
  *
+ * @param <E> the type of the elements in the list
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  * 
  * @author Stephen Colebourne
  */
-public abstract class AbstractListDecorator extends AbstractCollectionDecorator implements List {
+public abstract class AbstractListDecorator<E>
+        extends AbstractCollectionDecorator<E>
+        implements List<E> {
 
     /**
      * Constructor only used in deserialization, do not use otherwise.
@@ -48,7 +51,7 @@ public abstract class AbstractListDecorator extends AbstractCollectionDecorator
      * @param list  the list to decorate, must not be null
      * @throws IllegalArgumentException if list is null
      */
-    protected AbstractListDecorator(List list) {
+    protected AbstractListDecorator(List<E> list) {
         super(list);
     }
 
@@ -56,50 +59,60 @@ public abstract class AbstractListDecorator extends AbstractCollectionDecorator
      * Gets the list being decorated.
      * 
      * @return the decorated list
+     * @deprecated use decorated()
      */
-    protected List getList() {
+    protected List<E> getList() {
-        return (List) getCollection();
+        return decorated();
+    }
+
+    /**
+     * Gets the list being decorated.
+     * 
+     * @return the decorated list
+     */
+    protected List<E> decorated() {
+        return (List<E>) super.decorated();
     }
 
     //-----------------------------------------------------------------------
-    public void add(int index, Object object) {
+    public void add(int index, E object) {
-        getList().add(index, object);
+        decorated().add(index, object);
     }
 
-    public boolean addAll(int index, Collection coll) {
+    public boolean addAll(int index, Collection<? extends E> coll) {
-        return getList().addAll(index, coll);
+        return decorated().addAll(index, coll);
     }
 
-    public Object get(int index) {
+    public E get(int index) {
-        return getList().get(index);
+        return decorated().get(index);
     }
 
     public int indexOf(Object object) {
-        return getList().indexOf(object);
+        return decorated().indexOf(object);
     }
 
     public int lastIndexOf(Object object) {
-        return getList().lastIndexOf(object);
+        return decorated().lastIndexOf(object);
     }
 
-    public ListIterator listIterator() {
+    public ListIterator<E> listIterator() {
-        return getList().listIterator();
+        return decorated().listIterator();
     }
 
-    public ListIterator listIterator(int index) {
+    public ListIterator<E> listIterator(int index) {
-        return getList().listIterator(index);
+        return decorated().listIterator(index);
     }
 
-    public Object remove(int index) {
+    public E remove(int index) {
-        return getList().remove(index);
+        return decorated().remove(index);
     }
 
-    public Object set(int index, Object object) {
+    public E set(int index, E object) {
-        return getList().set(index, object);
+        return decorated().set(index, object);
     }
 
-    public List subList(int fromIndex, int toIndex) {
+    public List<E> subList(int fromIndex, int toIndex) {
-        return getList().subList(fromIndex, toIndex);
+        return decorated().subList(fromIndex, toIndex);
     }
 
 }

src/java/org/apache/commons/collections/set/AbstractSetDecorator.java

@@ -25,12 +25,15 @@ import org.apache.commons.collections.collection.AbstractCollectionDecorator;
  * <p>
  * Methods are forwarded directly to the decorated set.
  *
+ * @param <E> the type of the elements in the set
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  * 
  * @author Stephen Colebourne
  */
-public abstract class AbstractSetDecorator extends AbstractCollectionDecorator implements Set {
+public abstract class AbstractSetDecorator<E>
+        extends AbstractCollectionDecorator<E>
+        implements Set<E> {
 
     /**
      * Constructor only used in deserialization, do not use otherwise.
@@ -46,7 +49,7 @@ public abstract class AbstractSetDecorator extends AbstractCollectionDecorator i
      * @param set  the set to decorate, must not be null
      * @throws IllegalArgumentException if set is null
      */
-    protected AbstractSetDecorator(Set set) {
+    protected AbstractSetDecorator(Set<E> set) {
         super(set);
     }
 
@@ -54,9 +57,19 @@ public abstract class AbstractSetDecorator extends AbstractCollectionDecorator i
      * Gets the set being decorated.
      * 
      * @return the decorated set
+     * @deprecated use decorated()
      */
-    protected Set getSet() {
+    protected Set<E> getSet() {
-        return (Set) getCollection();
+        return decorated();
+    }
+
+    /**
+     * Gets the set being decorated.
+     * 
+     * @return the decorated set
+     */
+    protected Set<E> decorated() {
+        return (Set<E>) super.decorated();
     }
 
 }

src/java/org/apache/commons/collections/set/AbstractSortedSetDecorator.java

@@ -25,12 +25,15 @@ import java.util.SortedSet;
  * <p>
  * Methods are forwarded directly to the decorated set.
  *
+ * @param <E> the type of the elements in the sorted set
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  * 
  * @author Stephen Colebourne
  */
-public abstract class AbstractSortedSetDecorator extends AbstractSetDecorator implements SortedSet {
+public abstract class AbstractSortedSetDecorator<E>
+        extends AbstractSetDecorator<E>
+        implements SortedSet<E> {
 
     /**
      * Constructor only used in deserialization, do not use otherwise.
@@ -46,7 +49,7 @@ public abstract class AbstractSortedSetDecorator extends AbstractSetDecorator im
      * @param set  the set to decorate, must not be null
      * @throws IllegalArgumentException if set is null
      */
-    protected AbstractSortedSetDecorator(Set set) {
+    protected AbstractSortedSetDecorator(Set<E> set) {
         super(set);
     }
 
@@ -54,34 +57,44 @@ public abstract class AbstractSortedSetDecorator extends AbstractSetDecorator im
      * Gets the sorted set being decorated.
      * 
      * @return the decorated set
+     * @deprecated use decorated()
      */
-    protected SortedSet getSortedSet() {
+    protected SortedSet<E> getSortedSet() {
-        return (SortedSet) getCollection();
+        return decorated();
+    }
+
+    /**
+     * Gets the set being decorated.
+     * 
+     * @return the decorated set
+     */
+    protected SortedSet<E> decorated() {
+        return (SortedSet<E>) super.decorated();
     }
 
     //-----------------------------------------------------------------------
-    public SortedSet subSet(Object fromElement, Object toElement) {
+    public SortedSet<E> subSet(E fromElement, E toElement) {
-        return getSortedSet().subSet(fromElement, toElement);
+        return decorated().subSet(fromElement, toElement);
     }
 
-    public SortedSet headSet(Object toElement) {
+    public SortedSet<E> headSet(E toElement) {
-        return getSortedSet().headSet(toElement);
+        return decorated().headSet(toElement);
     }
 
-    public SortedSet tailSet(Object fromElement) {
+    public SortedSet<E> tailSet(E fromElement) {
-        return getSortedSet().tailSet(fromElement);
+        return decorated().tailSet(fromElement);
     }
 
-    public Object first() {
+    public E first() {
-        return getSortedSet().first();
+        return decorated().first();
     }
 
-    public Object last() {
+    public E last() {
-        return getSortedSet().last();
+        return decorated().last();
     }
 
-    public Comparator comparator() {
+    public Comparator<? super E> comparator() {
-        return getSortedSet().comparator();
+        return decorated().comparator();
     }
 
 }