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 &quot;<a href="http://bit.ly/anMa4g"
021     *          target="_blank">Emulating 'self types' using Java Generics to simplify fluent API implementation</a>&quot;
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 &lt; 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 &lt; 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 &gt; 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 &gt; 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 &ne; 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 &ne; 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    }