Filter.java

package io.ebean;

import java.util.List;
import java.util.Set;

/**
 * Provides support for filtering and sorting lists of entities without going
 * back to the database.
 * <p>
 * That is, it uses local in-memory sorting and filtering of a list of entity
 * beans. It is not used in a Database query or invoke a Database query.
 * </p>
 * <p>
 * You can optionally specify a sortByClause and if so, the sort will always
 * execute prior to the filter expressions. You can specify any number of filter
 * expressions and they are effectively joined by logical "AND".
 * </p>
 * <p>
 * The result of the filter method will leave the original list unmodified and
 * return a new List instance.
 * </p>
 * <p>
 * <pre>{@code
 *
 * // get a list of entities (query execution statistics in this case)
 *
 * List<MetaQueryStatistic> list =
 *     Ebean.find(MetaQueryStatistic.class).findList();
 *
 * long nowMinus24Hrs = System.currentTimeMillis() - 24 * (1000 * 60 * 60);
 *
 * // sort and filter the list returning a filtered list...
 *
 * List<MetaQueryStatistic> filteredList =
 *     Ebean.filter(MetaQueryStatistic.class)
 *         .sort("avgTimeMicros desc")
 *         .gt("executionCount", 0)
 *         .gt("lastQueryTime", nowMinus24Hrs)
 *         .eq("autoTuned", true)
 *         .maxRows(10)
 *         .filter(list);
 *
 * }</pre>
 * <p>
 * The propertyNames can traverse the object graph (e.g. customer.name) by using
 * dot notation. If any point during the object graph traversal to get a
 * property value is null then null is returned.
 * </p>
 * <p>
 * <pre>{@code
 *
 * // examples of property names that
 * // ... will traverse the object graph
 * // ... where customer is a property of our bean
 *
 * customer.name
 * customer.shippingAddress.city
 *
 * }</pre>
 * <p>
 * <pre>{@code
 *
 * // get a list of entities (query execution statistics)
 *
 * List<Order> orders =
 *     Ebean.find(Order.class).findList();
 *
 * // Apply a filter...
 *
 * List<Order> filteredOrders =
 *     Ebean.filter(Order.class)
 *         .startsWith("customer.name", "Rob")
 *         .eq("customer.shippingAddress.city", "Auckland")
 *         .filter(orders);
 *
 * }</pre>
 *
 * @param <T> the entity bean type
 */
public interface Filter<T> {

  /**
   * Specify a sortByClause.
   * <p>
   * The sort (if specified) will always execute first followed by the filter
   * expressions.
   * </p>
   * <p>
   * Refer to {@link Ebean#sort(List, String)} for more detail.
   * </p>
   */
  Filter<T> sort(String sortByClause);

  /**
   * Specify the maximum number of rows/elements to return.
   */
  Filter<T> maxRows(int maxRows);

  /**
   * Equal To - property equal to the given value.
   */
  Filter<T> eq(String prop, Object value);

  /**
   * Not Equal To - property not equal to the given value.
   */
  Filter<T> ne(String propertyName, Object value);

  /**
   * Case Insensitive Equal To.
   */
  Filter<T> ieq(String propertyName, String value);

  /**
   * Between - property between the two given values.
   */
  Filter<T> between(String propertyName, Object value1, Object value2);

  /**
   * Greater Than - property greater than the given value.
   */
  Filter<T> gt(String propertyName, Object value);

  /**
   * Greater Than or Equal to - property greater than or equal to the given
   * value.
   */
  Filter<T> ge(String propertyName, Object value);

  /**
   * Less Than - property less than the given value.
   */
  Filter<T> lt(String propertyName, Object value);

  /**
   * Less Than or Equal to - property less than or equal to the given value.
   */
  Filter<T> le(String propertyName, Object value);

  /**
   * Is Null - property is null.
   */
  Filter<T> isNull(String propertyName);

  /**
   * Is Not Null - property is not null.
   */
  Filter<T> isNotNull(String propertyName);

  /**
   * Starts With.
   */
  Filter<T> startsWith(String propertyName, String value);

  /**
   * Case insensitive Starts With.
   */
  Filter<T> istartsWith(String propertyName, String value);

  /**
   * Ends With.
   */
  Filter<T> endsWith(String propertyName, String value);

  /**
   * Case insensitive Ends With.
   */
  Filter<T> iendsWith(String propertyName, String value);

  /**
   * Contains - property contains the string "value".
   */
  Filter<T> contains(String propertyName, String value);

  /**
   * Case insensitive Contains.
   */
  Filter<T> icontains(String propertyName, String value);

  /**
   * In - property has a value contained in the set of values.
   */
  Filter<T> in(String propertyName, Set<?> values);

  /**
   * Apply the filter to the list returning a new list of the matching elements
   * in the sorted order.
   * <p>
   * The sourceList will remain unmodified.
   * </p>
   *
   * @return Returns a new list with the sorting and filters applied.
   */
  List<T> filter(List<T> sourceList);

}