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