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