001package io.ebean;
002
003import java.util.List;
004import java.util.Set;
005
006/**
007 * Provides support for filtering and sorting lists of entities without going
008 * back to the database.
009 * <p>
010 * That is, it uses local in-memory sorting and filtering of a list of entity
011 * beans. It is not used in a Database query or invoke a Database query.
012 * </p>
013 * <p>
014 * You can optionally specify a sortByClause and if so, the sort will always
015 * execute prior to the filter expressions. You can specify any number of filter
016 * expressions and they are effectively joined by logical "AND".
017 * </p>
018 * <p>
019 * The result of the filter method will leave the original list unmodified and
020 * return a new List instance.
021 * </p>
022 * <p>
023 * <pre>{@code
024 *
025 * // get a list of entities (query execution statistics in this case)
026 *
027 * List<MetaQueryStatistic> list =
028 *     DB.find(MetaQueryStatistic.class).findList();
029 *
030 * long nowMinus24Hrs = System.currentTimeMillis() - 24 * (1000 * 60 * 60);
031 *
032 * // sort and filter the list returning a filtered list...
033 *
034 * List<MetaQueryStatistic> filteredList =
035 *     DB.filter(MetaQueryStatistic.class)
036 *         .sort("avgTimeMicros desc")
037 *         .gt("executionCount", 0)
038 *         .gt("lastQueryTime", nowMinus24Hrs)
039 *         .eq("autoTuned", true)
040 *         .maxRows(10)
041 *         .filter(list);
042 *
043 * }</pre>
044 * <p>
045 * The propertyNames can traverse the object graph (e.g. customer.name) by using
046 * dot notation. If any point during the object graph traversal to get a
047 * property value is null then null is returned.
048 * </p>
049 * <p>
050 * <pre>{@code
051 *
052 * // examples of property names that
053 * // ... will traverse the object graph
054 * // ... where customer is a property of our bean
055 *
056 * customer.name
057 * customer.shippingAddress.city
058 *
059 * }</pre>
060 * <p>
061 * <pre>{@code
062 *
063 * // get a list of entities (query execution statistics)
064 *
065 * List<Order> orders =
066 *     DB.find(Order.class).findList();
067 *
068 * // Apply a filter...
069 *
070 * List<Order> filteredOrders =
071 *     DB.filter(Order.class)
072 *         .startsWith("customer.name", "Rob")
073 *         .eq("customer.shippingAddress.city", "Auckland")
074 *         .filter(orders);
075 *
076 * }</pre>
077 *
078 * @param <T> the entity bean type
079 */
080public interface Filter<T> {
081
082  /**
083   * Specify a sortByClause.
084   * <p>
085   * The sort (if specified) will always execute first followed by the filter
086   * expressions.
087   * </p>
088   * <p>
089   * Refer to {@link DB#sort(List, String)} for more detail.
090   * </p>
091   */
092  Filter<T> sort(String sortByClause);
093
094  /**
095   * Specify the maximum number of rows/elements to return.
096   */
097  Filter<T> maxRows(int maxRows);
098
099  /**
100   * Equal To - property equal to the given value.
101   */
102  Filter<T> eq(String prop, Object value);
103
104  /**
105   * Not Equal To - property not equal to the given value.
106   */
107  Filter<T> ne(String propertyName, Object value);
108
109  /**
110   * Case Insensitive Equal To.
111   */
112  Filter<T> ieq(String propertyName, String value);
113
114  /**
115   * Between - property between the two given values.
116   */
117  Filter<T> between(String propertyName, Object value1, Object value2);
118
119  /**
120   * Greater Than - property greater than the given value.
121   */
122  Filter<T> gt(String propertyName, Object value);
123
124  /**
125   * Greater Than or Equal to - property greater than or equal to the given
126   * value.
127   */
128  Filter<T> ge(String propertyName, Object value);
129
130  /**
131   * Less Than - property less than the given value.
132   */
133  Filter<T> lt(String propertyName, Object value);
134
135  /**
136   * Less Than or Equal to - property less than or equal to the given value.
137   */
138  Filter<T> le(String propertyName, Object value);
139
140  /**
141   * Is Null - property is null.
142   */
143  Filter<T> isNull(String propertyName);
144
145  /**
146   * Is Not Null - property is not null.
147   */
148  Filter<T> isNotNull(String propertyName);
149
150  /**
151   * Starts With.
152   */
153  Filter<T> startsWith(String propertyName, String value);
154
155  /**
156   * Case insensitive Starts With.
157   */
158  Filter<T> istartsWith(String propertyName, String value);
159
160  /**
161   * Ends With.
162   */
163  Filter<T> endsWith(String propertyName, String value);
164
165  /**
166   * Case insensitive Ends With.
167   */
168  Filter<T> iendsWith(String propertyName, String value);
169
170  /**
171   * Contains - property contains the string "value".
172   */
173  Filter<T> contains(String propertyName, String value);
174
175  /**
176   * Case insensitive Contains.
177   */
178  Filter<T> icontains(String propertyName, String value);
179
180  /**
181   * In - property has a value contained in the set of values.
182   */
183  Filter<T> in(String propertyName, Set<?> values);
184
185  /**
186   * Apply the filter to the list returning a new list of the matching elements
187   * in the sorted order.
188   * <p>
189   * The sourceList will remain unmodified.
190   * </p>
191   *
192   * @return Returns a new list with the sorting and filters applied.
193   */
194  List<T> filter(List<T> sourceList);
195
196}