Java Data Objects（JDO）は、Java でデータベースにアクセスするための標準インターフェースであり、Java のクラスとデータベースのテーブルとの間のマッピングを提供します。Datastore で JDO を使用するために利用できるオープンソースのプラグインがあります。このページでは、そのプラグインを使う方法について説明します。
警告: 多くのデベロッパーは、低水準の Datastore API を使用するか、Datastore 専用に開発された Objectify などのオープンソースの API を使用するほうが快適に作業できると思われます。JDO は、従来型のリレーショナル データベースに使用するように設計されているため、リレーショナル データベースとは異なる Datastore の特性（エンティティ グループや祖先クエリなど）を明示的に表す方法がありません。これは、理解や修正が困難な細かい問題の原因になることがあります。
App Engine Java SDK には、App Engine Datastore 用 JDO 2.3 の実装が含まれています。この実装は、JDO 2.3 のオープンソースのリファレンス実装である DataNucleus Access Platform のバージョン 1.0 に基づいています。
注: このページの手順は、App Engine 用 DataNucleus プラグインのバージョン 1.0 を使用している、JDO バージョン 2.3 に適用されます。現在、App Engine では、JDO 3.0 を実行可能な DataNucleus 2.x プラグインを提供しています。この新しいプラグインは、非所有関係をサポートしており、数々の新しい API と機能を提供します。このアップグレードには、前のバージョンとの完全な下位互換性はありません。JDO 3.0 を使用してアプリケーションを再構築する場合には、コードを更新し、再度テストを行う必要があります。新しいバージョンの詳細については、JDO 3.0 をご覧ください。アップグレードの詳細については、App Engine での JDO 3.0 の使用をご覧ください。
JDO 2.3 のセットアップ
データストアへのアクセスに JDO を使用するには、App Engine アプリが次の条件を満たしている必要があります。
- JDO と DataNucleus App Engine プラグイン JAR は、アプリの
war/WEB-INF/lib/ディレクトリにある必要があります。 jdoconfig.xmlという名前の JDO に App Engine データストアの使用を指示する構成を持つ構成ファイルが、アプリのwar/WEB-INF/classes/META-INF/ディレクトリに必要です。- プロジェクトのビルドプロセスで、コンパイル後の「拡張」手順をコンパイル済みのデータクラスに対して実行して、JDO 実装に関連付ける必要があります。
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>
Datastore の読み取りポリシーと呼び出し期限の設定
Datastore のクエリページで説明したように、Datastore の動作は、読み取りポリシー（強整合性と結果整合性）と呼び出し期限を設定することでカスタマイズできます。JDO では、<persistence-manager-factory> ファイルの jdoconfig.xml 要素に目的の値を指定することで、このカスタマイズを実施します。ある PersistenceManager インスタンスで行われるすべての呼び出しには、このマネージャーが PersistenceManagerFactory によって作成されたときの実際の構成値が使用されます。また、これらの値は 1 つの Query オブジェクトごとに設定をオーバーライドすることもできます。
PersistenceManagerFactory の読み取りポリシーを設定するには、名前が datanucleus.appengine.datastoreReadConsistency のプロパティを含めます。有効な値は、EVENTUAL と STRONG です。未指定の場合のデフォルトは STRONG です。これらの設定は、特定のエンティティ グループ内の祖先クエリにのみ適用される点に注意してください。祖先以外のクエリやクロスグループ クエリは、有効な読み取りポリシーの有無にかかわらず、常に結果整合性が保たれます。
<property name="datanucleus.appengine.datastoreReadConsistency" value="EVENTUAL" />
読み取りと書き込みに個別のデータストア呼び出し期限を設定できます。読み取りには、JDO の標準プロパティ javax.jdo.option.DatastoreReadTimeoutMillis を使用します。書き込みには、javax.jdo.option.DatastoreWriteTimeoutMillis を使用します。値は、ミリ秒単位の時間です。
<property name="javax.jdo.option.DatastoreReadTimeoutMillis" value="5000" /> <property name="javax.jdo.option.DatastoreWriteTimeoutMillis" value="10000" />
クロスグループ（XG）トランザクションを使用する場合は、次に示すプロパティを追加します。
<property name="datanucleus.appengine.datastoreEnableXGTransactions" value="true" />
異なる name 属性を使用して、同じ jdoconfig.xml ファイルに複数の <persistence-manager-factory> 要素を設定し、同じアプリで異なる構成の PersistenceManager インスタンスを使用できます。たとえば、次の jdoconfig.xml ファイルは、"transactions-optional" という名前と "eventual-reads-short-deadlines" という名前の 2 つの構成を確立します。
<?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> <persistence-manager-factory name="eventual-reads-short-deadlines"> <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"/> <property name="datanucleus.appengine.datastoreReadConsistency" value="EVENTUAL" /> <property name="javax.jdo.option.DatastoreReadTimeoutMillis" value="5000" /> <property name="javax.jdo.option.DatastoreWriteTimeoutMillis" value="10000" /> </persistence-manager-factory> </jdoconfig>
名前付きの構成セットで PersistenceManager を作成する方法については、後述の PersistenceManager インスタンスの取得をご覧ください。
データクラスの拡張
JDO はビルドプロセスでコンパイル後の「拡張」手順を使用して、データクラスを JDO の実装に関連付けます。
次に示すコマンドを使用して、コンパイルしたクラスに対する拡張手順をコマンドラインから実行できます。
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 インスタンスの初期化には時間がかかるため、1 つのアプリは 1 つのインスタンスを再利用します。これを強制するために、アプリケーションが（同じ設定名を持つ）複数の 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; } }
ヒント: "transactions-optional" は、jdoconfig.xml ファイル内の構成セットの名前を参照します。アプリで複数の構成セットを使用する場合は、このコードを拡張して、必要に応じて JDOHelper.getPersistenceManagerFactory() を呼び出すことをおすすめします。このコードにより、各 PersistenceManagerFactory のシングルトン インスタンスがキャッシュに保存されます。
アプリは、ファクトリ インスタンスを使用して、データストアにアクセスするリクエストごとに 1 つの PersistenceManager インスタンスを作成します。
import javax.jdo.JDOHelper; import javax.jdo.PersistenceManager; import javax.jdo.PersistenceManagerFactory; import PMF; // ... PersistenceManager pm = PMF.get().getPersistenceManager();
PersistenceManager は、データ オブジェクトの保存、更新、削除と、データストア クエリの実行に使用します。
PersistenceManager インスタンスの使用が終了したら、その close() メソッドを呼び出す必要があります。PersistenceManager インスタンスをその close() メソッドの呼び出し後に使用するとエラーが発生します。
try { // ... do stuff with pm ... } finally { pm.close(); }
サポートされていない JDO 2.3 の機能
次に示す JDO インターフェースの機能は、App Engine の実装ではサポートされていません。
- 非所有関係。明示的なキー値を使用して非所有関係を実装できます。非所有関係に関する JDO の構文は、将来のリリースでサポートされる可能性があります。
- 多対多の所有関係。
- 「結合」クエリ。親の種類に対してクエリを実行する場合は、フィルタで子エンティティのフィールドを使用することはできません。親の関係フィールドは、キーを使用することで、クエリで直接テストすることができます。
- JDOQL のグループ化とその他の集約クエリ。
- ポリモーフィック クエリ。クラスのクエリを実行して、サブクラスのインスタンスを取得することはできません。各クラスは、データストア内の個別のエンティティの種類として表されます。
@PersistenceCapableアノテーションのためのIdentityType.DATASTORE。IdentityType.APPLICATIONのみがサポートされています。- 現時点では、1 対多の所有関係で親と子が同じクラスである場合、ツリー構造のモデル化が困難になるというバグが存在します。これは、今後のリリースで修正される予定です。親と子のどちらかで明示的なキー値を格納すると、この問題を回避できます。
トランザクションの無効化と既存の JDO アプリの移植
JDO 構成では、datanucleus.appengine.autoCreateDatastoreTxns というプロパティを true に設定することをおすすめします。これは App Engine 固有のプロパティであり、データストア トランザクションをアプリケーション コード内で管理される JDO トランザクションに関連付けるように JDO の実装に指示するためのものです。新しいアプリを初めからビルドする場合は、このようにするとよいでしょう。ただし、App Engine での実行が必要な既存の JDO ベースのアプリケーションがある場合は、このプロパティの値を false に設定する別の永続構成の使用が必要になることもあります。
<?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="false"/> </persistence-manager-factory> </jdoconfig>
この設定が役立つ理由について理解するには、1 つのトランザクション内では同じエンティティ グループに属するオブジェクトにのみオペレーションを実行できることを思い出してください。従来型のデータベースを使用するようにビルドされたアプリケーションは、通常、トランザクション内で任意のレコードのセットを更新できる、グローバル トランザクションを使用できることを想定しています。App Engine データストアはグローバル トランザクションをサポートしていないため、グローバル トランザクションが利用できると想定しているコードでは例外がスローされます。コードベース全体（おそらくは巨大）を見直してトランザクション管理コードをすべて削除する代わりに、単にデータストアのトランザクションを無効にすることができます。これは、複数レコードの変更のアトミック性を想定しているコードに対処することにはなりませんが、アプリを動作させることはできます。それで、トランザクション コードのリファクタリングを一度に全部行うのではなく、段階的に必要に応じて実行できるようになります。