前言

此文档翻译于第一次学习 ORMLite 框架，如果发现当中有什么不对的地方，请指正。若翻译与原文档出现任何的不相符，请以原文档为准。原则上建议学习原英文文档。

----------------------------------------------------------------------------------------------

二、如何使用

2.1 配置 POJO

配置你的 POJO，使其能持久化到数据库，你需要做到下面的几件事：

1. 添加 @DatabaseTable 注解到每个需要持久化的 POJO 顶部，也可以使用 @Entity。
2. 添加 @DatabaseField 注解到每个需要持久化的成员属性上面，也可以使用 @@Column.
3. 保证每个需要持久化的 POJO 有 protect，或 public 修饰的无参的构造器。

2.1.1 添加 ORMLite 注解

从 Java5 开始支持的 annotations 作为一种特殊的代码标记，可以提供对于类，方法，字段的元信息。若要指定哪些类和字段来存储在数据库中，ORMLite 支持其自己的注释 (@DatabaseTable 和 @DatabaseField) 或使用 Java 扩展包 javax.persistenc 下提供的标准注解。请参阅使用标注批注。注解是最简单的方法来配置您的类，你也可以使用 Java 代码或 Spring XML 来配置类。请参见类配置一节.

对于 ORMLite 注解，每个需要持久化到数据库的 Java 类，你需要添加 @DatabaseTable 注解到类的上方。每一个被这个注解标注的 POJO 都将被持久化到数据库，例如：

@DatabaseTable(tableName = "accounts")
public class Account {
…

@DatabaseTable 注解有一个可选的参数 tablename 用来指定当前的 POJO 对应的数据库的表名。如果未指定，默认情况下使用的类名称。对于上面的示例中的每个 Account 对象将保持作为数据库中的 accounts 表中的行。如果未指定 tableName 参数，会使用 account 表。

对于高级的用户可能想要添加一个 daoClass 参数指定 DAO 对象，这个 daoClass 参数指定的 DAO， 将被 DaoManager 实例化。请参阅DaoManager。

此外，对于每一个 POJO，你需要添加 @DatabaseField 注解到每个需要保存到数据库的成员变量上。每个成员变量将作为数据库表中的记录的列。例如：

@DatabaseTable(tableName = "accounts")
public class Account {

    @DatabaseField(id = true)
    private String name;

    @DatabaseField(canBeNull = false)
    private String password;
    …

在上面的示例中，accounts 表中的没条记录有2个字段：

1. name 字段是一个字符串，同时也是数据库记录的标识（主键）。
2. password 字段是一个字符串，同时不能为空。

@DatabaseField 注解还可以设置以下的一些属性，该表没有对照翻译（详细属性介绍请看添加 ORMLite 注解）：

2.1.2 添加 javax.persistence 注解

你可以使用 javax.persistence 包下的 Java 标准注释用来取代 ORMList 定义的注释。你可以使用 javax.persistence 包下的 @Entity 来替代 @DatabaseTable 注释，例如：

@Entity(name = "accounts")
public class Account {
…

@Entity 有个可选参数 name 用来指定表名，如果没有设置该属性，将默认使用类名作为表名。

你也可以在每个属性上使用 javax.persistence 注释: @Column、 @Id、 @GeneratedValue、 @OneToOne、 @ManyToOne、 @JoinColumn和@Version，而不是@DatabaseField。例如：

@Entity(name = "accounts")
public class Account {

    @Id
    private String name;

    @Column(nullable = false)
    private String password;
    …

支持的 javax.persistence 有以下这些：

2.1.3 添加无参的构造函数

在添加完类和属性的注释之后，你还需要保证有一个被 protect 或 public 的无参的构造器。当 ORMLite 返回一个查询的对象时，ORMLite 使用 Java 反射调研构造器返回对象。

Account() {
    // all persisted classes must define a no-arg constructor
    // with at least package visibility
}

所以你最后一个例子拥有注释与构造函数的Account 类看起来应该是这样:

@DatabaseTable(tableName = "accounts")
public class Account {

    @DatabaseField(id = true)
    private String name;

    @DatabaseField(canBeNull = false)
    private String password;
    …

    Account() {
        // all persisted classes must define a no-arg constructor
        // with at least package visibility
    }
    …
}

2.2 可持久化的数据类型

下面的这些 Java 类型可以被 OEMLite 持久化到数据库。数据库的类型转换函数可以在把这些类型转换成 SQL 类型：

2.3 连接源

关于连接源，Android 用户应该看请参阅 Android 使用说明 一节。

为了使用数据库和 DAO 对象，您将需要配置 JDBC 调用 DataSource (见javax.sql.DataSource类) 和 ORMLite 调用 ConnectionSource。ConnectionSource 是一个连接到物理数据库的工厂类。

这里是一个示例，创建一个简单的连接源单列：

// single connection source example for a database URI
ConnectionSource connectionSource =
  new JdbcConnectionSource("jdbc:h2:mem:account");

此外，这个包下有一个相对简单的连接池类 JdbcPooledConnectionSource。当数据库连接被释放，而不是被关闭，被添加到内部列表中，他们可以在以后重复使用。当没有休眠的 connection 可以使用是就创建一个新的。JdbcPooledConnectionSource 是同步的，可以在多线程中使用。他可以设置关闭连接前的最大的空闲连接数量和最最长存活时间。

// pooled connection source
JdbcPooledConnectionSource connectionSource =
  new JdbcPooledConnectionSource("jdbc:h2:mem:account");
// only keep the connections open for 5 minutes
connectionSource.setMaxConnectionAgeMillis(5 * 60 * 1000);

JdbcPooledConnectionSource 拥有一个一直存活的线程，时常 ping 各个休眠的连接，关闭那些长时间没有验证通过的连接，保证连接的有效性。你还可以启用测试，在从连接池获取这个 connection 之前。

// change the check-every milliseconds from 30 seconds to 60
connectionSource.setCheckConnectionsEveryMillis(60 * 1000);
// for extra protection, enable the testing of connections
// right before they are handed to the user
connectionSource.setTestBeforeGet(true);

当您完成您的 ConnectionSource 时，要调用 close() 方法来关闭任何潜在的连接。下面的模式类似建议。

JdbcConnectionSource connectionSource =
    new JdbcPooledConnectionSource("jdbc:h2:mem:account");
try {
    // work with the data-source and DAOs
    …
} finally {
    connectionSource.close();
}

有许多其他高性能，更健壮的扩展数据源管理器可以来替换，你可以直接实例化自己，并将其包装在委托给它的DataSourceConnectionSource类。

// basic Apache data source
BasicDataSource dataSource = new BasicDataSource();
String databaseUrl = "jdbc:h2:mem:account";
dataSource.setUrl(databaseUrl);
// we wrap it in the DataSourceConnectionSource
ConnectionSource connectionSource =
  new DataSourceConnectionSource(dataSource, databaseUrl);

当你使用完 ConnectionSource 时，要调用 close(）方法来关闭任何潜在的连接。建议使用类似下面的模式：

JdbcConnectionSource connectionSource =
    new JdbcPooledConnectionSource("jdbc:h2:mem:account");
try {
    // work with the data-source and DAOs
    …
} finally {
    connectionSource.close();
}

很不幸，DataSource 接口没有关闭方法，所以你使用 DataSourceConnectionSource 你必须关闭底层数据源，通过操作 DataSourceConnectionSource 上的 close() 方法。

2.4 设置 DAOs

一旦你标注了注解类并且定义了你的 ConnectionSource，你就需要创建一个DAO（Data Access Object，这个类中包含对 POJO 的所有的数据库操作。每个DAO都有两个泛型参数：

1. 我们用 DAO 持久化的类。
2. 用于标记数据库行的 ID 字段，如果这个类没有 ID 字段，可以使用 Object 或者 void 作为第二个参数。例如，在上述Account类中，"名称"字段是 ID 列 (id = true) 所以 ID 类是String.

创建 DAO 的最简单的方式是使用 DaoManager 类的静态 方法 createDao。例如：

Dao<Account, String> accountDao =
  DaoManager.createDao(connectionSource, Account.class);
Dao<Order, Integer> orderDao =
  DaoManager.createDao(connectionSource, Order.class);

注意：你需要内置 ORMLite 功能， 你可以使用 DaoManager.createDao() 方法创建你自己的 DAO 类，他们可以被再次利用而不是再次生成。创建一个 DAO 是一个昂贵的操作，如果可能的话应该重用 DAOs 为有限的资源 (如手机) 的设备。

如果你想更好的类层次的结构，或者你想要添加更多的方法到你的 DAO 中，你应该考虑定义一个接口，它继承自Dao接口。这个接口不是必需的，但是他说一种好的模式，这样你在JDBC持久化上用的代码会更少。下面是一个相当于本手册前面章节 Account 类的 DAO 接口的示例：

/** Account DAO which has a String id (Account.name) */
public interface AccountDao extends Dao<Account, String> {
    // empty wrapper, you can add additional DAO methods here
}

然后在实现中，你应该扩展BaseDaoImpl基类。这里是您的 DAO 接口的示例实现：

/** JDBC implementation of the AccountDao interface. */
public class AccountDaoImpl extends BaseDaoImpl<Account, String>
  implements AccountDao {
    // this constructor must be defined
    public AccountDaoImpl(ConnectionSource connectionSource)
      throws SQLException {
        super(connectionSource, Account.class);
    }
}

要使用你自定义的 DAO 类，你需要将 daoClass 字段添加到 @DatabaseTable 上相应的实体类:

@DatabaseTable(daoClass = AccountDaoImpl.class)
public class Account {
   …
}

这是你需要做的所有的事，如果你需要定义一个自己的 DAO 类。如果有不需要不在基类中提供的特殊操作，你可以自由的将更多的方法添加到你的 DAO 接口和实现中。接口和实现，如果有需要不由道基类提供的特定操作。

如果你正在使用一个自定义的 DAO 一定要将 daoClass 参数添加到的您自定义的 DAO 类的 @DatabaseTable 注释。这被 DaoManager 内部实例化 Dao 时使用，请参阅DaoManager。

2.5 支持的数据库

ORMLite 支持以下数据库口味。他们有的需要遵循一些特定文档。请参阅 Supported Databases

• MySQL
• Postgres
• H2
• SQLite
• Android SQLite
• HSQLDB
• Microsoft SQL Server
• Netezza
• ODBC

2.6 整合

有一个被 annotation 标注的，添加了无参构造函数的 POJO 类，创建你的 ConnectionSource，并定义自己的 DAO 类。你准备开始坚持和查询数据库对象。如果你想要运行该示例，你需要下载和 H2 jar 文件添加到您的类路径，。请参阅H2 主页.

// h2 by default but change to match your database
String databaseUrl = "jdbc:h2:mem:account";
JdbcConnectionSource connectionSource =
  new JdbcConnectionSource(databaseUrl);

// instantiate the dao with the connection source
AccountDaoImpl accountDao = new AccountDaoImpl(connectionSource);

// if you need to create the ‘accounts‘ table make this call
TableUtils.createTable(connectionSource, Account.class);

// create an instance of Account
Account account = new Account("Jim Coakley");

// persist the account object to the database
accountDao.create(account);
…

// destroy the data source which should close underlying connections
connectionSource.destroy();

-----------------------------------------------------------------------------

由于本文档篇幅过长，之后的部分请参阅[翻译] ORMLite document -- How to Use Part (二)