001package io.ebean;
002
003/**
004 * Query by Example expression.
005 * <p>
006 * Pass in an example entity and for each non-null scalar properties an
007 * expression is added.
008 * </p>
009 * <p>
010 * By Default this case sensitive, will ignore numeric zero values and will use
011 * a Like for string values (you must put in your own wildcards).
012 * </p>
013 * <p>
014 * To get control over the options you can create an ExampleExpression and set
015 * those options such as case insensitive etc.
016 * </p>
017 *
018 * <pre>{@code
019 * // create an example bean and set the properties
020 * // with the query parameters you want
021 * Customer example = new Customer();
022 * example.setName("Rob%");
023 * example.setNotes("%something%");
024 *
025 * List<Customer> list =
026 *     DB.find(Customer.class)
027 *         .where()
028 *         // pass the bean into the where() clause
029 *         .exampleLike(example)
030 *         // you can add other expressions to the same query
031 *         .gt("id", 2)
032 *         .findList();
033 *
034 * }</pre>
035 *
036 * Similarly you can create an ExampleExpression
037 *
038 * <pre>{@code
039 *
040 * Customer example = new Customer();
041 * example.setName("Rob%");
042 * example.setNotes("%something%");
043 *
044 * // create a ExampleExpression with more control
045 * ExampleExpression qbe = new ExampleExpression(example, true, LikeType.EQUAL_TO)
046 *     .includeZeros();
047 *
048 * List<Customer> list =
049 *     DB.find(Customer.class)
050 *         .where()
051 *         .add(qbe)
052 *         .findList();
053 *
054 * }</pre>
055 */
056public interface ExampleExpression extends Expression {
057
058  /**
059   * By calling this method zero value properties are going to be included in
060   * the expression.
061   * <p>
062   * By default numeric zero values are excluded as they can result from
063   * primitive int and long types.
064   * </p>
065   */
066  ExampleExpression includeZeros();
067
068  /**
069   * Set case insensitive to true.
070   */
071  ExampleExpression caseInsensitive();
072
073  /**
074   * Use startsWith expression for string properties.
075   */
076  ExampleExpression useStartsWith();
077
078  /**
079   * Use contains expression for string properties.
080   */
081  ExampleExpression useContains();
082
083  /**
084   * Use endsWith expression for string properties.
085   */
086  ExampleExpression useEndsWith();
087
088  /**
089   * Use equal to expression for string properties.
090   */
091  ExampleExpression useEqualTo();
092
093}