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
020 * "<a href="http://bit.ly/anMa4g" target="_blank">Emulating 'self types' using Java Generics to simplify fluent
021 * API implementation</a>" 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 each element value satisfies the given condition
125 * @param condition the given condition.
126 * @return {@code this} object.
127 * @throws NullPointerException if the given condition is {@code null}.
128 * @throws AssertionError if a element cannot be cast to E.
129 * @throws AssertionError if one or more element not satisfy the given condition.
130 */
131 <E> S are(Condition<E> condition);
132
133
134 /**
135 * Verifies that each element value not satisfies the given condition
136 * @param condition the given condition.
137 * @return {@code this} object.
138 * @throws NullPointerException if the given condition is {@code null}.
139 * @throws AssertionError if a element cannot be cast to E.
140 * @throws AssertionError if one or more element satisfy the given condition.
141 */
142 <E> S areNot(Condition<E> condition);
143
144 /**
145 * Verifies that each element value satisfies the given condition
146 * @param condition the given condition.
147 * @return {@code this} object.
148 * @throws NullPointerException if the given condition is {@code null}.
149 * @throws AssertionError if a element cannot be cast to E.
150 * @throws AssertionError if one or more element not satisfy the given condition.
151 */
152 <E> S have(Condition<E> condition);
153
154
155 /**
156 * Verifies that each element value not satisfies the given condition
157 * @param condition the given condition.
158 * @return {@code this} object.
159 * @throws NullPointerException if the given condition is {@code null}.
160 * @throws AssertionError if a element cannot be cast to E.
161 * @throws AssertionError if one or more element satisfy the given condition.
162 */
163 <E> S doNotHave(Condition<E> condition);
164
165 /**
166 * Verifies that there is <b>at least</b> <i>n</i> elements in the actual group satisfying the given condition.
167 * @param n the minimum number of times the condition should be verified.
168 * @param condition the given condition.
169 * @return {@code this} object.
170 * @throws NullPointerException if the given condition is {@code null}.
171 * @throws AssertionError if an element can not be cast to E.
172 * @throws AssertionError if the number of elements satisfying the given condition is < n.
173 */
174 <E> S areAtLeast(int n, Condition<E> condition);
175
176 /**
177 * Verifies that there is <b>at least</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given condition.
178 * @param n the number of times the condition should not be verified at least.
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 the number of elements not satisfying the given condition is < n.
184 */
185 <E> S areNotAtLeast(int n, Condition<E> condition);
186
187 /**
188 * Verifies that there is <b>at most</b> <i>n</i> elements in the actual group satisfying the given condition.
189 * @param n the number of times the condition should be at most 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 a element cannot be cast to E.
194 * @throws AssertionError if the number of elements satisfying the given condition is > n.
195 */
196 <E> S areAtMost(int n, Condition<E> condition);
197
198 /**
199 * Verifies that there is <b>at most</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given condition.
200 * @param n the number of times the condition should not be verified at most.
201 * @param condition the given condition.
202 * @return {@code this} object.
203 * @throws NullPointerException if the given condition is {@code null}.
204 * @throws AssertionError if a element cannot be cast to E.
205 * @throws AssertionError if the number of elements not satisfying the given condition is > n.
206 */
207 <E> S areNotAtMost(int n, Condition<E> condition);
208
209 /**
210 * Verifies that there is <b>exactly</b> <i>n</i> elements in the actual group satisfying the given condition.
211 * @param n the exact number of times the condition should be verified.
212 * @param condition the given condition.
213 * @return {@code this} object.
214 * @throws NullPointerException if the given condition is {@code null}.
215 * @throws AssertionError if a element cannot be cast to E.
216 * @throws AssertionError if the number of elements satisfying the given condition is ≠ n.
217 */
218 <E> S areExactly(int n, Condition<E> condition);
219
220 /**
221 * Verifies that there is <b>exactly</b> <i>n</i> elements in the actual group <b>not</b> satisfying the given condition.
222 * @param n the exact number of times the condition should not be verified.
223 * @param condition the given condition.
224 * @return {@code this} object.
225 * @throws NullPointerException if the given condition is {@code null}.
226 * @throws AssertionError if a element cannot be cast to E.
227 * @throws AssertionError if the number of elements not satisfying the given condition is ≠ n.
228 */
229 <E> S areNotExactly(int n, Condition<E> condition);
230
231 /**
232 * This method is an alias for {@link #areAtLeast(int, Condition)}.
233 */
234 <E> S haveAtLeast(int n, Condition<E> condition);
235
236 /**
237 * This method is an alias {@link #areNotAtLeast(int, Condition)}.
238 */
239 <E> S doNotHaveAtLeast(int n, Condition<E> condition);
240
241 /**
242 * This method is an alias {@link #areAtMost(int, Condition)}.
243 */
244 <E> S haveAtMost(int n, Condition<E> condition);
245
246 /**
247 * This method is an alias {@link #areNotAtMost(int, Condition)}.
248 */
249 <E> S doNotHaveAtMost(int n, Condition<E> condition);
250
251 /**
252 * This method is an alias {@link #areExactly(int, Condition)}.
253 */
254 <E> S haveExactly(int n, Condition<E> condition);
255
256 /**
257 * This method is an alias {@link #areNotExactly(int, Condition)}.
258 */
259 <E> S doNotHaveExactly(int n, Condition<E> condition);
260
261 }