io.ebean.UpdateQuery Maven / Gradle / Ivy
package io.ebean;
/**
* An update query typically intended to perform a bulk update of many rows that match the query.
*
* Also note that you can also just use a raw SQL update via {@link SqlUpdate} which is pretty light and simple.
* This UpdateQuery is more for the cases where we want to build the where expression of the update using the
* {@link ExpressionList} "Criteria API" that is used with a normal ORM query.
*
*
*
Example: Simple update
*
*
{@code
*
* int rows = DB.update(Customer.class)
* .set("status", Customer.Status.ACTIVE)
* .set("whenUpdated", Instant.now())
* .where()
* .gt("id", 1000)
* .update();
*
* }
* {@code sql
*
* update o_customer set status=?, updtime=? where id > ?
*
* }
*
* Example: Using query bean
* {@code
*
* var cust = QCustomer.alias();
*
* int rows = new QCustomer()
* .id.gt(1000)
* .asUpdate()
* .set(cust.status, Customer.Status.COMPLETE)
* .set(cust.whenUpdated, Instant.now())
* .update();
*
* }
*
* Note that if the where() clause contains a join then the SQL update changes to use a
* WHERE ID IN () form.
*
*
*
Example: Update with a JOIN
*
* In this example the expression .eq("billingAddress.country", nz) requires a join
* to the address table.
*
*
*
{@code
*
* int rows = DB.update(Customer.class)
* .set("status", Customer.Status.ACTIVE)
* .set("whenUpdated", Instant.now())
* .where()
* .eq("status", Customer.Status.NEW)
* .eq("billingAddress.country", nz)
* .gt("id", 1000)
* .update();
* }
*
*
{@code sql
*
* update o_customer set status=?, updtime=?
* where id in (
* select t0.id c0
* from o_customer t0
* left join o_address t1 on t1.id = t0.billing_address_id
* where t0.status = ?
* and t1.country_code = ?
* and t0.id > ? )
*
* }
*
* @param The type of entity bean being updated
* @see SqlUpdate
*/
public interface UpdateQuery {
/**
* Set the value of a property.
*
*
{@code
*
* int rows = DB.update(Customer.class)
* .set("status", Customer.Status.ACTIVE)
* .set("whenUpdated", Instant.now())
* .where()
* .gt("id", 1000)
* .update();
*
* }
*
* @param property The bean property to be set
* @param value The value to set the property to
*/
UpdateQuery set(String property, Object value);
/**
* Set the value of a property.
*
*
{@code
*
* var cust = QCustomer.alias();
*
* int rows = new QCustomer()
* .id.gt(1000)
* .asUpdate()
* .set(cust.status, Customer.Status.COMPLETE)
* .set(cust.whenUpdated, Instant.now())
* .update();
*
* }
*
* @param property The bean property to be set
* @param value The value to set the property to
*/
UpdateQuery set(Query.Property property, P value);
/**
* Set the property to be null.
*
*
{@code
*
* int rows = DB.update(Customer.class)
* .setNull("notes")
* .where()
* .gt("id", 1000)
* .update();
*
* }
*
* @param property The property to be set to null.
*/
UpdateQuery setNull(String property);
/**
* Set the property to be null.
*
* @param property The bean property to be set
*/
UpdateQuery setNull(Query.Property property);
/**
* Set using a property expression that does not need any bind values.
*
* The property expression typically contains database functions.
*
*
*
{@code
*
* int rows = DB.update(Customer.class)
* .setRaw("status = coalesce(status, 'A')")
* .where()
* .gt("id", 1000)
* .update();
*
* }
*
* @param propertyExpression A property expression
*/
UpdateQuery setRaw(String propertyExpression);
/**
* Set using a property expression that can contain ? bind value placeholders.
*
* For each ? in the property expression there should be a matching bind value supplied.
*
* {@code
*
* int rows = DB.update(Customer.class)
* .setRaw("status = coalesce(status, ?)", Customer.Status.ACTIVE)
* .where()
* .gt("id", 1000)
* .update();
*
* }
*
* @param propertyExpression A raw property expression
* @param values The values to bind with the property expression
*/
UpdateQuery setRaw(String propertyExpression, Object... values);
/**
* Set the profile location of this update query. This is used to relate query execution metrics
* back to a location like a specific line of code.
*/
UpdateQuery setProfileLocation(ProfileLocation profileLocation);
/**
* Set the label on the update query.
*/
UpdateQuery setLabel(String label);
/**
* Return the query expression list to add predicates to.
*/
ExpressionList where();
/**
* Execute the update returning the number of rows updated.
*/
int update();
}