2009/05/09

Using JDO with App Engine

つづき。Unowned relationshipとかどう訳すのがいいんでしょうねぇ。

それにしてもリレーション周りはよくわからない。

Using JDO with App Engine

Java Data Objects (JDO) is a standard interface for storing objects containing data into a database. The standard defines interfaces for annotating Java objects, retrieving objects with queries, and interacting with a database using transactions. An application that uses the JDO interface can work with different kinds of databases without using any database-specific code, including relational databases, hierarchical databases and object databases. As with other interface standards, JDO makes your application easy to port between different storage solutions.

Java Data Objects (JDO)はデータベースに、データを保持するオブジェクトを保存するための標準的なインターフェースです。この標準はJavaオブジェクトにアノテーションをつけるためのインターフェースを定義します。これによってクエリでオブジェクトを取得し、トランザクションを使ってデータベースと作業をします。 JDOインターフェースを利用したアプリケーションは、リレーショナルデータベース、階層データベース、オブジェクトデータベースを含む、データベース固有のコードを使うことなく、異なる種類のデータベースを利用することができます。ほかの標準インタフェースと同様に、JDOは、アプリケーションを異なるストレージソリューション間で簡単に移植できるようにします。

The App Engine Java SDK includes an implementation of JDO 2.3 for the App Engine datastore. The implementation is based on DataNucleus Access Platform, the open source reference implementation for JDO 2.3.

App Engine Java SDKは、App Engine datastoreのためにJDO 2.3の実装を含んでいます。この実装は、JDO2.3のオープンソースの参照実装であるDataNucleus Access Platformを基にしています。

See the Access Platform 1.1 documentation for more information about JDO. In particular, see "JDO Mapping" and "JDO API".

JDOについての詳細はthe Access Platform 1.1 documentationを参照してください。具体的には"JDO Mapping" と"JDO API"を参照してください。

Setting Up JDO

To use JDO to access the datastore, an App Engine app needs the following:

JDOをつかって、Datastoreにアクセスするには、App Engine アプリケーションは次のものが必要とします。

  • The JDO and DataNucleus App Engine plugin JARs must be in the app's war/WEB-INF/lib/ directory.
  • A configuration file named jdoconfig.xml must be in the app's war/WEB-INF/classes/META-INF/ directory, with configuration that tells JDO to use the App Engine datastore.
  • The project's build process must perform a post-compilation "enhancement" step on the compiled data classes to associate them with the JDO implementation.
  • JDOとDataNucleus App Engine プラグインのJARが、アプリケーションの war/WEB-INF/lib/ディレクトリにあること
  • jdoconfig.xmlという設定ファイルが、アプリケーションのwar/WEB-INF/classes/META-INF/ディレクトリにあり、JDOにApp Engine datastoreを使用することを伝える設定がされていること
  • プロジェクトのビルドプロセスで、post-compilation(コンパイル後)に「エンハンスメント(拡張)」ステップを実行し、コンパイルされたデータクラスがJDO実装と結び付けること

If you are using the Google Plugin for Eclipse, these three things are taken care of for you. The new project wizard puts the JDO and DataNucleus App Engine plugin JARs in the correct location, and creates the jdoconfig.xml file. The build process performs the "enhancement" step automatically.

Google Plugin for Eclipseを使用している場合、これら3つの面倒をみてくれます。新規プロジェクトウィザードはJDOとDataNucleus App Engine プラグインのJarを正しい場所に配置し、jdoconfig.xmlファイルを作成します。ビルドプロセスでは「エンハンスメント」ステップを自動的に実行します。

If you are using Apache Ant to build your project, you can use an Ant task included with the SDK to perform the enhancement step. You must copy the JARs and create the configuration file when you set up your project. See Using Apache Ant for more information about the Ant task.

Apache Antをプロジェクトのビルドで利用している場合は、SDKに含まれるAntタスクを使ってエンハンスメントステップを実行することができます。プロジェクトのセットアップのときにJAR ファイルのコピーと設定ファイルの作成が必要です。Antタスクの詳細についてはUsing Apache Antを参照してください。

Copying the JARs

The JDO and datastore JARs are included with the App Engine Java SDK. You can find them in the appengine-java-sdk/lib/user/orm/ directory.

JDOとDatastoreのJarはApp Engine Java SDKに含まれています。これらのファイルは appengine-java-sdk/lib/user/orm/にあります。

Copy the JARs to your application's war/WEB-INF/lib/ directory.

これらのJARを、アプリケーションの war/WEB-INF/lib/ディレクトリにコピーしてください。

Make sure the appengine-api.jar is also in the war/WEB-INF/lib/ directory. (You may have already copied this when creating your project.) The App Engine DataNucleus plugin uses this JAR to access the datastore.

また、appengine-api.jarがwar/WEB-INF/lib/ディレクトリにあることを確認してください。(プロジェクト作成時に既にコピーされているかもしれません)AppEngine DataNucleus pluginはDatastoreにアクセスするときにこのJarを利用します。

Creating the jdoconfig.xml File

The JDO interface needs a configuration file named jdoconfig.xml in the application's war/WEB-INF/classes/META-INF/ directory. You can create this file in this location directly, or have your build process copy this file from a source directory.

JDOインターフェースは jdoconfig.xml という設定ファイルが、アプリケーションの war/WEB-INF/classes/META-INF/ ディレクトリにあることを必要とします。この場所にこのファイルを直接作成することも、ビルドプロセスでソースディレクトリからコピーすることもできます。

Create the file with the following contents:

次の内容でこのファイルを作成してください。


<?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>

Enhancing Data Classes

JDO uses a post-compilation "enhancement" step in the build process to associate data classes with the JDO implementation.

JDOは、ビルドプロセスのコンパイル後の「エンハンスメント」ステップを使って、JDOの実装とデータクラスを結び付けます。

If you are using Eclipse, the Google Plugin for Eclipse does this step automatically when building.

Eclipseを使っている場合、Google Plugin for Eclipse はこのステップをビルド時に自動的に実行します。

If you are using Apache Ant, the SDK includes an Ant task to perform this step. See Using Apache Ant for more information on using the Ant task.

Apache Antを使っている場合、SDKにこのステップを実行するためのAntタスクを含んでいます。Antタスクの詳細はUsing Apache Antを参照してください。

You can perform the enhancement step on compiled classes from the command line with the following command:

次のコマンドをコマンドラインで実行することによっても、コンパイルされたクラスにエンハンスをすることができます。

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

The classpath must contain the JAR appengine-tools-api.jar from the appengine-java-sdk/lib/ directory, as well as all of your data classes.

classpathには appengine-java-sdk/lib/ ディレクトリにある appengine-tools-api.jarと、あなたの全てのデータクラスを含む必要があります。

For more information on the DataNucleus bytecode enhancer, see the DataNucleus documentation.

DataNucleusのバイトコードエンハンサの詳細については、the DataNucleus documentationを参照してください。

Getting a PersistenceManager Instance

An app interacts with JDO using an instance of the PersistenceManager class. You get this instance by instantiating and calling a method on an instance of the PersistenceManagerFactory class. The factory uses the JDO configuration to create PersistenceManager instances.

JDOと動作するアプリケーションは、PersistenceManagerクラスのインスタンスを使います。このインスタンスを取得するには、PersistenceManagerFactoryクラスのインスタンスのメソッドを呼びます。このファクトリはJDOコンフィギュレーションを利用して、PersistenceManagerのインスタンスを作成します。

Because a PersistenceManagerFactory instance takes time to initialize, an app should reuse a single instance. To enforce this, an exception is thrown if the app instantiates more than one PersistenceManagerFactory (with the same configuration name). An easy way to manage the PersistenceManagerFactory instance is to create a singleton wrapper class with a static instance, as follows:

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;
    }
}

The app uses the factory instance to create one PersistenceManager instance for each request that accesses the datastore.

アプリケーションは、Datastoreにアクセスする各リクエストごとに、1つのPersistenceManagerインスタンスを作成するため、このファクトリのインスタンスを使います。

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

import PMF;

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

You use the PersistenceManager to store, update and delete data objects, and to perform datastore queries.

PersistenceManagerをデータオブジェクトの保存、更新、削除したり、Datastoreへのクエリしたりするのに使います。

When you are done with the PersistenceManager instance, you must call its close() method. It is an error to use the PersistenceManager instance after calling its close() method.

PersistenceManagerインスタンスを使い終えたら、必ずclose()メソッドを呼ぶ必要があります。 close() メソッドを呼んだ後に、PersistenceManagerインスタンスを使用するとエラーが発生します。

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

Unsupported Features of JDO

The following features of the JDO interface are not supported by the App Engine implementation:

つぎのJDOインターフェースの機能は、App Engineでの実装ではサポートされていません。

  • Unowned relationships. You can implement unowned relationships using explicit Key values. JDO's syntax for unowned relationships may be supported in a future release.
  • Owned many-to-many relationships.
  • contains() syntax for query filters on Collection fields. You can test that a multi-valued property (a Collection field) has a value using an equality filter: collection == "value"
  • "Join" queries. You cannot use a field of a child entity in a filter when performing a query on the parent kind. Note that you can test the parent's relationship field directly in query using a key.
  • JDOQL grouping and other aggregate queries.
  • Polymorphic queries. You cannot perform a query of a class to get instances of a subclass. Each class is represented by a separate entity kind in the datastore.
  • IdentityType.DATASTORE for the @PersistenceCapable annotation. Only IdentityType.APPLICATION is supported.
  • There is currently a bug preventing preventing persistent fields on superclasses from being saved to the datastore. This will be fixed in a future release.
  • Unowned relationshp。Unowned relationshpは明示的なKeyを使うことで実装することができます。JDOのUnowned relationshpのための文法は今後のリリースでサポートされます。
  • Owned 多対多リレーション
  • コレクションフィールドに対するクエリフィルタであるcontains() 文法。 collection == "value" といった等式フィルタを使うことによって、複数の値を持つプロパティ(コレクションフィールド)の値をもっているか検証することができます。
  • 「Join」クエリ。子エントリのフィールドを使って、親をフィルタするクエリは使えません。キーを使って、親のリレーションシップフィールドを直接検証することはできます。
  • JDOQLグルーピングと他の集合クエリ
  • ポリモフィッククエリ。サブクラスのインスタンスを取得するためのクエリは実行できません。Datastore内では各クラスは別の種類として表されます。
  • IdentityType.DATASTORE を @PersistenceCapableアノテーションにつかえません。 IdentityType.APPLICATIONのみサポートしています。
  • バグを防ぐため、スーパークラスの永続化フィールドをDatastoreに保存しません。将来のリリースで修正されます。

0 件のコメント: