001 /*
002 * Created on Jul 26, 2010
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
005 * the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
010 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
011 * specific language governing permissions and limitations under the License.
012 *
013 * Copyright @2010-2011 the original author or authors.
014 */
015 package org.fest.assertions.core;
016
017
018 /**
019 * Assertions methods applicable to groups of objects (e.g. arrays or collections.)
020 * @param <S> the "self" type of this assertion class. Please read "<a href="http://bit.ly/anMa4g"
021 * target="_blank">Emulating 'self types' using Java Generics to simplify fluent API implementation</a>"
022 * for more details.
023 * @param <T> the type of elements of the "actual" value.
024 *
025 * @author Yvonne Wang
026 * @author Alex Ruiz
027 * @author Nicolas François
028 * @author Mikhail Mazursky
029 * @author Joel Costigliola
030 */
031 public interface ObjectEnumerableAssert<S, T> extends EnumerableAssert<S, T> {
032
033 /**
034 * Verifies that the actual group contains the given values, in any order.
035 * @param values the given values.
036 * @return {@code this} assertion object.
037 * @throws NullPointerException if the given argument is {@code null}.
038 * @throws IllegalArgumentException if the given argument is an empty array.
039 * @throws AssertionError if the actual group is {@code null}.
040 * @throws AssertionError if the actual group does not contain the given values.
041 */
042 S contains(T... values);
043
044 /**
045 * Verifies that the actual group contains only the given values and nothing else, in any order.
046 * @param values the given values.
047 * @return {@code this} assertion object.
048 * @throws NullPointerException if the given argument is {@code null}.
049 * @throws IllegalArgumentException if the given argument is an empty array.
050 * @throws AssertionError if the actual group is {@code null}.
051 * @throws AssertionError if the actual group does not contain the given values, i.e. the actual group contains some
052 * or none of the given values, or the actual group contains more values than the given ones.
053 */
054 S containsOnly(T... values);
055
056 /**
057 * Verifies that the actual group contains the given sequence, without any other values between them.
058 * @param sequence the sequence of objects to look for.
059 * @return this assertion object.
060 * @throws AssertionError if the actual group is {@code null}.
061 * @throws AssertionError if the given array is {@code null}.
062 * @throws AssertionError if the actual group does not contain the given sequence.
063 */
064 S containsSequence(T... sequence);
065
066 /**
067 * Verifies that the actual group does not contain the given values.
068 * @param values the given values.
069 * @return {@code this} assertion object.
070 * @throws NullPointerException if the given argument is {@code null}.
071 * @throws IllegalArgumentException if the given argument is an empty array.
072 * @throws AssertionError if the actual group is {@code null}.
073 * @throws AssertionError if the actual group contains any of the given values.
074 */
075 S doesNotContain(T... values);
076
077 /**
078 * Verifies that the actual group does not contain duplicates.
079 * @return {@code this} assertion object.
080 * @throws AssertionError if the actual group is {@code null}.
081 * @throws AssertionError if the actual group contains duplicates.
082 */
083 S doesNotHaveDuplicates();
084
085 /**
086 * Verifies that the actual group starts with the given sequence of objects, without any other objects between them.
087 * Similar to <code>{@link #containsSequence(Object...)}</code>, but it also verifies that the first element in the
088 * sequence is also first element of the actual group.
089 * @param sequence the sequence of objects to look for.
090 * @return this assertion object.
091 * @throws NullPointerException if the given argument is {@code null}.
092 * @throws IllegalArgumentException if the given argument is an empty array.
093 * @throws AssertionError if the actual group is {@code null}.
094 * @throws AssertionError if the actual group does not start with the given sequence of objects.
095 */
096 S startsWith(T... sequence);
097
098 /**
099 * Verifies that the actual group ends with the given sequence of objects, without any other objects between them.
100 * Similar to <code>{@link #containsSequence(Object...)}</code>, but it also verifies that the last element in the
101 * sequence is also last element of the actual group.
102 * @param sequence the sequence of objects to look for.
103 * @return this assertion object.
104 * @throws NullPointerException if the given argument is {@code null}.
105 * @throws IllegalArgumentException if the given argument is an empty array.
106 * @throws AssertionError if the actual group is {@code null}.
107 * @throws AssertionError if the actual group does not end with the given sequence of objects.
108 */
109 S endsWith(T... sequence);
110
111 /**
112 * Verifies that the actual group contains at least a null element.
113 * @return {@code this} assertion object.
114 * @throws AssertionError if the actual group is {@code null}.
115 * @throws AssertionError if the actual group does not contain a null element.
116 */
117 S containsNull();
118
119 /**
120 * Verifies that the actual group does not contain null elements.
121 * @return {@code this} assertion object.
122 * @throws AssertionError if the actual group is {@code null}.
123 * @throws AssertionError if the actual group contains a null element.
124 */
125 S doesNotContainNull();
126
127 /**
128 * Verifies that the actual group has the same size as given array.
129 * @param other the array to compare size with actual group.
130 * @return {@code this} assertion object.
131 * @throws AssertionError if the actual group is {@code null}.
132 * @throws AssertionError if the other array is {@code null}.
133 * @throws AssertionError if actual group and given array don't have the same size.
134 */
135 S hasSameSizeAs(Object[] other);
136
137 /**
138 * Verifies that the actual group has the same size as given {@link Iterable}.
139 * @param other the {@code Iterable} to compare size with actual group.
140 * @return {@code this} assertion object.
141 * @throws AssertionError if the actual group is {@code null}.
142 * @throws AssertionError if the other {@code Iterable} is {@code null}.
143 * @throws AssertionError if actual group and given {@code Iterable} don't have the same size.
144 */
145 S hasSameSizeAs(Iterable<?> other);
146
147 /**
148 * Verifies that each element value satisfies the given condition
149 * @param condition the given condition.
150 * @return {@code this} object.
151 * @throws NullPointerException if the given condition is {@code null}.
152 * @throws AssertionError if a element cannot be cast to E.
153 * @throws AssertionError if one or more element not satisfy the given condition.
154 */
155 <E> S are(Condition<E> condition);
156
157 /**
158 * Verifies that each element value not satisfies the given condition
159 * @param condition the given condition.
160 * @return {@code this} object.
161 * @throws NullPointerException if the given condition is {@code null}.
162 * @throws AssertionError if a element cannot be cast to E.
163 * @throws AssertionError if one or more element satisfy the given condition.
164 */
165 <E> S areNot(Condition<E> condition);
166
167 /**
168 * Verifies that each element value satisfies the given condition
169 * @param condition the given condition.
170 * @return {@code this} object.
171 * @throws NullPointerException if the given condition is {@code null}.
172 * @throws AssertionError if a element cannot be cast to E.
173 * @throws AssertionError if one or more element not satisfy the given condition.
174 */
175 <E> S have(Condition<E> condition);
176
177 /**
178 * Verifies that each element value not satisfies the given condition
179 * @param condition the given condition.
180 * @return {@code this} object.
181 * @throws NullPointerException if the given condition is {@code null}.
182 * @throws AssertionError if a element cannot be cast to E.
183 * @throws AssertionError if one or more element satisfy the given condition.
184 */
185 <E> S doNotHave(Condition<E> condition);
186
187 /**
188 * Verifies that there is <b>at least</b> <i>n</i> elements in the actual group satisfying the given condition.
189 * @param n the minimum number of times the condition should be verified.
190 * @param condition the given condition.
191 * @return {@code this} object.
192 * @throws NullPointerException if the given condition is {@code null}.
193 * @throws AssertionError if an element can not be cast to E.
194 * @throws AssertionError if the number of elements satisfying the given condition is < n.
195 */
196 <E> S areAtLeast(int n, Condition<E> condition);
197
198 /**
199 * Verifies that there is <b>at least</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given
200 * condition.
201 * @param n the number of times the condition should not be verified at least.
202 * @param condition the given condition.
203 * @return {@code this} object.
204 * @throws NullPointerException if the given condition is {@code null}.
205 * @throws AssertionError if a element cannot be cast to E.
206 * @throws AssertionError if the number of elements not satisfying the given condition is < n.
207 */
208 <E> S areNotAtLeast(int n, Condition<E> condition);
209
210 /**
211 * Verifies that there is <b>at most</b> <i>n</i> elements in the actual group satisfying the given condition.
212 * @param n the number of times the condition should be at most verified.
213 * @param condition the given condition.
214 * @return {@code this} object.
215 * @throws NullPointerException if the given condition is {@code null}.
216 * @throws AssertionError if a element cannot be cast to E.
217 * @throws AssertionError if the number of elements satisfying the given condition is > n.
218 */
219 <E> S areAtMost(int n, Condition<E> condition);
220
221 /**
222 * Verifies that there is <b>at most</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given
223 * condition.
224 * @param n the number of times the condition should not be verified at most.
225 * @param condition the given condition.
226 * @return {@code this} object.
227 * @throws NullPointerException if the given condition is {@code null}.
228 * @throws AssertionError if a element cannot be cast to E.
229 * @throws AssertionError if the number of elements not satisfying the given condition is > n.
230 */
231 <E> S areNotAtMost(int n, Condition<E> condition);
232
233 /**
234 * Verifies that there is <b>exactly</b> <i>n</i> elements in the actual group satisfying the given condition.
235 * @param n the exact number of times the condition should be verified.
236 * @param condition the given condition.
237 * @return {@code this} object.
238 * @throws NullPointerException if the given condition is {@code null}.
239 * @throws AssertionError if a element cannot be cast to E.
240 * @throws AssertionError if the number of elements satisfying the given condition is ≠ n.
241 */
242 <E> S areExactly(int n, Condition<E> condition);
243
244 /**
245 * Verifies that there is <b>exactly</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given
246 * condition.
247 * @param n the exact number of times the condition should not be verified.
248 * @param condition the given condition.
249 * @return {@code this} object.
250 * @throws NullPointerException if the given condition is {@code null}.
251 * @throws AssertionError if a element cannot be cast to E.
252 * @throws AssertionError if the number of elements not satisfying the given condition is ≠ n.
253 */
254 <E> S areNotExactly(int n, Condition<E> condition);
255
256 /**
257 * This method is an alias for {@link #areAtLeast(int, Condition)}.
258 */
259 <E> S haveAtLeast(int n, Condition<E> condition);
260
261 /**
262 * This method is an alias {@link #areNotAtLeast(int, Condition)}.
263 */
264 <E> S doNotHaveAtLeast(int n, Condition<E> condition);
265
266 /**
267 * This method is an alias {@link #areAtMost(int, Condition)}.
268 */
269 <E> S haveAtMost(int n, Condition<E> condition);
270
271 /**
272 * This method is an alias {@link #areNotAtMost(int, Condition)}.
273 */
274 <E> S doNotHaveAtMost(int n, Condition<E> condition);
275
276 /**
277 * This method is an alias {@link #areExactly(int, Condition)}.
278 */
279 <E> S haveExactly(int n, Condition<E> condition);
280
281 /**
282 * This method is an alias {@link #areNotExactly(int, Condition)}.
283 */
284 <E> S doNotHaveExactly(int n, Condition<E> condition);
285
286 /**
287 * Verifies that the actual group contains all the elements of given {@code Iterable}, in any order.
288 * @param iterable the given {@code Iterable} we will get elements from.
289 * @return {@code this} assertion object.
290 * @throws NullPointerException if the given argument is {@code null}.
291 * @throws AssertionError if the actual group is {@code null}.
292 * @throws AssertionError if the actual group does not contain all the elements of given {@code Iterable}.
293 */
294 S containsAll(Iterable<? extends T> iterable);
295
296 }