001package com.avaje.ebean;
002
003/**
004 * A SqlUpdate for executing insert update or delete statements.
005 * <p>
006 * Provides a simple way to execute raw SQL insert update or delete statements
007 * without having to resort to JDBC.
008 * </p>
009 * <p>
010 * Supports the use of positioned or named parameters and can automatically
011 * notify Ebean of the table modified so that Ebean can maintain its cache.
012 * </p>
013 * <p>
014 * Note that {@link #setAutoTableMod(boolean)} and
015 * Ebean#externalModification(String, boolean, boolean, boolean)} can be to
016 * notify Ebean of external changes and enable Ebean to maintain it's "L2"
017 * server cache.
018 * </p>
019 * 
020 * <pre class="code">
021 * // example that uses 'named' parameters 
022 * String s = &quot;UPDATE f_topic set post_count = :count where id = :id&quot;
023 * SqlUpdate update = Ebean.createSqlUpdate(s);
024 * update.setParameter(&quot;id&quot;, 1);
025 * update.setParameter(&quot;count&quot;, 50);
026 * 
027 * int modifiedCount = Ebean.execute(update);
028 * 
029 * String msg = &quot;There were &quot; + modifiedCount + &quot; rows updated&quot;
030 * </pre>
031 * 
032 * @see Update
033 * @see SqlQuery
034 * @see CallableSql
035 */
036public interface SqlUpdate {
037
038  /**
039   * Execute the update returning the number of rows modified.
040   * <p>
041   * After you have executed the SqlUpdate you can bind new variables using
042   * {@link #setParameter(String, Object)} etc and then execute the SqlUpdate
043   * again.
044   * </p>
045   * <p>
046   * For JDBC batch processing refer to
047   * {@link Transaction#setBatchMode(boolean)} and
048   * {@link Transaction#setBatchSize(int)}.
049   * </p>
050   * 
051   * @see com.avaje.ebean.Ebean#execute(SqlUpdate)
052   */
053  int execute();
054
055  /**
056   * Return true if eBean should automatically deduce the table modification
057   * information and process it.
058   * <p>
059   * If this is true then cache invalidation and text index management are aware
060   * of the modification.
061   * </p>
062   */
063  boolean isAutoTableMod();
064
065  /**
066   * Set this to false if you don't want eBean to automatically deduce the table
067   * modification information and process it.
068   * <p>
069   * Set this to false if you don't want any cache invalidation or text index
070   * management to occur. You may do this when say you update only one column
071   * and you know that it is not important for cached objects or text indexes.
072   * </p>
073   */
074  SqlUpdate setAutoTableMod(boolean isAutoTableMod);
075
076  /**
077   * Return the label that can be seen in the transaction logs.
078   */
079  String getLabel();
080
081  /**
082   * Set a descriptive text that can be put into the transaction log.
083   * <p>
084   * Useful when identifying the statement in the transaction log.
085   * </p>
086   */
087  SqlUpdate setLabel(String label);
088
089  /**
090   * Return the sql statement.
091   */
092  String getSql();
093
094  /**
095   * Return the generated sql that has named parameters converted to positioned parameters.
096   */
097  String getGeneratedSql();
098
099  /**
100   * Return the timeout used to execute this statement.
101   */
102  int getTimeout();
103
104  /**
105   * Set the timeout in seconds. Zero implies no limit.
106   * <p>
107   * This will set the query timeout on the underlying PreparedStatement. If the
108   * timeout expires a SQLException will be throw and wrapped in a
109   * PersistenceException.
110   * </p>
111   */
112  SqlUpdate setTimeout(int secs);
113
114  /**
115   * Set a parameter via its index position.
116   */
117  SqlUpdate setParameter(int position, Object value);
118
119  /**
120   * Set a null parameter via its index position.
121   */
122  SqlUpdate setNull(int position, int jdbcType);
123
124  /**
125   * Set a null valued parameter using its index position.
126   */
127  SqlUpdate setNullParameter(int position, int jdbcType);
128
129  /**
130   * Set a named parameter value.
131   */
132  SqlUpdate setParameter(String name, Object param);
133
134  /**
135   * Set a named parameter that has a null value. Exactly the same as
136   * {@link #setNullParameter(String, int)}.
137   */
138  SqlUpdate setNull(String name, int jdbcType);
139
140  /**
141   * Set a named parameter that has a null value.
142   */
143  SqlUpdate setNullParameter(String name, int jdbcType);
144
145}