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}