java.sql.DataSet<T>

Implements: List

A DataSet provides a type safe view of the data returned from the execution of a SQL Query. It is a subinterface of java.util.List. A DataSet is also a parameterized type. The parameter type is a data class describing the columns for the rows returned by invoking a method on a Query interface decorated by a Select annotation. The data class must have an access modifier of public.

A DataSet may operate in a connected or disconnected mode. When used in a connected mode, the DataSet functions in a manner similar to ResultSet. A disconnected DataSet functions in a manner similar to a CachedRowSet.

A DataSet objects allows for the iteration through the rows that were returned using the Iterator API.

Navigating a DataSet

A DataSet is a subinterface of the List allowing for an application to navigate through a DataSet object:

 public class Mammal {
    public String name;
    public String description;
    public int age;
 }

 interface MyQueries extends BaseQuery {    
    @Select("select name, description, age from mammal")
    DataSet<Mammal> getAllMammals();
 }

 MyQueries mq = con.createQueryObject(MyQueries.class);
 DataSet rows = mq.getAllMammals();
 
 for (Mammal m: rows) {
     System.out.println("Name = " + m.name);
     System.out.println("Description =  " + m.description);
 }

Modifying a Row within a DataSet

You may update rows within a DataSet instance by positioning to the row to be modified, making the required modifications and then calling the modify method on the DataSet. If the DataSet is disconnected, the tableName annotation element must be specified in the Select annotation.

 DataSet<Mammal> rows = mq.getAllMammals();
 
 for (Mammal m: rows) {
     if (m.description.equals("")) {
         m.description="a mammal";
         rows.modify();
     }
 }

Deleting a Row within a DataSet

You may delete rows within a DataSet instance by positioning to the row to be deleted, and then calling the delete method on the DataSet. If the DataSet is disconnected, the tableName annotation element must be specified in the Select annotation.

 DataSet<Mammal> rows = mq.getAllMammals();
 
 for (Mammal m: rows) {
     if (m.description.equals("tbd")) {
         rows.delete();
     }
 }

Inserting a Row into a DataSet

You may insert rows into an existing DataSet instance. If the DataSet is disconnected, the tableName annotation element must be specified in the Select annotation. To insert a row, create an instance of the data class for the given DataSet and populate it. The method DataSet.insert is called to add the row to the DataSet.

 DataSet<Mammal> rows = mq.getAllMammals();
 Mammal newMammal = new Mammal();
 newMammal.name="Jane Doe";
 newMammal.description = "a real dear";
 rows.insert(newMammal);

Syncronizing a DataSet

A DataSet can be configured to operate in a disconnected manner by setting the Select annotation element connected to false. This requires any changes made to the DataSet to be explicitly syncronized to the underlying data store. The DataSet.sync method must be called to propagate the DatasSet modifications to the data store. The modifications are done as an atomic operation.

The data class for a disconnected DataSet must specify at least one column to uniquely identify the row using the ResultColumn annotation's uniqueIdentifier annotation element. If there is no column specified to uniquely identify the row, a SQLRuntimeException will be thrown.

If an invocation of DataSet.sync fails, a SQLDataSetSyncException will be thrown. The SQLDataSetSyncException.getDataSetResolver method can be called to navigate the rows that could not be updated in the data store along with the cause of the failure.

since 1.6