Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ExtensibleCollection |
|
| 0.0;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 | } |