Coverage Report - jaggregate.ExtensibleCollection
 
Classes in this File Line Coverage Branch Coverage Complexity
ExtensibleCollection
N/A
N/A
0
 
 1  
 /*
 2  
  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.
 3  
  Licensed under the Academic Free License version 3.0
 4  
  */
 5  
 
 6  
 package jaggregate;
 7  
 
 8  
 /**
 9  
  * Provides protocol for adding elements to and removing elements from a variable-sized
 10  
  * collection.
 11  
  *
 12  
  * @param <E> a restriction on the types of elements that may be included in the
 13  
  * collection
 14  
  *
 15  
  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
 16  
  * @version $Id: ExtensibleCollection.java,v 1.4 2008/05/07 06:00:48 pholser Exp $
 17  
  */
 18  
 public interface ExtensibleCollection<E> extends Collection<E> {
 19  
     /**
 20  
      * {@inheritDoc}
 21  
      *
 22  
      * @return a extensible collection of the transformations
 23  
      */
 24  
     <R> ExtensibleCollection<R> collect(
 25  
         UnaryFunctor<? super E, ? extends R> transformer );
 26  
 
 27  
     /**
 28  
      * {@inheritDoc}
 29  
      *
 30  
      * @return an extensible collection of the rejected elements of this collection
 31  
      */
 32  
     ExtensibleCollection<E> reject( UnaryCondition<? super E> discriminator );
 33  
 
 34  
     /**
 35  
      * {@inheritDoc}
 36  
      *
 37  
      * @return an extensible collection of the selected elements of this collection
 38  
      */
 39  
     ExtensibleCollection<E> select( UnaryCondition<? super E> discriminator );
 40  
 
 41  
     /**
 42  
      * Adds a new element to this collection.  Unless specifically refined,
 43  
      * the position of {@code newElement} in the element traversal order is unspecified.
 44  
      * <p/>
 45  
      * Conformant protocols may place restrictions on the characteristics of objects
 46  
      * that are valid elements.  Unless otherwise specified, any object that is of the
 47  
      * same class as or of a subclass of this collection's type parameter is acceptable.
 48  
      *
 49  
      * @param newElement the element to add
 50  
      * @throws IllegalArgumentException if {@code newElement} is found to violate
 51  
      * restrictions on the characteristics of valid elements
 52  
      */
 53  
     void add( E newElement );
 54  
 
 55  
     /**
 56  
      * Adds each element of the given collection to this collection.
 57  
      * <p/>
 58  
      * The operation is equivalent to adding each element of {@code newElements} to this
 59  
      * collection using {@link #add(Object) add} with the element as the parameter.
 60  
      * The {@code newElements} are traversed in the order specified by {@link
 61  
      * #forEachDo(UnaryFunctor) forEachDo} for {@code newElements}.
 62  
      *
 63  
      * @param newElements the elements to add
 64  
      * @throws NullPointerException if {@code newElements} is {@code null}
 65  
      * @throws IllegalArgumentException if any of {@code newElements} is found to
 66  
      * violate restrictions on the characteristics of valid elements
 67  
      */
 68  
     void addAll( Collection<? extends E> newElements );
 69  
 
 70  
     /**
 71  
      * @param newElements the elements to add
 72  
      * @throws NullPointerException if {@code newElements} is {@code null}
 73  
      * @throws IllegalArgumentException if any of {@code newElements} is found to
 74  
      * violate restrictions on the characteristics of valid elements
 75  
      * @see #addAll(Collection)
 76  
      */
 77  
     void addAll( E[] newElements );
 78  
 
 79  
     /**
 80  
      * @param newElement first new element to add
 81  
      * @param restOfNewElements remainder of the elements to add
 82  
      * @throws NullPointerException if {@code restOfNewElements} is {@code null}
 83  
      * @throws IllegalArgumentException if any of the new elements is found to violate
 84  
      * restrictions on the characteristics of valid elements
 85  
      * @see #addAll(Collection)
 86  
      */
 87  
     void addAll( E newElement, E... restOfNewElements );
 88  
 
 89  
     /**
 90  
      * @param newElements the elements to add
 91  
      * @throws NullPointerException if {@code newElements} is {@code null}
 92  
      * @throws IllegalArgumentException if any of {@code newElements} is found to
 93  
      * violate restrictions on the characteristics of valid elements
 94  
      * @see #addAll(Collection)
 95  
      */
 96  
     void addAll( Iterable<? extends E> newElements );
 97  
 
 98  
     /**
 99  
      * Removes the first element of this collection which is equivalent to the
 100  
      * given element.
 101  
      * <p/>
 102  
      * The elements are tested in the same order in which they would be enumerated by
 103  
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
 104  
      *
 105  
      * @param oldElement the element to remove
 106  
      * @return {@code true} if any removal occurred
 107  
      */
 108  
     boolean remove( E oldElement );
 109  
 
 110  
     /**
 111  
      * For each element in the given collection, removes the first element from this
 112  
      * collection which is equivalent to this element.
 113  
      * <p/>
 114  
      * The operation is defined to be equivalent to removing each element of {@code
 115  
      * oldElements} from this collection using {@link #remove(Object) remove} with the
 116  
      * element as the parameter.
 117  
      *
 118  
      * @param oldElements the elements to remove
 119  
      * @return {@code true} if any removal occurred
 120  
      * @throws NullPointerException if {@code oldElements} is {@code null}
 121  
      */
 122  
     boolean removeAll( Collection<? extends E> oldElements );
 123  
 
 124  
     /**
 125  
      * @param oldElements the elements to remove
 126  
      * @return {@code true} if any removal occurred
 127  
      * @throws NullPointerException if {@code oldElements} is {@code null}
 128  
      * @see #removeAll(Collection)
 129  
      */
 130  
     boolean removeAll( E[] oldElements );
 131  
 
 132  
     /**
 133  
      * @param oldElement first element to remove
 134  
      * @param restOfNewElements remainder of the elements to remove
 135  
      * @return {@code true} if any removal occurred
 136  
      * @throws NullPointerException if {@code restOfOldElements} is {@code null}
 137  
      * @see #removeAll(Collection)
 138  
      */
 139  
     boolean removeAll( E oldElement, E... restOfNewElements );
 140  
 
 141  
     /**
 142  
      * @param oldElements the elements to remove
 143  
      * @return {@code true} if any removal occurred
 144  
      * @throws NullPointerException if {@code oldElements} is {@code null}
 145  
      * @see #removeAll(Collection)
 146  
      */
 147  
     boolean removeAll( Iterable<? extends E> oldElements );
 148  
 
 149  
     /**
 150  
      * Removes each element of this collection which causes the given discriminator to
 151  
      * answer {@code true}.
 152  
      * <p/>
 153  
      * The elements are tested in the same order in which they would be enumerated by
 154  
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
 155  
      *
 156  
      * @param discriminator the discriminator to evaluate
 157  
      * @return {@code true} if any removal occurred
 158  
      * @throws NullPointerException if {@code discriminator} is {@code null}
 159  
      */
 160  
     boolean removeIf( UnaryCondition<? super E> discriminator );
 161  
 
 162  
     /**
 163  
      * Removes each element of this collection that is not contained in the
 164  
      * given collection.
 165  
      * <p/>
 166  
      * Note that if the given collection is {@linkplain #isEmpty() empty}, this method
 167  
      * has the effect of "clearing" this collection.
 168  
      *
 169  
      * @param keepers the elements to retain
 170  
      * @return {@code true} if any removal occurred
 171  
      * @throws NullPointerException if {@code keepers} is {@code null}
 172  
      */
 173  
     boolean retainAll( Collection<? extends E> keepers );
 174  
 
 175  
     /**
 176  
      * @param keepers the elements to retain
 177  
      * @return {@code true} if any removal occurred
 178  
      * @throws NullPointerException if {@code keepers} is {@code null}
 179  
      * @see #retainAll(Collection)
 180  
      */
 181  
     boolean retainAll( E[] keepers );
 182  
 
 183  
     /**
 184  
      * @param keeper first element to retain
 185  
      * @param restOfKeepers remainder of the elements to retain
 186  
      * @return {@code true} if any removal occurred
 187  
      * @throws NullPointerException if {@code restOfKeepers} is {@code null}
 188  
      * @see #retainAll(Collection)
 189  
      */
 190  
     boolean retainAll( E keeper, E... restOfKeepers );
 191  
 
 192  
     /**
 193  
      * @see #retainAll(Collection)
 194  
      * @param keepers the elements to retain
 195  
      * @return {@code true} if any removal occurred
 196  
      * @throws NullPointerException if {@code keepers} is {@code null}
 197  
      */
 198  
     boolean retainAll( Iterable<? extends E> keepers );
 199  
 
 200  
     /**
 201  
      * Removes each element of this collection which causes the given discriminator to
 202  
      * answer {@code false}.
 203  
      * <p/>
 204  
      * The elements are tested in the same order in which they would be enumerated by
 205  
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
 206  
      *
 207  
      * @param discriminator the discriminator to evaluate
 208  
      * @return {@code true} if any removal occurred
 209  
      * @throws NullPointerException if {@code discriminator} is {@code null}
 210  
      */
 211  
     boolean retainIf( UnaryCondition<? super E> discriminator );
 212  
 }