透過應用服務引擎使用 JDO

Java Data Object (JDO) 是一種標準介面，可將內含資料的物件儲存至資料庫。這個標準所定義的介面可用於註解 Java 物件、使用查詢擷取物件，以及透過交易與資料庫互動。使用 JDO 介面的應用程式不需要任何資料庫專用的程式碼，即可搭配不同種類的資料庫，包括關聯式資料庫、階層式資料庫和物件資料庫。和其他的介面標準一樣，JDO 可讓您的應用程式在不同的儲存解決方案之間輕鬆移植。

「應用服務引擎 Java SDK」包括適用於「應用服務引擎」資料存放區的 JDO 2.3。這個實作是以 DataNucleus Access Platform (JDO 2.3 的開放原始碼參照實作) 為基礎。

如需 JDO 的詳細資訊，請參閱 Access Platform 1.1 文件。另外，請特別參閱「JDO 對應」和 JDO API。

• 設定 JDO
• 強化資料類別
• 取得 PersistenceManager 實例
• 尚未支援的 JDO 功能

設定 JDO

如要使用 JDO 存取資料存放區，「應用服務引擎」需要下列設定：

• JDO 和 DataNucleus App Engine plugin JAR 必須位於應用程式的 war/WEB-INF/lib/ 目錄。
• jdoconfig.xml 設定檔必須位於應用程式的 war/WEB-INF/classes/META-INF/ 目錄，其設定應指示 JDO 使用「應用服務引擎」資料存放區。
• 專案的建置程序必須在編譯的資料類別上執行編譯後的「強化」步驟，為資料類別與 JDO 實作建立關聯。

如果您使用的是「Eclipse 專用的 Google 外掛程式」，它會為您完成這三項設定。新建專案精靈會將 JDO 和 DataNucleus App Engine plugin JAR 放在正確位置，並建立 jdoconfig.xml 檔案。建置程序會自動執行「強化」步驟。

如果您是透過 Apache Ant 建置專案，您可以使用 SDK 隨附的 Ant 工作執行強化步驟。設定專案時，您必須複製這些 JAR 並建立設定檔。如需 Ant 工作的詳細資訊，請參閱「使用 Apache Ant」。

複製 JAR

「應用服務引擎 Java SDK」內含 JDO 和資料存放區 JAR，您可以在 appengine-java-sdk/lib/user/orm/ 目錄中找到它們。

將 JAR 複製到應用程式的 war/WEB-INF/lib/ 目錄。

請確定 appengine-api.jar 也在 war/WEB-INF/lib/ 目錄中。(您在建立專案時可能已經複製)。「應用服務引擎」的 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 類別的實例上，建立方法的實例並呼叫方法，藉此取得這個實例。Factory 使用 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;
    }
}

應用程式使用 factory 實例，為每個存取資料存放區的要求建立一個 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 功能

「應用服務引擎」實作不支援下列 JDO 介面的功能：

• 非從屬關聯性。您可以使用明確的 Key 值來實作非從屬關聯性。未來的版本可能會支援適用於非從屬關聯性的 JDO 語法。
• 多對多的從屬關聯性。
• 「Join」查詢。在父系種類上執行查詢時，您無法在篩選器中使用子系實體的欄位。請注意，您可以使用金鑰，在查詢中直接測試父系的關聯性欄位。
• JDOQL 群組與其他的彙整查詢。
• 多型態查詢。您無法執行類別的查詢以取得子類別的實例。每個類別是由資料存放區中的個別實體種類代表之。
• @PersistenceCapable 註解的 IdentityType.DATASTORE。僅支援 IdentityType.APPLICATION。
• 目前有一個錯誤，導致超級類別上的持續性欄位無法儲存至資料存放區。在未來的版本中，我們將修正這個錯誤。