001package com.avaje.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 class="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(&quot;Rob%&quot;);
023 * example.setNotes(&quot;%something%&quot;);
024 * 
025 * List&lt;Customer&gt; list =
026 *     Ebean.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(&quot;id&quot;, 2)
032 *         .findList();
033 * 
034 * </pre>
035 * 
036 * Similarly you can create an ExampleExpression
037 * 
038 * <pre>
039 * Customer example = new Customer();
040 * example.setName(&quot;Rob%&quot;);
041 * example.setNotes(&quot;%something%&quot;);
042 * 
043 * // create a ExampleExpression with more control
044 * ExampleExpression qbe = new ExampleExpression(example, true, LikeType.EQUAL_TO)
045 *     .includeZeros();
046 * 
047 * List&lt;Customer&gt; list =
048 *     Ebean.find(Customer.class)
049 *         .where()
050 *         .add(qbe)
051 *         .findList();
052 * </pre>
053 * 
054 * @author Rob Bygrave
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}