Apache Torque的使用

这篇文章学习如何使用Torque，作为一个ORM（a tool that maps relational databases to java classes）

用Torque访问数据库，需要如下步骤

定义描述数据库结构（tables, columns等）的schema文件
通过schema生成classes和数据库
使用生成的类 (and the torque-runtime library classes) 访问数据库

创建database schema

每个schema文件包含一个数据库作为根元素。

运行Generator

Torque uses the information from the database schema to generate classes by which the database can be accessed. Also, Torque can generate SQL scripts and documentation in HTML and xdoc format from the schema. The Torque generator must be invoked in order to generate these artifacts. This can be done in three different ways: via Maven 2/3, via ant or via plain Java.

数据库独立性

产生的java代码具有数据库独立性。这意味着不必为每种数据库重新生成代码。但是有几点需要注意的：

不是所有data types are available on all databases.
Available data types也可能不同数据库表现不同。E.g. Oracle's date type contains time information as well, in contrast to all other databases.
表名和column名的最大长度也随数据库变化而变化。目前的了解，表名长度不超过27个字符，column名长度不超过31个字符在所有数据库中都是安全的。

产生的SQL具有数据库依赖性 (of course).

初始化Torque runtime

Torque通过调用Torque.init() 来初始化。Torque在使用前必须初始化，而且只能初始化一次。初始化时必须提供执行configuration文件的路径或者configuration本身。

一旦初始化，数据库的runtime model，比如DatabaseMaps会自动有生成的MapBuilder类创建。每个peer class在Base class被加载时构建runtime model，并且将table model注册到相应的database model中。

Configuration说明

database handles: 数据库的名称，如果没有定义，则是default
```
torque.database.default=bookstore
```
database adapter: 为handle指定adapter。目前支持: derby, mysql, oracle, mssql等
```
torque.database.bookstore.adapter=mysql
```
连接池: 可以为任何实现接口DataSource的连接池。用户可以配置获取datasource的factory。
- SharedPoolDataSourceFactory
- JndiDataSourceFactory

读数据库

读数据需要指定读哪个数据库里的哪张表。Torque引入Criteria object表达SQL Query。之后将Criteria对象传给一个Peer类，该类会负责查询数据库并将结果以Data Object返回。

Runtime中有两类Criteria类：org.apache.torque.criteria.Criteria and org.apache.torque.util.Criteria。前者推荐给新项目，后者已过时但可以支持legacy项目。

Criteria crit = new Criteria();
Criterion a1 = new Criterion(ABC.A, 1, Criteria.LESS_THAN);
Criterion b2 = new Criterion(ABC.B, 2, Criteria.GREATER_THAN);
Criterion a5 = new Criterion(ABC.A, 5, Criteria.GREATER_THAN);
Criterion b3 = new Criterion(ABC.B, 3, Criteria.LESS_THAN);

crit.where(a1.and(b2).or(a5.and(b3)));

写数据库

往数据库中写数据，调用save()方法。写的方式分为insert和update。另外一种选择方案是调用对用Peer类的静态方式doInsert()或者doUpdate()

Mass Updates: BasePeer的中的doUpdate(Criteria, ColumnValues) 方法，允许一次修改多个数据对象。比如将id大于5的author的name置null

Criteria criteria = new Criteria();
criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_THAN);
ColumnValues columnValues = new ColumnValues();
columnValues.put(AuthorPeer.NAME,
    new JdbcTypedValue(
        null,
        java.sql.Types.VARCHAR));
BasePeer.doUpdate(criteria, columnValues);

删除对象: 如何数据已经加载到了直接调用对应Peer类的doDelete(xxx)；如果没有被加载，则直接使用Criteria

Criteria criteria = new Criteria();
criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_THAN);
AuthorPeer.doDelete(criteria);

Reference

https://db.apache.org/torque/torque-4.0/documentation/orm-reference/index.html

http://www.iteye.com/topic/151778