java.sql
Annotation Type Update

@Documented
@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface Update

Annotation used to decorate a method in a Query interface with a SQL statement that can return an update count or can return auto generated keys. The Update annotation must not be used in-conjunction with a SQL statement that returns a ResultSet.

A Query interface may contain zero, one or more methods decorated with an Update annotation.

The following provides an example of using the Update annotation. 

 // Define DataSet type
 public class Mammal {
     public String name;
     public String description;
     public int age;
     public int weight;
 }
 // Define the interface containing the methods representing SQL statements
 // that can be invoked.
 
 interface MyQueries extends BaseQuery {    
    @Select("select name, description, age from mammal")
    DataSet<Mammal> getAllMammals();
 
    @Update("delete  from mammal")
    int deleteAllMammals();
 }
To invoke the deleteAllMammals() method, an instance of the MyQueries interface must be created by invoking either the Connnection.createQueryObject or DataSource.createQueryObject method. 
 MyQueries mq = con.createQueryObject(MyQueries.class);
 int success = mq.deleteAllMammals();

Using a Parameterized sql annotation element

The sql annotation element allows developers to specify parameter markers similar to PreparedStatements. Parameter markers are defined as: 

 interface MyQueries extends BaseQuery {    
 
    @Update(sql="update mammal set description= ?1 where age <10")
    int setDescription(String desc);
 }
 

 MyQueries mq = con.createQueryObject(MyQueries.class);
 int success = mq.setDescription("a young mammal");

When the setDescription() method is invoked, the value specified for the parameter desc will be used as the value for the parameter marker.

Returning Auto-Generated keys

The AutoGeneratedKeys annotation is used to indicate that a Dataset data class will be used to store any auto generated keys that occur as the result of executing a method decorated with an Update. The data class may contain one or more fields that comprise the auto generated key. The Update annotation element keys would be set to a value of GeneratedKeys.ALL_KEYS to indicate that auto generated keys might be returned from the method invocation. 

 public class TabKeys {
     public String col1;
     public String col2;
 }
 public interface MyQueries extends BaseQuery{
   @Update(sql="insert into tabName({name}, {age})",
    keys=GeneratedKeys.ALL_KEYS) 
   DatSet<TabKeys> addPerson(String name, int age);
 }
In the above example, the MyQueries.addPerson method indicates that it can return auto generated keys upon its execution. The returned auto generated keys may be accessed as follows: 

 MyQueries mq = con.createQueryObject(MyQueries.class);
 DataSet<TabKeys> keys = mq.addPerson("Jane Doe", 29);
 for (TabKeys key : keys) {
      System.out.println("Key=" + key.col1 + "," + key.col2);
 }

Returning an Update Count

A method decorated by an Update annotation can return the number of rows affected by the method invocation by specifying a return type of int. If a return type of void is specified, an update count will not be returned. 

 interface MyQueries extends BaseQuery {
     @Update(sql="update mammal set weight = 5 where weight > {weight}")
     int shrinkBigMammals(int weight);
 }

A returned value of 0 indicates that no rows were updated. A returned value greater than 0 indicates that 1 or more rows were affected by the method invocation.

Since:
1.6

Optional Element Summary
 GeneratedKeys keys
          Determines whether auto-generated keys are returned or not
 String sql
          The SQL command to execute.
 String value
          The SQL command to execute.
 

sql

public abstract String sql
The SQL command to execute. The SQL command that is specified can return an update count. The SQL command must not return a result set.

Note: If the sql and the value annotation element are specified at the same time, a SQLRuntimeException will be thrown.

Returns:
a String representation of the SQL command.
Since:
1.6
Default:
""

keys

public abstract GeneratedKeys keys
Determines whether auto-generated keys are returned or not

Returns:
GeneratedKeys.NO_KEYS if auto-generated keys have not been requested; GeneratedKey.ALL_KEYS otherwise.
Since:
1.6
Default:
NO_KEYS

value

public abstract String value
The SQL command to execute. The SQL command that is specified can return an update count. The SQL command must not return a result set.

Note: If the sql and the value annotation element are specified at the same time, a SQLRuntimeException will be thrown.

Returns:
a String representation of the SQL command.
Since:
1.6
Default:
""