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