canonical

在witrix平台中访问数据库最直接的方法是使用edu.thu.db.SQL类。基本用法如下:
//  设定数据库连接参数， 连接可以通过java.sql.DriverManager 和

//javax.sql.DataSource等多种方式建立，并支持数据库连接缓冲池。
TransactionMode db = new TransactionMode("default"); // 设定数据库连接参数
SQL sql = SQL.begin().select().field("id")
                     .from().table("other_table")
      .where().like("name","a%");
   .end();
int n = SQL.begin().select().countAll()
                   .from().table("my_table")
       .where().gt("value", new Integer(3)) // value > 3
            .and().in("type", new String[]{"a","b"})  // type in ('a','b')
         .and().in("data_id",sql)  // data_id in (select id from other_table where name like 'a%')
      .end().query(db).intValue();

在SQL类的设计中体现了三个设计原则:
1. 正交化的流式设计
2. 参数对象化
3. bug-free设计

首先，SQL类将构造SQL语句，连接数据库以及查询结果类型转换分解成了三个正交的部分。
在一般的数据库编程中，我们需要如下访问方式:
String sql = "select count(*) from my_table where value > ?";
Connection conn = getConnection();
PreparedStatement stmt = null;
try{
     PreparedStatement stmt = conn.prepareStatement(sql);
  stmt.setParameter(1, valueLimit);
  ResultSet rs = stmt.executeQuery();
  rs.next();
  int ret = rs.getInt(1);
  // ...
}finally{
 try{
  if(stmt != null)
   stmt.close();
 }catch(Exception e){
     e.printStackTrace();
 }

 try{
  conn.close();
 }catch(Exception e){
     e.printStackTrace();
 }
}

从 以上的例子中，我们可以注意到，在普通JDBC编程中，设置SQL语句的参数，建立数据库连接，取得结果集中的结果并转化为合适的格式这三者之间是交织在 一起的。特别是打开连接需要配对的关闭连接语句，造成整个程序的流程不是线性的, 因为我们不能说建立连接之后就可以不再管连接的事情了，我们必须记住在做完所有其他事情之后还要关闭连接。    通过一系列的封装对象，SQL类实现了一种正交化的流式设计，其分解模式如下:
      SQL.begin().拼接SQL语句.end().建立连接并运行SQL语句.转化结果()
注意在SQL语句执行之后是不需要显式关闭连接的。

SQL类的第二个设计要点是参数对象化。在witrix平台中，实际运行SQL语句的引擎函数是
 IDbEngine.execute(String sqlText, List sqlParameters, int resultType, int concurrency);
这 里sqlText, sqlParameters等都是参数，但是在应用中构造这些参数的过程很复杂，并且非常灵活，一般的Util类（静态Utility函数）无法提供有效 的简化。 所以构造SQL语句这个过程不是通过util类完成的，而是通过一个专用的SqlBuilder对象。SQL的基本思想是将sql语句纳入java程序框 架，使得sql语句成为程序中可控制的部分。首先SQL类将sql文本与sql参数封装为一个完整的对象，使得sql语句的重用成为可能。其次， SqlBuilder类通过一种可控制的方式构造sql语句（所有的关键字都对应于一个函数)，整个过程与直接书写sql文本类似，但函数封装使得我们能 够在同一行上指定sql文本中用到的参数，而不是象jdbc里那样，集中指定参数。同时SqlBuilder支持面向java语言的扩展，如直接支持 java集合类型等，从而大大简化了sql语句的构造，因为一般sql拼接中最混乱的部分就是牵涉到循环与判断。
  参数对象化的方法还可以应用于那些具有大量缺省参数的地方。在SQL类中，如果我们希望以scroll insensitive的方式选出数据，调用方式如下:
  SQL.begin().select().star()
             .from().table("my_table")
   .end().scrollable(true).list(db,3,100);
如果我们希望利用Statement.cancel()特性，我们可以指定cancelMonitor参数
   SQL.begin()....end().cancelMonitor(monitor).query(db).listValue();