JOQS- Java Simple O/R Mapping & JDBC Extensions

OQS 使用查询语句（Query String）来查询数据库，并根据查询语句的描述来进行O/R映射。QS描述了数据库中的一条记录将映射成怎样的一个JAVA对象。通过QS查询的结果都是对象，primitive的值将会自动使用其包装类，JDK1.5以上则可以使用泛型，省去类型转化的麻烦。

QS类似于NATIVE SQL，是与数据库平台相关的，但分页查询是与数据库产品无关的；如果使用标准的SQL语句，也能获得较好的数据库移植性。应尽量使用标准的SQL语法，避免使用数据库相关的特殊函数操作，就可以减少或去除更换数据库产品所带来的代码移植问题。

select id, name, description from UserInfo where id > ?

select new list(id, name, description) from UserInfo where id > ?

select new map(id, name as name, description mydesc) from UserInfo where id > ?

select new org.opoo.oqs.sapmles.UserInfo(id, name as userName, description userDesc) 
from userinfo where id > ?

select new list(id, name, description) as mylist from UserInfo where id > ?

select id, new list(name, description) as list0, new map(id, name as userName) map0 from userinfo

select new list(id, name, new map(id as ID, name NAME, description DESC) as myMap) from UserInfo

select new list(*) from UserInfo

select new map(*) from UserInfo

select new UserInfo(*) from UserInfo

select new list(id, *) from UserInfo
select new map(id as id, new list(*) as list) from UserInfo

select new list(a.*), new map(b.*(8)) from UserInfo a, UserDetail b
select a.*(3), b.*(8) from UserInfo a, UserDetail b

查询语句(QS)中select ... from之间表示的每个字段都是一个QS属性，几个简单的QS属性也可以组合成一个复杂的QS属性，如 new map(id, name) as map0， 此属性的别名是map0，类型是一个复合属性。

如1.2.1所示，当QS中没有指定任何映射器是，系统会调用默认的Mapper，但此默认行为也可以通过指定自定义的Mapper来改变。设置自定义Mapper后，OQS将使用指定的Mapper来处理结果集。设置Mapper的方法如下。

Mapper mapper = ...;
QueryFactory queryFactory = ...;
List list = queryFactory.createQuery("select * from UserInfo").setMapper(mapper).list();

其中Mapper的定义如下：

public interface Mapper {
    void initialize(ResultSetMetaData rsmd) throws SQLException;
    Object map(ResultSet rs, int rowNum) throws SQLException;
}

initialize方法做在查询结果集初始化的时候被调用，map方法则在负责将结果集每条记录转化成一个java对象，自定义Mapper时，实现map方法即可，可以通过继承MapperAdaptor来实现。

Mapper mapper = new MapperAdaptor()
{
    public Object map(ResultSet rs, int rowNum) throws SQLException
    {
        UserInfo userInfo = new UserInfo();
        userInfo.setId(rs.getLong("id"));
        userInfo.setName(rs.getString("name"));
        return userInfo;
    }
}
...

占位参数(Positional Parameters)和命名参数(Named Parameters)都可以应用于QS中。

select id, name from userinfo where id > ?

select id, name from userinfo where id in (:ids) and name=:name

OQS 的编译和运行需要JDK1.4.2以上版本。

OQS distributions包括源码包和二进制包。发布包中都包含了编译或者运行所需要的类库。

除了上表列出的类库，运行环境还需要相应数据库的JDBC驱动类库等。

QueryFactory是OQS最重要的两个接口之一，另外一个是Query。QueryFactory的主要作用是根据需要产生不同的Query实例。

QueryFactory目前只用一个使用spring jdbc的实现-org.opoo.oqs.spring.SpringQueryFactoryImpl，开发者可以继承AbstractQueryFactory类来实现了自己的QueryFactory。

创建QueryFactory需要指定一个数据源(java.sql.DataSource)，分页查询还必须设置数据库Dialect(Dialect可以使用现有的各个实现版本，也可以直接使用Hibernate3的Dialect实现)。如果创建过程出现错误，则抛出CannotCreateQueryFactoryException异常，这是checked exception，必须处理。

建议：在一个应用中，尽量保证只有一个QueryFactory的实例（单态），这样可以减少资源的使用情况。

下面讲述两种最常见的QueryFactory创建方式，更详细实现请参考后面的章节。

Query是OQS另外一个最要的接口。从QueryFactory创建一个查询示例如下：

Query query = factory.createQuery("select new list(id, name) from userinfo"); 

有关Query更详细的信息请阅读第3章：QueryFactory和Query。

对Query的操作类似于Hibernate的Query。

//查询
Query query = factory.createQuery("select new list(id, name) from userinfo"); 
List list = query.list();
//或者：
QueryIterator iterator = query.iterate();

//更新
int effectRows = factory.createQuery("update userinfo set name='aa' where id=1").executeUpdate();

//Positional parameters
Query query = factory.createQuery("select new list(id, name) from userinfo where id > ?"); 
query.setInteger(0, 1);//index从0开始
List list = query.list();

list = factory.createQuery("select id, name from userinfo where id > ? and name=?")
.setInteger(0, 1)//也可以先setString(1, "");
.setString(1, "name1")
.list();

//update
int result = factory.createQuery("update userinfo set name=? where id=?")
.setString(0, "new name")
.setInteger(1, 23)
.executeUpdate();


//named parameters
list = factory.createQuery("select id, name from userinfo where id > :id")
.setInteger("id", 10)
.list();

//positional parameters & named parameters
list = factory.createQuery("select id, name from userinfo where id > ? and name=:name")
.setInteger(0, 10)
.setString("name", "name1")
.list();

示例使用dbcp数据源，需要commons-dbcp和commons-pool类库。要运行本示例，您还必须有相应的数据库（test）、数据表（test_table）、以及JDBC驱动包等。本示例使用SQLServer数据库，JTDS驱动。

package org.opoo.oqs.samples;

import java.util.List;
import java.util.Map;
import org.apache.commons.dbcp.BasicDataSource;
import org.opoo.oqs.*;
import org.opoo.oqs.core.*;
import org.opoo.oqs.spring.*;

/**
 * @author alex@opoo.org
 */
public class TestQuery
{
  public static void main(String[] args) throws
      CannotCreateQueryFactoryException
  {
    BasicDataSource ds = new BasicDataSource();
    ds.setDefaultAutoCommit(true);
    ds.setDriverClassName("net.sourceforge.jtds.jdbc.Driver");
    ds.setMaxActive(10);
    ds.setMaxIdle(2);
    ds.setUsername("sa");
    ds.setPassword("");
    ds.setUrl("jdbc:jtds:sqlserver://127.0.0.1:1433;DatabaseName=test");

    SpringQueryFactoryImpl factory = new SpringQueryFactoryImpl(ds);
    factory.setShowSql(3);

    List list = factory.createQuery("select new map(id id, name nm, desc1 dc) from test_table where id > ?")
      .setInteger(0, 2).list();

    for(int i = 0, n = list.size() ; i < n; i++)
    {
      Map map = (Map) list.get(i);
      System.out.println("ID: " + map.get("id"));
      System.out.println("Name: " + map.get("nm"));
      System.out.println("Desc: " + map.get("dc"));
      System.out.println("-------------------");
    }
  }
}

目前版本OQS有一种QueryFactory的实现。

org.opoo.oqs.spring.SpringQueryFactoryImpl 调用createQuery()可以创建一个org.opoo.oqs.spring.SpringQueryImpl的实例。

这个类继承自org.opoo.oqs.core.AbstractQueryFactory，AbstractQueryFactory定义了setDataSource(), setDialectClassName(), setConnectionManager()，setShowSql()等方法。要创建一个有效的QueryFactory，QueryFactory实现类、数据源（或者ConnectionManager)这两个重要的属性必须被指定。 showSql属性指定sql调试信息的显示级别，0不显示，1只显示SQL，>=2显示SQL和中间转换过程中产生的中间QS。方法的具体描述请参考API文档。

创建对象是dataSource和connectionManager属性二者选其一即可，指定了dataSource可以就不必设置connectionManager，而指定了connectionManager也不必再设置dataSource。

ConnectionManager是org.opoo.oqs.jdbc包中的一个接口，声明了获得数据库连接（getConnection()）和释放数据库连接（releaseConnection(java.sql.Connection conn)）的两个基本方法，用来管理数据库连接，您可以定制自己的ConnectionManager。

DataSource dataSource = ...;
QueryFactory qf = new SpringQueryFactoryImpl();//QueryFactory实现类
qf.setDataSource(dataSource);//数据源

或者 QueryFactory qf = new SpringQueryFactoryImpl(dataSource);

上例创建QueryFactory过程中将自动创建系统默认的ConnectionManager，用户不必再指定。

DataSource dataSource = ...;
//简单的实现
ConnectionManager manager = new ConnectionManager()
{
  public Connection getConnection() throws DataAccessException
  {
    try
    {
      return dataSource.getConnection();
    }
    catch(Exception e)
    {
      throw new DataAccessException(e);
    }
  }

  public void releaseConnection(Connection conn)
  {
    if(conn != null)
      try
      {
        conn.close();
      }
      catch(Exception e)
      {
      }
  }
};

QueryFactory qf = new SpringQueryFactoryImpl();//QueryFactory实现类
qf.setConnectionManager(manager);//数据连接管理器

上例中指定了QueryFactory的ConnectionManager，因此不必再指定DataSource。

AbstractQueryFactory定义了一个static方法来创建QueryFactory实例。

Query是一个面向对象的查询接口。Query的实例必须通过调用QueryFactory的createQuery方法来创建。例如：

QueryFactory qf = ...;
Query query = qf.createQuery("select count(*) from tabs");

Query的具体类型只与QueryFactory的类型有关。

Query主要包括一组set方法，用来设置查询所需的参数，同名重载的方法一般分别是绑定命名参数和占位参数的。 最基本的设置参数方法是：setParameter(String name, Object value, Type dataType)和setParameter(int index, Object value, Type dataType)，例如：

query.setParameter(0, value, DataTypes.INTEGER);

以上操作用来绑定一个Integer型的占位参数。等同于调用setInteger(0, ((Integer)value).intValue());

query.setParameter("name1", value, DataTypes.INTEGER);

以上操作用来绑定一个Integer型的命名参数。等同于调用setInteger("name1", ((Integer)value).intValue());

query.setParameterList("names", new String[]{"a","b","c"});

以上操作用来绑定一个值是数组的命名参数。功能于setParameterList(String, Collection)相同，一般数组或集合中的元素类型都是一致的，所以也可以调用setParameterList(String, Object[], Type)或者setParameterList(String, Collection, Type)，明确指出个元素的类型。

准备数据：samples中包含建表脚本（HSQLDB和MySQL两种版本），使用HSQLDB不必再创建数据库和表，不必初始化数据，如果使用MYSQL则需要手动创建库、表，并执行oqs-mysql-dataload初始化数据。

建表的HSQLDB脚本如下（userinfo2 为主键自增的表）：

create table userinfo (
id            bigint not null,
name          varchar(30) not null ,
age           int not null ,
regtime       datetime,
primary key (id) 
);

create table userinfo2 (
id            bigint generated by default as identity(start with 0,increment by 1) primary key,
name          varchar(30) not null ,
age           int not null ,
regtime       datetime,
primary key (id) 
);

编写java接口及类，分别用于测试映射到接口和类。

public interface UserInfo extends Serializable {
    Long getId();
    String getName();
    int getAge();
    Date getRegTime();
    void setName(String name);
    void setAge(int age);
    void setRegTime(Date date);
}

public class UserInfoImpl implements UserInfo {
    private Long id;
    private String name;
    private int age;
    private Date regTime;
    public UserInfoImpl() {
    }

    public int getAge() {
        return age;
    }

    public Long getId() {
        return id;
    }
......

示例包含3个配置文件，主配置文件samples.properties如下：

#是否使用spring的ApplicationContext来生成示例类的示例
oqs.useSpringBeanFactory=false

#oqs的配置文件在classpath中的位置
oqs.config=/oqs.properties

#指定使用spring的ApplicationContext时其配置文件的名称和位置
spring.config=applicationContext.xml

另外两个配置文件：oqs.properties指定了JDBC的参数和QueryFactory的参数，applicationContext.xml则是在使用Spring的容器生成类时所必需的配置文件。

示例包文件说明：

Main示例可以根据配置来决定是通过编程来创建Main实例还是从Spring容器中获取，代码如下：

public static void main(String[] args) {
  Main main = null;
  if(Samples.useSpringBeanFactory())
  {
    main = (Main) SpringBeanFactory.getAc().getBean("mainProxy");
  }
  else
  {
    QueryFactory qf = QueryFactoryFactory.getQueryFactory();
    main = new Main(qf);
  }
......

    public void inertData() {
        String sql = "insert into userinfo(id, name, age, regtime) values(?,?,?,?)";
        //单条插入
        int rows = factory.createQuery(sql)
                   .setLong(0, 7).setString(1, "test name").setInteger(2, 25).
                   setTimestamp(3, new Date()).executeUpdate();
        System.out.println(rows + " 条更新");

        //批量更新
        TypedValue[] tv1 = {new TypedValue(11L, Type.LONG),
                           new TypedValue("name0", Type.STRING),
                           new TypedValue(22, Type.INTEGER),
                           new TypedValue(new Date(), Type.TIMESTAMP)};
        TypedValue[] tv2 = {new TypedValue(12L, Type.LONG),
                           new TypedValue("name2", Type.STRING),
                           new TypedValue(32, Type.INTEGER),
                           new TypedValue(new Date(), Type.TIMESTAMP)};

        PreparedStatementBatcher batcher = factory.createBatcher(sql);
        int[] result = batcher.addBatch(tv1).addBatch(tv2).executeBatch();
        System.out.println(result.length);
    }

    public void insertIntoUserInfo2() {
        String sql = "insert into userinfo2(name, age, regtime) values(?,?,?)";
        Serializable id = factory.createQuery(sql).setString(0, "name0").
                          setInteger(1, 30).setTimestamp(2, new Date()).insert();
        System.out.println("自动产生的ID是：" + id);
    }

    //根据ID查找对象
    public UserInfo getUserInfo(long id){
        String sql = "select new UserInfoImpl(id, name, age, regTime)"
             + " from userinfo where id=?";
        return (UserInfo) factory.createQuery(sql).setLong(0, id).uniqueResult();
    }     

    public void update() {
        long id = 2;
        UserInfo ui = getUserInfo(id);
        System.out.println("before update: " + ui);
        factory.createQuery("update userinfo set name=? where id=?")
                .setString(0, "Another name").setLong(1, id)
                .executeUpdate();
        ui = getUserInfo(id);
        System.out.println("after update: " + ui);
    }

    public void update2(){
        String sql1 = "update userinfo set name=name1 where id=1";
        String sql2 = "update userinfo set name=name2 where id=2";
        factory.createBatcher().addBatch(sql1).addBatch(sql2).executeBatch();
        UserInfo u1 = getUserInfo(1);
        UserInfo u2 = getUserInfo(2);
        System.out.println("after update: \n" + u1 + "\n" + u2);
    }

  public void delete() {
      int rows = factory.createQuery("delete from userinfo2 where id=?")
           .setLong(0, 2).executeUpdate();
      System.out.println(rows);
  }   

    public void viewAllUserInfoImpl() {
        String sql = "select new UserInfoImpl(id, name, age, regTime) from userinfo";
        List<UserInfo> list = factory.createQuery(sql).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

    public void viewAllUserInfo() {
        String sql = "select new UserInfo(id, name, age, regTime) from userinfo";
        List<UserInfo> list = factory.createQuery(sql).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

    public void viewAllForMap() {
        String sql = "select new map(id, name, age, regTime) from userinfo";
        List<Map> list = factory.createQuery(sql).list();
        for (Map ui : list) {
            System.out.println(ui);
        }
    }

    public void viewAllForList() {
        String sql = "select new list(id, name, age, regTime) from userinfo";
        List<List> list = factory.createQuery(sql).list();
        for (List ui : list) {
            System.out.println(ui);
        }
    }

    public void viewAllForList2() {
        String sql = "select new list(*) from userinfo";
        List<List> list = factory.createQuery(sql).list();
        for (List ui : list) {
            System.out.println(ui);
        }
    }

    public void viewAllForMap2() {
        String sql = "select new map(id, name, new list(age, regTime) as thelist) from userinfo";
        List<Map> list = factory.createQuery(sql).list();
        for (Map map : list) {
            System.out.println(map);
        }
    }

    public void viewPagedUserInfo() {
        String sql = "select new UserInfoImpl(id, name, age, regTime) from userinfo";
        List<UserInfo> list = factory.createQuery(sql).setFirstResult(0)
           .setMaxResults(2).list();
        System.out.println(list.size() == 2);
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

    //使用占位参数的条件查询
    public void viewUserInfoWhere() {
        String sql = "select new UserInfoImpl(id, name, age, regTime)"
                     + " from userinfo where id > ?";
        List<UserInfo> list = factory.createQuery(sql).setLong(0, 2).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }
    //使用命名参数的条件查询
    public void viewUserInfoWhere2(){
        String sql = "select new UserInfoImpl(id, name, age, regTime)"
                     + " from userinfo where id > :id";
        List<UserInfo> list = factory.createQuery(sql).setLong("id", 2).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }
    //使用集合作为命名参数的值
    public void viewUserInfoWhere3() {
        String sql = "select new UserInfoImpl(id, name, age, regTime)"
                     + " from userinfo where id in (:id)";
        List<UserInfo> list = factory.createQuery(sql)
              .setParameterList("id",new Long[]{1L,2L})
              .list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

      public void viewUserInfoByCriteria(){
        String sql = "select new UserInfoImpl(id, name, age, regTime) from userinfo";
        Criterion c1 = Restrictions.gt("id", 1);
        Order order = Order.asc("name");
        List<UserInfo> list = factory.createCriteria(sql)
              .add(c1).addOrder(order).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

    public void viewUserInfoByCriteria2(){
        String sql = "select new UserInfoImpl(id, name, age, regTime) from userinfo";
        Criterion c1 = Restrictions.gt("id", 1);
        Criterion c2 = Restrictions.lt("id", 14);
        Order order = Order.asc("name").add(Order.asc("id"));
        Criterion c = Restrictions.logic(c1).and(c2);
        List<UserInfo> list = factory.createCriteria(sql)
              .add(c).addOrder(order).list();
        for (UserInfo ui : list) {
            System.out.println(ui);
        }
    }

      public void view2list() {
        String sql = "select new list(a.*(4)), new list(b.*), b.name"
                     + " from userinfo a, userinfo2 b"
                     + " where a.id=b.id";
        List<Object[]> list = factory.createQuery(sql).list();
        for (Object[] os : list) {
            System.out.println(os[0] + " -- " + os[1] + " -- " + os[2]);
        }
    }

OQS提供两种方式的编程式事务管理

我们通常推荐使用第一种。

第二种方式类似使用JTA UserTransaction API 或者Spring框架的PlatformTransactionManager。

TransactionTemplate tt = new TransactionTemplate(queryFactory);
Object result = tt.execute(new TransactionCallback() 
{
    public Object doInTransaction(QueryFactory qf) 
    {
        //execute your business logic here
        qf.createQuery("update userinfo set name='a'").executeUpdate();
        return qf.createQuery("select name from userinfo").list();
    }
});

Transaction tx = queryFactory.beginTransaction();
try
{
  //execute your business logic here
  tx.commit();
}
catch(Exception ex)
{
  tx.rollback();
  throw ex;
}

Transaction tx = queryFactory.beginTransaction();
try
{
  //execute your business logic here
  Connection conn = queryFactory.getConnectionManager().getConnection();
  //execute jdbc operations here
  queryFactory.getConnectionManager().releaseConnection(conn);  
  tx.commit();
}
catch(Exception ex)
{
  tx.rollback();
  throw ex;
}

    public void transaction() {
        Transaction tx = factory.beginTransaction();
        try {
            factory.createQuery("update userinfo set name='t1' where id=1").executeUpdate();
            factory.createQuery("update userinfo set name='t2' where id=2").executeUpdate();
            tx.commit();
        } catch (TransactionException ex) {
            tx.rollback();
            throw new QueryException(ex);
        }
    }

OQS借助Spring AOP实现声明式事务管理，如果您的系统里已经使用了Spring的BeanFactory等特性，那么使用声明式事务管理可以较少的影响到应用代码，并且拥有和Spring声明式事务管理同样的特性和性能，更多信息请阅读《Spring开发参考手册：事务管理》。

在定义一个OQS实现的Spring PlatformTransactionManager之前，必须先定义数据源以及QueryFactory：

<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
  <property name="driverClassName" value="${jdbc.driverClassName}"/>
  <property name="url" value="${jdbc.url}"/>
  <property name="username" value="${jdbc.username}"/>
  <property name="password" value="${jdbc.password}"/>
</bean>

<bean id="queryFactory" class="org.opoo.oqs.spring.SpringQueryFactoryImpl">
  <property name="dataSource" ref="dataSource"/>
  <property name="showSql" value="${query.show_sql}"/>
  <property name="dialectClassName" value="${query.dialectClassName}"/>
  <property name="beanClassLoader">
    <bean class="org.opoo.oqs.core.BeanClassLoader">
    <constructor-arg value="${query.bean_imports}"/>
    </bean>
  </property>
</bean>

OQS实现的Spring PlatformTransactionManager定义如下：

<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
  <property name="dataSource" ref="dataSource"/>
</bean>

如果使用JTA，我们需要使用通过JNDI获得的容器数据源，和一个JtaTransactionManager实现。JtaTransactionManager不需要知道数据源，或任何其他特定资源，因为它将使用容器的全局事务管理。

<bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName"><value>MySQLDS</value></property>
</bean>

<bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager"/>

<bean id="jndiTemplate" class="org.springframework.jndi.JndiTemplate">
  <property name="environment">
      <props>
        <prop key="java.naming.factory.initial">weblogic.jndi.WLInitialContextFactory</prop>
        <prop key="java.naming.provider.url">t3://localhost:7001</prop>
        <prop key="java.naming.security.principal">weblogic</prop>
        <prop key="java.naming.security.credentials">weblogic</prop>
      </props>
    </property>
</bean>

<bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName"><value>JDataStoreDS</value></property>
    <property name="jndiTemplate"><ref local="jndiTemplate"/></property>
</bean>


<bean id="transactionManager"
      class="org.springframework.transaction.jta.JtaTransactionManager">
  <property name="jndiTemplate"><ref local="jndiTemplate"/></property>
  <property name="userTransactionName">
    <value>weblogic/transaction/UserTransaction</value>
  </property>
</bean>

在使用声明式事务管理情况下，应用程序代码不需要任何更改。我们可以仅仅更改配置来更改管理事务的方式，即使这些更改意味这从局部事务转换到全局事务或者相反的转换。

通常通过TransactionProxyFactoryBean设置Spring事务代理。我们需要一个目标对象包装在事务代理中。这个目标对象一般是一个普通Java对象的bean。当我们定义TransactionProxyFactoryBean时，必须提供一个相关的Spring PlatformTransactionManager的引用和事务属性。 事务属性含有上面描述的事务定义。

<bean id="main" class="org.opoo.oqs.samples.Main">
  <property name="queryFactory" ref="queryFactory"/>
</bean>

<bean id="mainProxy" class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean">
  <property name="transactionManager" ref="transactionManager"/>
  <property name="target" ref="main"/>
  <property name="transactionAttributes">
    <props>
      <prop key="transaction2*">PROPAGATION_REQUIRED</prop>
    </props>
  </property>
</bean>

示例Mian的transaction2方法实现如下：

    public void transaction2() {
        factory.createQuery("update userinfo set name='t110' where id=1").executeUpdate();
        factory.createQuery("update userinfo set name='t220' where id=2").executeUpdate();
    }