まずは、データとなるDocumentをどのように作成していくか、から説明していきましょう。Documentは、通常のクラスのようにnewでインスタンスを作成したりはしません。APIには、Documentインスタンスを作成するための専用ビルダーとして「Document.Builder」というクラスが用意されています。これをまずは用意する必要があります。

Document.Builderでは、まずこのクラスのインスタンスを作成した後、Documentに保存する項目となる「フィールド（Field）」の作成と組み込みを行なっていきます。このフィールドは、データベースのレコードにあるフィールドとほぼ同じイメージで考えてよいでしょう。これも、まずField.Builderというフィールド作成のためのクラスのインスタンスを用意し、これを使ってフィールドの設定を行なってから、Fieldを生成し、Document.Builderに組み込みます。

そして必要なデータをすべてフィールドとして組み込んだら、Document.BuilderからDocumentを生成し、保存をします。このとき、「インデックス（Index）」というインデックス管理のオブジェクトが必要になります。これにDocumentを追加することでデータが保存されるのです。

いろいろとオブジェクトが登場して割とわかりにくいので、Docment作成までの基本的な流れを整理していきましょう。


●Document.Builderの用意

1. Document.Builderを作成する

Document.Builder 変数 = Document.newBuilder();

まず、Document.Builderインスタンスを作成します。これはnewBuilderメソッドを呼び出すだけです。


●フィールドの作成と組み込み

2. Field.Builderを作成する

Field.Builder 変数 = Field.newBuilder();

フィールドの作成を行うには、まずFieldBuilderクラスのインスタンスを作成します。これはnewBuilderメソッドを呼び出して行います。

3. Fieldの名前を設定する

《Field.Builder》.setName( 名前 );

作成したField.Builderインスタンスのメソッドを呼び出し、フィールド名を設定します。

4. Fieldに値を設定する

《Field.Builder》.setText(《String》);
《Field.Builder》.setNumber(《double》);
《Field.Builder》.setText(《String》);
《Field.Builder》.setHTML(《String》);
《Field.Builder》.setAtom(《String》);
《Field.Builder》.setDate(《Date》);
《Field.Builder》.setLocale(《Locale》);

フィールドに値を設定します。設定できる値の種類は、テキスト・数値・日時・ロケール情報といったものになります。テキストは、通常のテキストの他、HTMLやAtomのデータも専用の種類として扱われます。

注意したいのは、日時です。これはsetDateで引数のDateインスタンスを値として設定するのですが、この引数にはごく普通に作成されたDateインスタンスを直接設定することはできません。Fieldクラスに用意されているメソッドを使い、以下のようにして変換されたDateインスタンスを用意し、これをsetDateで設定する必要があります。

《Field.Builder》.setDate(Field.date(《Date》));

5. Document.Builderに追加する

《Document.Builder》.addField(《Field.Builder》);

Field.Builderに名前と値の設定ができたら、Document.Builderの「addField」メソッドでフィールドを追加します。このメソッドの引数に、できあがったField.Builderインスタンスを指定すると、それをもとにDocument.Builderの中にFieldが追加されます。

以上の２～５までを必要なだけ繰り返し、保管するすべての値をフィールドとして組み込みます。


●Documentの作成

6. buildでオブジェクトを生成する

Document 変数 = 《Document.Builder》.build();

フィールドの組み込みが終わったら、「build」メソッドを呼び出してDocumentインスタンスを作成します。


――ようやく、Documentを作成できました。後はこれを保存するわけですが、しかしそのためには、今度は「Index」というものを作成しなければいけません。



「Index」というのは、文字通りデータベースのインデックスを管理するためのクラスです。なぜ、インデックスというがDocumentの保存に登場するのか？と思うかも知れませんが、実はDocumentは、このIndexに追加することで保存されるのです。

Indexは、そのインデックスに関する設定情報をまとめた「IndexSpec」というオブジェクトを引数に指定して作成をします。このIndexSpecは、インスタンスを作成するためのビルダークラスを使って作成をしていきます。

では、これも手順を細かく説明していきましょう。そして、IndexにDocumentを保存するまでひと通りできるようにしましょう。


●IndexSpec.Builderの作成

1. IndexSpec.newBuilderを用意する

IndexSpec.Builder 変数 = IndexSpec.newBuilder();

まず最初にインデックスに関する設定情報を管理するIndexSpecを作成するための「IndexSpec.Builder」クラスのインスタンスを作成します。ややこしいですが、要するにフィールドの場合と同じで、このインスタンスに設定を行なっていくわけです。

2. インデックス名を設定する

《IndexSpec.Builder》.setName(《String》);

インデックス名を設定するものです。引数に名前のテキストを指定して呼び出します。.これでIndexSpec.Builderの準備は完了です。

3. SearchService を用意する

SearchService 変数 = SearchServiceFactory.getSearchService();

続いて、Indexインスタンスを作成するわけですが、これにはまず、SearchServiceFactoryクラスの「getSearchService」を呼び出して、「SearchService」というクラスのインスタンスを用意します。

4. Indexを取得する

Index 変数 = 《SearchService》.getIndex(《IndexSpec.Builder》);

SearchServiceの「getIndex」メソッドでIndexインスタンスを取得します。引数には、先ほど用意しておいたIndexSpec.Builderインスタンスを指定します。


●DocumentをIndexに追加する

5. addでIndexに追加する

try {
    《Index》.add(《Document》);
} catch (RuntimeException e) {
    ……例外処理……
}

最後に、Indexの「add」メソッドで、Documentをインデックスに追加します。これで、ようやくDocumentがGAEサーバーに保管されました!　けっこう長かったですね……。