001package com.avaje.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 * 
023 * <pre class="code">
024 * 
025 * // get a list of entities (query execution statistics in this case)
026 * 
027 * List&lt;MetaQueryStatistic&gt; list =
028 *     Ebean.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&lt;MetaQueryStatistic&gt; filteredList =
035 *     Ebean.filter(MetaQueryStatistic.class)
036 *         .sort(&quot;avgTimeMicros desc&quot;)
037 *         .gt(&quot;executionCount&quot;, 0)
038 *         .gt(&quot;lastQueryTime&quot;, nowMinus24Hrs)
039 *         .eq(&quot;autoTuned&quot;, 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 * 
050 * <pre>
051 * // examples of property names that 
052 * // ... will traverse the object graph
053 * // ... where customer is a property of our bean
054 * 
055 * customer.name
056 * customer.shippingAddress.city
057 * </pre>
058 * 
059 * </p>
060 * 
061 * <pre class="code">
062 * 
063 * // get a list of entities (query execution statistics)
064 * 
065 * List&lt;Order&gt; orders =
066 *     Ebean.find(Order.class).findList();
067 * 
068 * // Apply a filter...
069 * 
070 * List&lt;Order&gt; filteredOrders =
071 *     Ebean.filter(Order.class)
072 *         .startsWith(&quot;customer.name&quot;, &quot;Rob&quot;)
073 *         .eq(&quot;customer.shippingAddress.city&quot;, &quot;Auckland&quot;)
074 *         .filter(orders);
075 * 
076 * </pre>
077 * 
078 * @param <T>
079 *          the entity bean type
080 */
081public interface Filter<T> {
082
083  /**
084   * Specify a sortByClause.
085   * <p>
086   * The sort (if specified) will always execute first followed by the filter
087   * expressions.
088   * </p>
089   * <p>
090   * Refer to {@link Ebean#sort(List, String)} for more detail.
091   * </p>
092   */
093  Filter<T> sort(String sortByClause);
094
095  /**
096   * Specify the maximum number of rows/elements to return.
097   */
098  Filter<T> maxRows(int maxRows);
099
100  /**
101   * Equal To - property equal to the given value.
102   */
103  Filter<T> eq(String prop, Object value);
104
105  /**
106   * Not Equal To - property not equal to the given value.
107   */
108  Filter<T> ne(String propertyName, Object value);
109
110  /**
111   * Case Insensitive Equal To.
112   */
113  Filter<T> ieq(String propertyName, String value);
114
115  /**
116   * Between - property between the two given values.
117   */
118  Filter<T> between(String propertyName, Object value1, Object value2);
119
120  /**
121   * Greater Than - property greater than the given value.
122   */
123  Filter<T> gt(String propertyName, Object value);
124
125  /**
126   * Greater Than or Equal to - property greater than or equal to the given
127   * value.
128   */
129  Filter<T> ge(String propertyName, Object value);
130
131  /**
132   * Less Than - property less than the given value.
133   */
134  Filter<T> lt(String propertyName, Object value);
135
136  /**
137   * Less Than or Equal to - property less than or equal to the given value.
138   */
139  Filter<T> le(String propertyName, Object value);
140
141  /**
142   * Is Null - property is null.
143   */
144  Filter<T> isNull(String propertyName);
145
146  /**
147   * Is Not Null - property is not null.
148   */
149  Filter<T> isNotNull(String propertyName);
150
151  /**
152   * Starts With.
153   */
154  Filter<T> startsWith(String propertyName, String value);
155
156  /**
157   * Case insensitive Starts With.
158   */
159  Filter<T> istartsWith(String propertyName, String value);
160
161  /**
162   * Ends With.
163   */
164  Filter<T> endsWith(String propertyName, String value);
165
166  /**
167   * Case insensitive Ends With.
168   */
169  Filter<T> iendsWith(String propertyName, String value);
170
171  /**
172   * Contains - property contains the string "value".
173   */
174  Filter<T> contains(String propertyName, String value);
175
176  /**
177   * Case insensitive Contains.
178   */
179  Filter<T> icontains(String propertyName, String value);
180
181  /**
182   * In - property has a value contained in the set of values.
183   */
184  Filter<T> in(String propertyName, Set<?> values);
185
186  /**
187   * Apply the filter to the list returning a new list of the matching elements
188   * in the sorted order.
189   * <p>
190   * The sourceList will remain unmodified.
191   * </p>
192   * 
193   * @return Returns a new list with the sorting and filters applied.
194   */
195  List<T> filter(List<T> sourceList);
196
197}