001package com.avaje.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 * 
015 * <pre type="class">
016 *  ...
017 * &#064;NamedUpdates(value = {
018 *   &#064;NamedUpdate(
019 *      name = &quot;setTitle&quot;, 
020 *      notifyCache = false, 
021 *      update = &quot;update topic set title = :title, postCount = :count where id = :id&quot;),
022 *  &#064;NamedUpdate(
023 *      name = &quot;setPostCount&quot;, 
024 *      notifyCache = false, 
025 *      update = &quot;update f_topic set post_count = :postCount where id = :id&quot;),
026 *  &#064;NamedUpdate(
027 *      name = &quot;incrementPostCount&quot;, 
028 *      notifyCache = false, 
029 *      update = &quot;update Topic set postCount = postCount + 1 where id = :id&quot;) 
030 *      //update = &quot;update f_topic set post_count = post_count + 1 where id = :id&quot;) 
031 *  })
032 * &#064;Entity
033 * &#064;Table(name = &quot;f_topic&quot;)
034 * public class Topic {
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 * 
043 * <pre class="code">
044 * Update&lt;Topic&gt; update = Ebean.createUpdate(Topic.class, &quot;incrementPostCount&quot;);
045 * update.setParameter(&quot;id&quot;, 1);
046 * int rows = update.execute();
047 * </pre>
048 * 
049 * @param <T>
050 *          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
078   *          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
097   *          the index position of the parameter starting with 1.
098   * @param value
099   *          the parameter value to bind.
100   */
101  Update<T> set(int position, Object value);
102
103  /**
104   * Set and ordered bind parameter (same as bind).
105   * 
106   * @param position
107   *          the index position of the parameter starting with 1.
108   * @param value
109   *          the parameter value to bind.
110   */
111  Update<T> setParameter(int position, Object value);
112
113  /**
114   * Set an ordered parameter that is null. The JDBC type of the null must be
115   * specified.
116   * <p>
117   * position starts at value 1 (not 0) to be consistent with PreparedStatement.
118   * </p>
119   */
120  Update<T> setNull(int position, int jdbcType);
121
122  /**
123   * Set an ordered parameter that is null (same as bind).
124   */
125  Update<T> setNullParameter(int position, int jdbcType);
126
127  /**
128   * Set a named parameter. Named parameters have a colon to prefix the name.
129   * <p>
130   * A more succinct version of setParameter() to be consistent with Query.
131   * </p>
132   * 
133   * @param name
134   *          the parameter name.
135   * @param value
136   *          the parameter value.
137   */
138  Update<T> set(String name, Object value);
139
140  /**
141   * Bind a named parameter (same as bind).
142   */
143  Update<T> setParameter(String name, Object param);
144
145  /**
146   * Set a named parameter that is null. The JDBC type of the null must be
147   * specified.
148   * <p>
149   * A more succinct version of setNullParameter().
150   * </p>
151   * 
152   * @param name
153   *          the parameter name.
154   * @param jdbcType
155   *          the type of the property being bound.
156   */
157  Update<T> setNull(String name, int jdbcType);
158
159  /**
160   * Bind a named parameter that is null (same as bind).
161   */
162  Update<T> setNullParameter(String name, int jdbcType);
163
164  /**
165   * Return the sql that is actually executed.
166   */
167  String getGeneratedSql();
168
169}