001    /*
002     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
003     * the License. You may obtain a copy of the License at
004     * 
005     * http://www.apache.org/licenses/LICENSE-2.0
006     * 
007     * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
008     * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
009     * specific language governing permissions and limitations under the License.
010     * 
011     * Copyright @2010-2011 the original author or authors.
012     */
013    package org.fest.util;
014    
015    /**
016     * Describes the contract to implement a <b>consistent</b> comparison strategy that covers :<br>
017     * - comparing two objects for equality and order<br>
018     * - knowing if an object belongs to a group of objects (collection/array)<br>
019     * - determining duplicates in a group of objects (collection/array)<br>
020     * - string specific comparison<br>
021     * 
022     * @author Joel Costigliola
023     */
024    public interface ComparisonStrategy {
025    
026      /**
027       * Returns true if actual and other are equal according to the implemented comparison strategy.
028       * 
029       * @param actual the object to compare to other
030       * @param other the object to compare to actual
031       * @return true if actual and other are equal according to the underlying comparison strategy.
032       */
033      boolean areEqual(Object actual, Object other);
034    
035      /**
036       * Returns true if actual is greater than other, false otherwise.
037       * 
038       * @param actual the object to compare to other
039       * @param other the object to compare to actual
040       * @return true if actual is greater than other, false otherwise.
041       * @throws UnsupportedOperationException if operation is not supported by a concrete implementation.
042       */
043      boolean isGreaterThan(Object actual, Object other);
044    
045      /**
046       * Returns true if actual is greater than or equal to other, false otherwise.
047       * 
048       * @param actual the object to compare to other
049       * @param other the object to compare to actual
050       * @return true if actual is greater than or equal to other, false otherwise.
051       * @throws UnsupportedOperationException if operation is not supported by a concrete implementation.
052       */
053      boolean isGreaterThanOrEqualTo(Object actual, Object other);
054    
055      /**
056       * Returns true if actual is less than other, false otherwise.
057       * 
058       * @param actual the object to compare to other
059       * @param other the object to compare to actual
060       * @return true if actual is less than other, false otherwise.
061       * @throws UnsupportedOperationException if operation is not supported by a concrete implementation.
062       */
063      boolean isLessThan(Object actual, Object other);
064    
065      /**
066       * Returns true if actual is less than or equal to other, false otherwise.
067       * 
068       * @param actual the object to compare to other
069       * @param other the object to compare to actual
070       * @return true if actual is less than or equal to other, false otherwise.
071       * @throws UnsupportedOperationException if operation is not supported by a concrete implementation.
072       */
073      boolean isLessThanOrEqualTo(Object actual, Object other);
074    
075      /**
076       * Returns true if given {@link Iterable} contains given value according to the implemented comparison strategy, false
077       * otherwise.<br>
078       * If given {@link Iterable} is null, return false.
079       * 
080       * @param collection the {@link Iterable} to search value in
081       * @param value the object to look for in given {@link Iterable}
082       * @return true if given {@link Iterable} contains given value according to the implemented comparison strategy, false
083       *         otherwise.
084       */
085      boolean iterableContains(Iterable<?> collection, Object value);
086    
087      /**
088       * Look for given value in given {@link Iterable} according to the implemented comparison strategy, if value is found
089       * it is removed from it.<br>
090       * If given {@link Iterable} is null, does nothing.
091       * 
092       * @param iterable the {@link Iterable} we want remove value from
093       * @param value object to remove from given {@link Iterable}
094       */
095      void iterableRemoves(Iterable<?> iterable, Object value);
096    
097      /**
098       * Returns any duplicate elements from the given {@link Iterable} according to the implemented comparison strategy.
099       * 
100       * @param iterable the given {@link Iterable} we want to extract duplicate elements.
101       * @return an {@link Iterable} containing the duplicate elements of the given one. If no duplicates are found, an
102       *         empty {@link Iterable} is returned.
103       */
104      Iterable<?> duplicatesFrom(Iterable<?> iterable);
105    
106      /**
107       * Returns true if given array contains given value according to the implemented comparison strategy, false otherwise.
108       * 
109       * @param array the array to search value in (must not be null)
110       * @param value the object to look for in given array
111       * @return true if given array contains given value according to the implemented comparison strategy, false otherwise.
112       */
113      boolean arrayContains(Object array, Object value);
114    
115      /**
116       * Returns true if given string contains given sequence according to the implemented comparison strategy, false
117       * otherwise.
118       * 
119       * @param string the string to search sequence in (must not be null)
120       * @param sequence the String to look for in given string
121       * @return true if given string contains given sequence according to the implemented comparison strategy, false
122       *         otherwise.
123       */
124      boolean stringContains(String string, String sequence);
125    
126      /**
127       * Returns true if string starts with prefix according to the implemented comparison strategy, false otherwise.
128       * 
129       * @param string the String we want to look starting prefix
130       * @param prefix the prefix String to look for at string's start
131       * @return true if string starts with prefix according to the implemented comparison strategy, false otherwise.
132       */
133      boolean stringStartsWith(String string, String prefix);
134    
135      /**
136       * Returns true if sstring ends with suffix according to the implemented comparison strategy, false otherwise.
137       * 
138       * @param string the String we want to look starting suffix
139       * @param suffix the suffix String to look for at string's end
140       * @return true if string ends with suffix according to the implemented comparison strategy, false otherwise.
141       */
142      boolean stringEndsWith(String string, String suffix);
143    
144    }