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 *   }
036 * }</pre>
037 *
038 * <p>
039 * The following show code that would use a named update on the Topic entity
040 * bean.
041 * </p>
042 * <p>
043 * <pre>{@code
044 *
045 * Update<Topic> update = DB.createUpdate(Topic.class, "incrementPostCount");
046 * update.setParameter("id", 1);
047 * int rows = update.execute();
048 *
049 * }</pre>
050 *
051 * @param <T> the type of entity beans inserted updated or deleted
052 */
053public interface Update<T> {
054
055  /**
056   * Return the name if it is a named update.
057   */
058  String getName();
059
060  /**
061   * Set this to false if you do not want the cache to invalidate related
062   * objects.
063   * <p>
064   * If you don't set this Ebean will automatically invalidate the appropriate
065   * parts of the "L2" server cache.
066   * </p>
067   */
068  Update<T> setNotifyCache(boolean notifyCache);
069
070  /**
071   * Set a timeout for statement execution.
072   * <p>
073   * This will typically result in a call to setQueryTimeout() on a
074   * preparedStatement. If the timeout occurs an exception will be thrown - this
075   * will be a SQLException wrapped up in a PersistenceException.
076   * </p>
077   *
078   * @param secs the timeout in seconds. Zero implies unlimited.
079   */
080  Update<T> setTimeout(int secs);
081
082  /**
083   * Execute the statement returning the number of rows modified.
084   */
085  int execute();
086
087  /**
088   * Set an ordered bind parameter.
089   * <p>
090   * position starts at value 1 (not 0) to be consistent with PreparedStatement.
091   * </p>
092   * <p>
093   * Set a value for each ? you have in the sql.
094   * </p>
095   *
096   * @param position the index position of the parameter starting with 1.
097   * @param value    the parameter value to bind.
098   */
099  Update<T> set(int position, Object value);
100
101  /**
102   * Set and ordered bind parameter (same as bind).
103   *
104   * @param position the index position of the parameter starting with 1.
105   * @param value    the parameter value to bind.
106   */
107  Update<T> setParameter(int position, Object value);
108
109  /**
110   * Set an ordered parameter that is null. The JDBC type of the null must be
111   * specified.
112   * <p>
113   * position starts at value 1 (not 0) to be consistent with PreparedStatement.
114   * </p>
115   */
116  Update<T> setNull(int position, int jdbcType);
117
118  /**
119   * Set an ordered parameter that is null (same as bind).
120   */
121  Update<T> setNullParameter(int position, int jdbcType);
122
123  /**
124   * Set a named parameter. Named parameters have a colon to prefix the name.
125   * <p>
126   * A more succinct version of setParameter() to be consistent with Query.
127   * </p>
128   *
129   * @param name  the parameter name.
130   * @param value the parameter value.
131   */
132  Update<T> set(String name, Object value);
133
134  /**
135   * Bind a named parameter (same as bind).
136   */
137  Update<T> setParameter(String name, Object param);
138
139  /**
140   * Set a named parameter that is null. The JDBC type of the null must be
141   * specified.
142   * <p>
143   * A more succinct version of setNullParameter().
144   * </p>
145   *
146   * @param name     the parameter name.
147   * @param jdbcType the type of the property being bound.
148   */
149  Update<T> setNull(String name, int jdbcType);
150
151  /**
152   * Bind a named parameter that is null (same as bind).
153   */
154  Update<T> setNullParameter(String name, int jdbcType);
155
156  /**
157   * Set a label meaning performance metrics will be collected for the execution of this update.
158   */
159  Update<T> setLabel(String label);
160
161  /**
162   * Return the sql that is actually executed.
163   */
164  String getGeneratedSql();
165
166}