001package com.avaje.ebean;
002
003/**
004 * An update query typically intended to perform a bulk update of many rows that match the query.
005 * <p>
006 * Also note that you can also just use a raw SQL update via {@link SqlUpdate} which is pretty light and simple.
007 * This UpdateQuery is more for the cases where we want to build the where expression of the update using the
008 * {@link ExpressionList} "Criteria API" that is used with a normal ORM query.
009 * </p>
010 *
011 * <h4>Example: Simple update</h4>
012 *
013 * <pre>{@code
014 *
015 *  int rows = ebeanServer
016 *      .update(Customer.class)
017 *      .set("status", Customer.Status.ACTIVE)
018 *      .set("updtime", new Timestamp(System.currentTimeMillis()))
019 *      .where()
020 *      .gt("id", 1000)
021 *      .update();
022 *
023 * }</pre>
024 * <pre>{@code sql
025 *
026 *   update o_customer set status=?, updtime=? where id > ?
027 *
028 * }</pre>
029 *
030 * <p>
031 * Note that if the where() clause contains a join then the SQL update changes to use a
032 * <code> WHERE ID IN () </code> form.
033 * </p>
034 *
035 * <h4>Example: Update with a JOIN</h4>
036 * <p>
037 *   In this example the expression <code>.eq("billingAddress.country", nz)</code> requires a join
038 *   to the address table.
039 * </p>
040 *
041 * <pre>{@code
042 *
043 *   int rows = ebeanServer
044 *       .update(Customer.class)
045 *       .set("status", Customer.Status.ACTIVE)
046 *       .set("updtime", new Timestamp(System.currentTimeMillis()))
047 *       .where()
048 *         .eq("status", Customer.Status.NEW)
049 *         .eq("billingAddress.country", nz)
050 *         .gt("id", 1000)
051 *         .update();
052 * }</pre>
053 *
054 * <pre>{@code sql
055 *
056 *   update o_customer set status=?, updtime=?
057 *   where id in (
058 *     select t0.id c0
059 *     from o_customer t0
060 *     left outer join o_address t1 on t1.id = t0.billing_address_id
061 *     where t0.status = ?
062 *       and t1.country_code = ?
063 *       and t0.id > ? )
064 *
065 * }</pre>
066 *
067 * @param <T> The type of entity bean being updated
068 *
069 * @see SqlUpdate
070 */
071public interface UpdateQuery<T> {
072
073  /**
074   * Set the value of a property.
075   *
076   *
077   * <pre>{@code
078   *
079   *   int rows = ebeanServer
080   *      .update(Customer.class)
081   *      .set("status", Customer.Status.ACTIVE)
082   *      .set("updtime", new Timestamp(System.currentTimeMillis()))
083   *      .where()
084   *      .gt("id", 1000)
085   *      .update();
086   *
087   * }</pre>
088   *
089   * @param property The bean property to be set
090   * @param value The value to set the property to
091   */
092  UpdateQuery<T> set(String property, Object value);
093
094  /**
095   * Set the property to be null.
096   *
097   * <pre>{@code
098   *
099   *   int rows = ebeanServer
100   *      .update(Customer.class)
101   *      .setNull("notes")
102   *      .where()
103   *      .gt("id", 1000)
104   *      .update();
105   *
106   * }</pre>
107   *
108   * @param property The property to be set to null.
109   */
110  UpdateQuery<T> setNull(String property);
111
112  /**
113   *
114   * Set using a property expression that does not need any bind values.
115   * <p>
116   * The property expression typically contains database functions.
117   * </p>
118   *
119   * <pre>{@code
120   *
121   *   int rows = ebeanServer
122   *      .update(Customer.class)
123   *      .setRaw("status = coalesce(status, 'A')")
124   *      .where()
125   *      .gt("id", 1000)
126   *      .update();
127   *
128   * }</pre>
129   *
130   * @param propertyExpression A property expression
131   */
132  UpdateQuery<T> setRaw(String propertyExpression);
133
134  /**
135   * Set using a property expression that can contain <code>?</code> bind value placeholders.
136   * <p>
137   * For each <code>?</code> in the property expression there should be a matching bind value supplied.
138   * </p>
139   * <pre>{@code
140   *
141   *   int rows = ebeanServer
142   *      .update(Customer.class)
143   *      .setRaw("status = coalesce(status, ?)", Customer.Status.ACTIVE)
144   *      .where()
145   *      .gt("id", 1000)
146   *      .update();
147   *
148   * }</pre>
149   *
150   * @param propertyExpression A raw property expression
151   * @param values The values to bind with the property expression
152   */
153  UpdateQuery<T> setRaw(String propertyExpression, Object... values);
154
155  /**
156   * Return the query expression list to add predicates to.
157   */
158  ExpressionList<T> where();
159
160}