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