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:

• A String value designated by a question mark(?) prefix follwed by an integer.
• The numbering for parameter markers starts at 1. For example ?1.
• The number of distinct parameter marks must not exceed the number of method parameters for the method that was decorated by the Update annotation. If this occurs, a SQLRuntimeException will be thrown.
• A parameter marker may be specfied more than once in a sql annotation element.

 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 annotation. 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.RETURNED_KEYS_DRIVER_DEFINED to indicate that the JDBC driver will determine the columns to return to represent the auto-generated keys. A value of GeneratedKeys.RETURNED_KEYS_COLUMNS_SPECIFIED for the keys annotation element indicates that the columns contained in the data class decorated by the AutoGeneratedKeys annotation are returned as the auto generated keys from the method invocation.

  @AutoGeneratedKeys
 public class TabKeys {
     public String col1;

 }
 public interface MyQueries extends BaseQuery{
   @Update(sql="insert into tabName(?1, ?2)",
    keys=GeneratedKeys.RETURNED_KEYS_DRIVER_DEFINED) 
   DataSet<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 );
 }
 

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 > ?1")
     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