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 }