001    /*
002     * Created on Oct 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.api;
016    
017    import java.util.Comparator;
018    import java.util.List;
019    
020    import org.fest.assertions.core.IndexedObjectEnumerableAssert;
021    import org.fest.assertions.data.Index;
022    import org.fest.assertions.internal.Lists;
023    import org.fest.util.ComparatorBasedComparisonStrategy;
024    import org.fest.util.VisibleForTesting;
025    
026    /**
027     * Assertion methods for <code>{@link List}</code>s.
028     * <p>
029     * To create an instance of this class, invoke <code>{@link Assertions#assertThat(List)}</code>.
030     * </p>
031     * 
032     * @author Yvonne Wang
033     * @author Alex Ruiz
034     * @author Joel Costigliola
035     */
036    // TODO inherits from IterableAssert and remove AbstractIterableAssert ? 
037    public class ListAssert extends AbstractIterableAssert<ListAssert, List<?>> implements IndexedObjectEnumerableAssert {
038    
039      @VisibleForTesting
040      Lists lists = Lists.instance();
041    
042      protected ListAssert(List<?> actual) {
043        super(actual, ListAssert.class);
044      }
045    
046      /** {@inheritDoc} */
047      public ListAssert contains(Object value, Index index) {
048        lists.assertContains(info, actual, value, index);
049        return this;
050      }
051    
052      /** {@inheritDoc} */
053      public ListAssert doesNotContain(Object value, Index index) {
054        lists.assertDoesNotContain(info, actual, value, index);
055        return this;
056      }
057    
058      /**
059       * Verifies that the actual list is sorted into ascending order according to the natural ordering of its elements.
060       * <p>
061       * All list elements must implement the {@link Comparable} interface and must be mutually comparable (that is,
062       * e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the list), examples :
063       * <ul>
064       * <li>a list composed of {"a1", "a2", "a3"} is ok because the element type (String) is Comparable</li>
065       * <li>a list composed of Rectangle {r1, r2, r3} is <b>NOT ok</b> because Rectangle is not Comparable</li>
066       * <li>a list composed of {True, "abc", False} is <b>NOT ok</b> because elements are not mutually comparable</li>
067       * </ul>
068       * Empty lists are considered sorted.</br> Unique element lists are considered sorted unless the element type is not
069       * Comparable.
070       * 
071       * @return {@code this} assertion object.
072       * 
073       * @throws AssertionError if the actual list is not sorted into ascending order according to the natural ordering of
074       *           its elements.
075       * @throws AssertionError if the actual list is <code>null</code>.
076       * @throws AssertionError if the actual list element type does not implement {@link Comparable}.
077       * @throws AssertionError if the actual list elements are not mutually {@link Comparable}.
078       */
079      public ListAssert isSorted() {
080        lists.assertIsSorted(info, actual); 
081        return this;
082      }
083    
084      /**
085       * Verifies that the actual list is sorted according to the given comparator.</br> Empty lists are considered sorted
086       * whatever the comparator is.</br> One element lists are considered sorted if element is compatible with comparator.
087       * 
088       * @param comparator the {@link Comparator} used to compare list elements
089       * 
090       * @return {@code this} assertion object.
091       * 
092       * @throws AssertionError if the actual list is not sorted according to the given comparator.
093       * @throws AssertionError if the actual list is <code>null</code>.
094       * @throws NullPointerException if the given comparator is <code>null</code>.
095       * @throws AssertionError if the actual list elements are not mutually comparabe according to given Comparator.
096       */
097      public ListAssert isSortedAccordingTo(Comparator<? extends Object> comparator) {
098        lists.assertIsSortedAccordingToComparator(info, actual, comparator);
099        return this;
100      }
101    
102      @Override
103      public ListAssert usingComparator(Comparator<?> customComparator) {
104        super.usingComparator(customComparator);
105        this.lists = new Lists(new ComparatorBasedComparisonStrategy(customComparator));
106        return myself;
107      }
108      
109      @Override
110      public ListAssert usingDefaultComparator() {
111        super.usingDefaultComparator();
112        this.lists = Lists.instance();
113        return myself;
114      }
115    }