Coverage Report

Coverage Report - jaggregate.ExtensibleCollection

Classes in this File

 /*
  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.
  Licensed under the Academic Free License version 3.0
  */
 
 package jaggregate;
 
 /**
  * Provides protocol for adding elements to and removing elements from a variable-sized
  * collection.
  *
  * @param <E> a restriction on the types of elements that may be included in the
  * collection
  *
  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
  * @version $Id: ExtensibleCollection.java,v 1.4 2008/05/07 06:00:48 pholser Exp $
  */
 public interface ExtensibleCollection<E> extends Collection<E> {
     /**
      * {@inheritDoc}
      *
      * @return a extensible collection of the transformations
      */
     <R> ExtensibleCollection<R> collect(
         UnaryFunctor<? super E, ? extends R> transformer );
 
     /**
      * {@inheritDoc}
      *
      * @return an extensible collection of the rejected elements of this collection
      */
     ExtensibleCollection<E> reject( UnaryCondition<? super E> discriminator );
 
     /**
      * {@inheritDoc}
      *
      * @return an extensible collection of the selected elements of this collection
      */
     ExtensibleCollection<E> select( UnaryCondition<? super E> discriminator );
 
     /**
      * Adds a new element to this collection.  Unless specifically refined,
      * the position of {@code newElement} in the element traversal order is unspecified.
      * <p/>
      * Conformant protocols may place restrictions on the characteristics of objects
      * that are valid elements.  Unless otherwise specified, any object that is of the
      * same class as or of a subclass of this collection's type parameter is acceptable.
      *
      * @param newElement the element to add
      * @throws IllegalArgumentException if {@code newElement} is found to violate
      * restrictions on the characteristics of valid elements
      */
     void add( E newElement );
 
     /**
      * Adds each element of the given collection to this collection.
      * <p/>
      * The operation is equivalent to adding each element of {@code newElements} to this
      * collection using {@link #add(Object) add} with the element as the parameter.
      * The {@code newElements} are traversed in the order specified by {@link
      * #forEachDo(UnaryFunctor) forEachDo} for {@code newElements}.
      *
      * @param newElements the elements to add
      * @throws NullPointerException if {@code newElements} is {@code null}
      * @throws IllegalArgumentException if any of {@code newElements} is found to
      * violate restrictions on the characteristics of valid elements
      */
     void addAll( Collection<? extends E> newElements );
 
     /**
      * @param newElements the elements to add
      * @throws NullPointerException if {@code newElements} is {@code null}
      * @throws IllegalArgumentException if any of {@code newElements} is found to
      * violate restrictions on the characteristics of valid elements
      * @see #addAll(Collection)
      */
     void addAll( E[] newElements );
 
     /**
      * @param newElement first new element to add
      * @param restOfNewElements remainder of the elements to add
      * @throws NullPointerException if {@code restOfNewElements} is {@code null}
      * @throws IllegalArgumentException if any of the new elements is found to violate
      * restrictions on the characteristics of valid elements
      * @see #addAll(Collection)
      */
     void addAll( E newElement, E... restOfNewElements );
 
     /**
      * @param newElements the elements to add
      * @throws NullPointerException if {@code newElements} is {@code null}
      * @throws IllegalArgumentException if any of {@code newElements} is found to
      * violate restrictions on the characteristics of valid elements
      * @see #addAll(Collection)
      */
     void addAll( Iterable<? extends E> newElements );
 
     /**
      * Removes the first element of this collection which is equivalent to the
      * given element.
      * <p/>
      * The elements are tested in the same order in which they would be enumerated by
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
      *
      * @param oldElement the element to remove
      * @return {@code true} if any removal occurred
      */
     boolean remove( E oldElement );
 
     /**
      * For each element in the given collection, removes the first element from this
      * collection which is equivalent to this element.
      * <p/>
      * The operation is defined to be equivalent to removing each element of {@code
      * oldElements} from this collection using {@link #remove(Object) remove} with the
      * element as the parameter.
      *
      * @param oldElements the elements to remove
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code oldElements} is {@code null}
      */
     boolean removeAll( Collection<? extends E> oldElements );
 
     /**
      * @param oldElements the elements to remove
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code oldElements} is {@code null}
      * @see #removeAll(Collection)
      */
     boolean removeAll( E[] oldElements );
 
     /**
      * @param oldElement first element to remove
      * @param restOfNewElements remainder of the elements to remove
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code restOfOldElements} is {@code null}
      * @see #removeAll(Collection)
      */
     boolean removeAll( E oldElement, E... restOfNewElements );
 
     /**
      * @param oldElements the elements to remove
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code oldElements} is {@code null}
      * @see #removeAll(Collection)
      */
     boolean removeAll( Iterable<? extends E> oldElements );
 
     /**
      * Removes each element of this collection which causes the given discriminator to
      * answer {@code true}.
      * <p/>
      * The elements are tested in the same order in which they would be enumerated by
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean removeIf( UnaryCondition<? super E> discriminator );
 
     /**
      * Removes each element of this collection that is not contained in the
      * given collection.
      * <p/>
      * Note that if the given collection is {@linkplain #isEmpty() empty}, this method
      * has the effect of "clearing" this collection.
      *
      * @param keepers the elements to retain
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code keepers} is {@code null}
      */
     boolean retainAll( Collection<? extends E> keepers );
 
     /**
      * @param keepers the elements to retain
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code keepers} is {@code null}
      * @see #retainAll(Collection)
      */
     boolean retainAll( E[] keepers );
 
     /**
      * @param keeper first element to retain
      * @param restOfKeepers remainder of the elements to retain
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code restOfKeepers} is {@code null}
      * @see #retainAll(Collection)
      */
     boolean retainAll( E keeper, E... restOfKeepers );
 
     /**
      * @see #retainAll(Collection)
      * @param keepers the elements to retain
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code keepers} is {@code null}
      */
     boolean retainAll( Iterable<? extends E> keepers );
 
     /**
      * Removes each element of this collection which causes the given discriminator to
      * answer {@code false}.
      * <p/>
      * The elements are tested in the same order in which they would be enumerated by
      * {@link #forEachDo(UnaryFunctor) forEachDo} for this collection.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean retainIf( UnaryCondition<? super E> discriminator );
 }

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		}