001package io.ebean;
002
003/**
004 * An Insert Update or Delete statement.
005 * <p>
006 * Generally a named update will be defined on the entity bean. This will take
007 * the form of either an actual sql insert update delete statement or a similar
008 * statement with bean name and property names in place of database table and
009 * column names. The statement will likely include named parameters.
010 * </p>
011 * <p>
012 * The following is an example of named updates on an entity bean.
013 * </p>
014 * <pre>{@code
015 *  ...
016 * @NamedUpdates(value = {
017 *   @NamedUpdate(
018 *      name = "setTitle",
019 *      notifyCache = false,
020 *      update = "update topic set title = :title, postCount = :count where id = :id"),
021 *  @NamedUpdate(
022 *      name = "setPostCount",
023 *      notifyCache = false,
024 *      update = "update f_topic set post_count = :postCount where id = :id"),
025 *  @NamedUpdate(
026 *      name = "incrementPostCount",
027 *      notifyCache = false,
028 *      update = "update Topic set postCount = postCount + 1 where id = :id")
029 *      //update = "update f_topic set post_count = post_count + 1 where id = :id")
030 *  })
031 * @Entity
032 * @Table(name = "f_topic")
033 * public class Topic {
034 *  ...
035 * }</pre>
036 *
037 * <p>
038 * The following show code that would use a named update on the Topic entity
039 * bean.
040 * </p>
041 * <p>
042 * <pre>{@code
043 *
044 * Update<Topic> update = DB.createUpdate(Topic.class, "incrementPostCount");
045 * update.setParameter("id", 1);
046 * int rows = update.execute();
047 *
048 * }</pre>
049 *
050 * @param <T> the type of entity beans inserted updated or deleted
051 */
052public interface Update<T> {
053
054  /**
055   * Return the name if it is a named update.
056   */
057  String getName();
058
059  /**
060   * Set this to false if you do not want the cache to invalidate related
061   * objects.
062   * <p>
063   * If you don't set this Ebean will automatically invalidate the appropriate
064   * parts of the "L2" server cache.
065   * </p>
066   */
067  Update<T> setNotifyCache(boolean notifyCache);
068
069  /**
070   * Set a timeout for statement execution.
071   * <p>
072   * This will typically result in a call to setQueryTimeout() on a
073   * preparedStatement. If the timeout occurs an exception will be thrown - this
074   * will be a SQLException wrapped up in a PersistenceException.
075   * </p>
076   *
077   * @param secs the timeout in seconds. Zero implies unlimited.
078   */
079  Update<T> setTimeout(int secs);
080
081  /**
082   * Execute the statement returning the number of rows modified.
083   */
084  int execute();
085
086  /**
087   * Set an ordered bind parameter.
088   * <p>
089   * position starts at value 1 (not 0) to be consistent with PreparedStatement.
090   * </p>
091   * <p>
092   * Set a value for each ? you have in the sql.
093   * </p>
094   *
095   * @param position the index position of the parameter starting with 1.
096   * @param value    the parameter value to bind.
097   */
098  Update<T> set(int position, Object value);
099
100  /**
101   * Set and ordered bind parameter (same as bind).
102   *
103   * @param position the index position of the parameter starting with 1.
104   * @param value    the parameter value to bind.
105   */
106  Update<T> setParameter(int position, Object value);
107
108  /**
109   * Set an ordered parameter that is null. The JDBC type of the null must be
110   * specified.
111   * <p>
112   * position starts at value 1 (not 0) to be consistent with PreparedStatement.
113   * </p>
114   */
115  Update<T> setNull(int position, int jdbcType);
116
117  /**
118   * Set an ordered parameter that is null (same as bind).
119   */
120  Update<T> setNullParameter(int position, int jdbcType);
121
122  /**
123   * Set a named parameter. Named parameters have a colon to prefix the name.
124   * <p>
125   * A more succinct version of setParameter() to be consistent with Query.
126   * </p>
127   *
128   * @param name  the parameter name.
129   * @param value the parameter value.
130   */
131  Update<T> set(String name, Object value);
132
133  /**
134   * Bind a named parameter (same as bind).
135   */
136  Update<T> setParameter(String name, Object param);
137
138  /**
139   * Set a named parameter that is null. The JDBC type of the null must be
140   * specified.
141   * <p>
142   * A more succinct version of setNullParameter().
143   * </p>
144   *
145   * @param name     the parameter name.
146   * @param jdbcType the type of the property being bound.
147   */
148  Update<T> setNull(String name, int jdbcType);
149
150  /**
151   * Bind a named parameter that is null (same as bind).
152   */
153  Update<T> setNullParameter(String name, int jdbcType);
154
155  /**
156   * Set a label meaning performance metrics will be collected for the execution of this update.
157   */
158  Update<T> setLabel(String label);
159
160  /**
161   * Return the sql that is actually executed.
162   */
163  String getGeneratedSql();
164
165}