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