将 JDO 与 App Engine 配合使用

Java 数据对象 (JDO) 是用于将包含数据的对象存储在数据库中的标准接口。该标准定义用于对 Java 对象进行批注、通过查询检索对象，以及使用事务与数据库交互的接口。使用 JDO 接口的应用程序可以在不使用任何数据库特定的代码的情况下使用不同类型的数据库，包括关系数据库、层次数据库和对象数据库。至于其他接口标准，JDO 使您的应用程序可轻松地在不同的存储解决方案之间移植。

App Engine Java SDK 包括针对 App Engine 数据存储区的 JDO 2.3 的实现。该实现基于 DataNucleus 访问平台（JDO 2.3 的开放源代码参考实现）。

有关 JDO 的详细信息，请参阅访问平台 1.1 文档。详细而言，请参阅 JDO 映射和 JDO API。

• 设置 JDO
• 增强数据类
• 获取 PersistenceManager 实例
• 不支持的 JDO 功能

设置 JDO

要使用 JDO 访问数据存储区，App Engine 应用程序需进行以下设置：

• JDO 和 DataNucleus App Engine 插件 JAR 必须位于应用程序的 war/WEB-INF/lib/ 目录。
• 命名为 jdoconfig.xml 的配置文件必须位于应用程序的 war/WEB-INF/classes/META-INF/ 目录中，配置为使 JDO 使用 App Engine 数据存储区。
• 项目的构建过程必须对编译的数据类执行后编译“增强”步骤以使其与 JDO 实现相关联。

如果使用的是 Eclipse Google 插件，则以上三项已为您处理。新项目向导将 JDO 和 DataNucleus App Engine 插件 JAR 放置在正确的位置上，并创建 jdoconfig.xml 文件。构建过程自动执行“增强”步骤。

如果使用 Apache Ant 构建项目，您可以使用 SDK 内含的 Ant 任务来执行增强步骤。您必须在设置项目时复制 JAR 并创建配置文件。有关 Ant 任务的详细信息，请参阅使用 Apache Ant。

复制 JAR

JDO 和数据存储区 JAR 内含在 App Engine Java SDK 中。您可以在 appengine-java-sdk/lib/user/orm/ 目录中找到。

将 JAR 复制到您的应用程序的 war/WEB-INF/lib/ 目录中。

确保 appengine-api.jar 也在 war/WEB-INF/lib/ 目录中。（可能已在创建项目时进行过复制）App Engine DataNucleus 插件使用此 JAR 访问数据存储区。

创建 jdoconfig.xml 文件

JDO 接口需要应用程序的 war/WEB-INF/classes/META-INF/ 目录中的命名为 jdoconfig.xml 的配置文件。您可以直接在此位置上创建此文件，或者让您的构建过程从源目录复制此文件。

创建内容如下的文件：

<?xml version="1.0" encoding="utf-8"?>
<jdoconfig xmlns="http://java.sun.com/xml/ns/jdo/jdoconfig"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://java.sun.com/xml/ns/jdo/jdoconfig">

    <persistence-manager-factory name="transactions-optional">
        <property name="javax.jdo.PersistenceManagerFactoryClass"
            value="org.datanucleus.store.appengine.jdo.DatastoreJDOPersistenceManagerFactory"/>
        <property name="javax.jdo.option.ConnectionURL" value="appengine"/>
        <property name="javax.jdo.option.NontransactionalRead" value="true"/>
        <property name="javax.jdo.option.NontransactionalWrite" value="true"/>
        <property name="javax.jdo.option.RetainValues" value="true"/>
        <property name="datanucleus.appengine.autoCreateDatastoreTxns" value="true"/>
    </persistence-manager-factory>
</jdoconfig>

增强数据类

JDO 在构建过程中使用后编译“增强”步骤使数据类与 JDO 实现相关联。

如果使用的是 Eclipse，Eclipse Google 插件将在构建时自动执行此步骤。

如果使用的是 Apache Ant，则 SDK 包括一个 Ant 任务来执行此步骤。有关 Ant 任务的详细信息，请参阅使用 Apache Ant。

您可通过命令行使用以下命令来对编译类执行增强步骤：

java -cp classpath com.google.appengine.tools.enhancer.Enhance class-files

classpath 必须包含来自 appengine-java-sdk/lib/ 目录的 JAR appengine-tools-api.jar，以及所有数据类。

有关 DataNucleus 字节码增强器的详细信息，请参阅 DataNucleus 文档。

获取 PersistenceManager 实例

应用程序使用 PersistenceManager 类的实例和 JDO 交互。可通过实例化并调用 PersistenceManagerFactory 类的实例上的方法来获取此实例。工厂使用 JDO 配置来创建 PersistenceManager 实例。

由于 PersistenceManagerFactory 实例需要时间来初始化，因此应用程序应重复使用单个实例。为强制执行此操作，如果应用程序实例化一个以上 PersistenceManagerFactory（具有相同配置名称），将引发异常。管理 PersistenceManagerFactory 实例的一个简单方式是创建一个具有静态实例的单独包装器类，如下所示：

PMF.java

import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManagerFactory;

public final class PMF {
    private static final PersistenceManagerFactory pmfInstance =
        JDOHelper.getPersistenceManagerFactory("transactions-optional");

    private PMF() {}

    public static PersistenceManagerFactory get() {
        return pmfInstance;
    }
}

应用程序使用工厂实例来为访问数据存储区的每一请求创建一个 PersistenceManager 实例。

import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManager;
import javax.jdo.PersistenceManagerFactory;

import PMF;

// ...
    PersistenceManager pm = PMF.get().getPersistenceManager();

使用 PersistenceManager 来存储、更新和删除数据对象并执行数据存储区查询。

完成 PersistenceManager 实例时，您必须调用其 close() 方法。在调用实例的 close() 方法后使用 PersistenceManager 实例是错误的。

    try {
        // ... do stuff with pm ...
    } finally {
        pm.close();
    }

不支持的 JDO 功能

App Engine 实例不支持 JDO 接口的以下功能：

• 无主的关系。您可以使用显式 Key 值实现无主的关系。在未来版本中可能支持 JDO 的关于无主关系的语法。
• 有主的多对多关系。
• “Join”查询。当对父类型执行查询时，不可在过滤条件中使用子实体的字段。请注意，您可以用键直接在查询中测试父实体的关系字段。
• JDOQL 分组和其他聚合查询。
• 多态查询。您不可执行某一类的查询以获取子类的实例。各类都由数据存储区中的单独实体类型表示。
• 针对 @PersistenceCapable 批注的 IdentityType.DATASTORE。仅支持 IdentityType.APPLICATION。
• 目前，有阻止超类中的持久性字段保存到数据存储区中的错误。这将在未来版本中修复。