XEP Event Persistence の使用法

XepSimple サンプル・アプリケーション

以下のプログラムは、XEP と InterSystems IRIS の操作方法を示しています。この XepSimple は、小さなプログラムですが、XEP の主要機能のほとんどについて例を提供しているので、XEP API を使用する方法の概要を学ぶことができます。

このプログラムは 4 つのセクションに分かれており、それぞれが 4 つの主要 XEP クラス EventPersister、Event、EventQuery、および EventQueryIterator のいずれかを紹介しています。インポートされる xep.samples.SingleStringSample クラスは、このセクションの最後にリストされます。

クラス XepSimple

package xepsimple;
import com.intersystems.xep.*;
import xep.samples.SingleStringSample;

public class XepSimple {
  public static void main(String[] args) throws Exception {
// Generate 12 SingleStringSample objects for use as test data
    SingleStringSample[] sampleArray = SingleStringSample.generateSampleData(12);

// EventPersister
    EventPersister xepPersister = PersisterFactory.createPersister();
    xepPersister.connect("127.0.0.1",51774,"User","_SYSTEM","SYS"); // connect to localhost
    xepPersister.deleteExtent("xep.samples.SingleStringSample");   // remove old test data
    xepPersister.importSchema("xep.samples.SingleStringSample");   // import flat schema

// Event
    Event xepEvent = xepPersister.getEvent("xep.samples.SingleStringSample");
    for (int i=0; i < sampleArray.length; i++) {
      SingleStringSample sample = sampleArray[i];  // array initialized on line 8
      sample.name = "Sample object #" + i;
      xepEvent.store(sample);
      System.out.println("Persisted " + sample.name);
    }

// EventQuery
    String sqlQuery = "SELECT * FROM xep_samples.SingleStringSample WHERE %ID BETWEEN ? AND ?";
    EventQuery<SingleStringSample> xepQuery = xepEvent.createQuery(sqlQuery);
    xepQuery.setParameter(1,3);    // assign value 3 to first SQL parameter
    xepQuery.setParameter(2,12);   // assign value 12 to second SQL parameter
    xepQuery.execute();            // get resultset for IDs between 3 and 12

// EventQueryIterator
    EventQueryIterator<SingleStringSample> xepIter = xepQuery.getIterator();
    while (xepIter.hasNext()) {
      SingleStringSample newSample = xepIter.next();
      newSample.name = newSample.name + " has been updated";
      xepIter.set(newSample);
      System.out.println(newSample.name);
    }

    xepQuery.close();
    xepEvent.close();
    xepPersister.close();
  } // end main()
} // end class XepSimple

XepSimple は、以下のタスクを実行します。

• まず、サンプルのデータ・クラス xep.samples.SingleStringSample のメソッドを呼び出すことで、サンプルのオブジェクトがいくつか生成されます。

• EventPersister は、XEP の主なエントリ・ポイントで、データベースへの接続を提供します。

  このクラスは、xepPersister という名前のインスタンスを作成します。このインスタンスは、データベース内の User ネームスペースへの JDBC 接続を確立して、既存のサンプル・データをすべて削除します。次に、このクラスは、importSchema() を呼び出して、サンプル・クラスを分析し、スキーマをデータベースに送信します。その結果、SingleStringSample 永続オブジェクトを保持するエクステントが作成されます。

• Event は Java オブジェクトと対応するデータベース・オブジェクトとの間のインタフェースをカプセル化します。

  スキーマが生成されると、xepPersister は、サンプル・クラスに xepEvent という名前の Event オブジェクトを作成できます。ループで、SingleStringSample の各インスタンスに変更が加えられた後、これらのインスタンスがデータベースに永続化されます。xepEvent store() メソッドは、xepPersister で定義されている接続およびスキーマを利用します。

• EventQuery は、SQL クエリの準備と実行に使用されます。

  xepEvent オブジェクトの createQuery() メソッドにクエリ文字列を渡すことによって、xepQuery という名前の EventQuery<SingleStringSample> オブジェクトが作成されます。この文字列によって、2 つのパラメータ (? 文字) を受け取る SQL クエリが定義されます。setParameter() の呼び出しによってパラメータ値が定義され、execute() の呼び出しによってクエリの結果セットがフェッチされます。

• EventQueryIterator は、結果セットからの行の読み取り、および対応する永続オブジェクトの更新または削除に使用されます。

  xepQuery にはクエリの結果セットが含まれているので、getIterator() を呼び出すことによって、このオブジェクト用に xepIter という名前の反復子を作成できます。ループでこの反復子の next() メソッドが、データの各行を取得し、それを SingleStringSample オブジェクトに割り当てる処理に使用されます。次にこのオブジェクトに変更が加えられ、反復子の set() メソッドによって、データベース内の対応する永続オブジェクトが更新されます。

• 処理が完了したら、XEP オブジェクトに対して close() メソッドを呼び出すことによって、クリーン・アップが行われます。

以下に、XepSimple アプリケーションで使用されるサンプル・クラスのリストを示します。

xep.samples.SingleStringSample

  public class SingleStringSample {
    public  String name;
    public SingleStringSample() {}
    SingleStringSample(String str) {
        name = str;
    }

    public static SingleStringSample[] generateSampleData(int objectCount) {
        SingleStringSample[] data = new SingleStringSample[objectCount];
        for (int i=0;i<objectCount;i++) {
            data[i] = new SingleStringSample("single string test");
        }
        return data;
    }
  }

イベントの作成と格納

Event クラスのインスタンスは、以下のメソッドによって作成され、破棄されます。

• EventPersister.getEvent() — className String 引数を取り、指定したクラスのイベントを格納し、それにアクセスできる Event のインスタンスを返します。オプションで、インデックス・エントリを更新する既定の方法を指定する indexMode 引数を取ります (詳細は、“インデックス更新の制御” を参照してください)。

  Note:

  ターゲット・クラス

  Event のインスタンスは、getEvent() の呼び出しで className 引数によって指定されたクラスのイベントのみを格納、アクセス、または照会できます。この章では、クラス className をターゲット・クラスと呼びます。各例では、ターゲット・クラスは常に SingleStringSample です。

• Event.close() — この Event インスタンスを閉じ、それに関連するネイティブ・コード・リソースを解放します。

以下の Event メソッドは、ターゲット・クラスの Java オブジェクトを永続イベントとして格納します。

• store() — ターゲット・クラスの 1 つ以上のインスタンスをデータベースに追加します。引数として 1 つのイベント、または複数のイベントからなる 1 つの配列を取り、格納されているイベントごとに long データベース ID (データベース ID を返すことができない場合は 0) を返します。

  Important:

  イベントが格納されるときは、どのようなテストも行われず、既存のデータが変更されたり、上書きされることはありません。各イベントは、可能な限り速い速度でエクステントに追加されるか、指定されたキーを持つイベントが既にデータベースに存在する場合は暗黙的に無視されます。

以下の例では、ターゲット・クラスとして SingleStringSample を指定して Event のインスタンスを作成し、それを使用して Java SingleStringSample オブジェクトの配列を永続イベントとして投影します。この例では、myPersister が既に作成されて接続されており、SingleStringSample クラス (前述の “XepSimple サンプル・アプリケーション” にリストされています) のスキーマがインポートされていることを前提としています。

イベントの格納と変更 ： オブジェクトの配列の格納

  SingleStringSample[] eventItems = SingleStringSample.generateSampleData(12);
  try {
    Event newEvent = myPersister.getEvent("xep.samples.SingleStringSample");
    long[] itemIdList = newEvent.store(eventItems);  // store all events
    int itemCount = 0;
    for (int i=0; i < itemIdList.length; i++) {
      if (itemIdList[i]>0) itemCount++;
    }
    System.out.println("Stored " + itemCount + " of " + eventItems.length + " events");
    newEvent.close();
  }
  catch (XEPException e) {System.out.println("Event storage failed:\n" + e);}

• SingleStringSample の generateSampleData() メソッドは、12 個の SingleStringSample オブジェクトを生成し、それらを eventItems という名前の配列に格納します。

• EventPersister.getEvent() メソッドは、ターゲット・クラスとして SingleStringSample を指定して newEvent という名前の Event インスタンスを作成します。

• Event.store() メソッドが呼び出され、eventItems 配列内の各オブジェクトをデータベース内の永続イベントとして投影します。

  このメソッドは、itemIdList という名前の配列を返します。この配列には、正常に格納された各イベントの場合は long オブジェクト ID が、格納できなかったオブジェクトの場合は 0 が含まれます。変数 itemCount は、itemIdList の 0 より大きい各 ID に対して 1 回インクリメントされ、その合計が出力されます。

• ループが終了すると、Event.close() メソッドが呼び出されて、関連するリソースが解放されます。

格納されたイベントへのアクセス

永続イベントが格納されると、そのターゲット・クラスの Event インスタンスが、イベントを読み取り、更新、および削除するための以下のメソッドを提供します。

• deleteObject() — 引数としてデータベース・オブジェクト ID または IdKey を取り、データベースから指定したイベントを削除します。

• getObject() — 引数としてデータベース・オブジェクト ID または IdKey を取り、指定したイベントを返します。

• updateObject() — 引数としてデータベース・オブジェクト ID または IdKey およびターゲット・クラスの Object を取り、指定したイベントを更新します。

ターゲット・クラスが標準オブジェクト ID を使用する場合、それは long 値として指定されます (前のセクションで説明した store() メソッドで返されるとおり)。ターゲット・クラスが IdKey を使用する場合、それは Object の配列として指定され、その配列の各項目はその IdKey を構成するフィールドの 1 つの値です (“IdKey の使用法” を参照してください)。

以下の例では、配列 itemIdList には、前に格納された SingleStringSample イベントのオブジェクト ID 値のリストが含まれています。例では、リストの最初の 6 個の永続イベントを適宜更新し、残りを削除します。

イベントの格納と変更 ： イベントのフェッチ、更新、および削除

// itemIdList is a previously created array of SingleStringSample event IDs
  try {
    Event newEvent = myPersister.getEvent("xep.samples.SingleStringSample");
    int itemCount = 0;
    for (int i=0; i < itemIdList.length; i++) {
      try { // arbitrarily update events for first 6 IDs and delete the rest
        SingleStringSample eventObject = (SingleStringSample)newEvent.getObject(itemIdList[i]);
        if (i<6) {
          eventObject.name = eventObject.name + " (id=" + itemIdList[i] + ")" + " updated!";
          newEvent.updateObject(itemIdList[i], eventObject);
          itemCount++;
        } else {
          newEvent.deleteObject(itemIdList[i]);
        }
      }
      catch (XEPException e) {System.out.println("Failed to process event:\n" + e);}
    }
    System.out.println("Updated " + itemCount + " of " + itemIdList.length + " events");
    newEvent.close();
  }
  catch (XEPException e) {System.out.println("Event processing failed:\n" + e);}

• EventPersister.getEvent() メソッドは、ターゲット・クラスとして SingleStringSample を指定して newEvent という名前の Event インスタンスを作成します。

• 配列 itemIdList には、前に格納された SingleStringSample イベントのオブジェクト ID 値のリストが含まれています (itemIdList を作成した例は、“イベントの作成と格納” を参照してください)。

  ループでは、itemIdList の各項目が処理されます。最初の 6 つの項目は変更および更新され、残りの項目は削除されます。以下の処理が実行されます。

  • Event.getObject() メソッドが、itemIdList[i] に指定されたオブジェクト ID を持つ SingleStringSample オブジェクトをフェッチして、これを変数 eventObject に割り当てます。

  • eventObject name フィールドの値が変更されます。

  • eventObject がリストの最初の 6 項目の 1 つである場合は、Event.updateObject() が呼び出されてデータベース内でこれが更新されます。そうでない場合は、Event.deleteObject() が呼び出されて、データベースからオブジェクトが削除されます。

• itemIdList のすべての ID が処理されると、ループが終了し、更新されたイベントの数を示すメッセージが表示されます。

• Event.close() メソッドが呼び出されて、関連するリソースが解放されます。

簡単な SQL クエリによってフェッチされた永続イベントへのアクセス方法、およびその変更方法の詳細は、“クエリの使用法” を参照してください。

テスト・データベースを初期化する際は、多くの場合、クラス全体を削除するか、指定されたエクステントのすべてのイベントを削除すると便利です。以下の EventPersister メソッドは、クラスおよびエクステントを InterSystems IRIS データベースから削除します。

• deleteClass() — 引数として className 文字列を取り、指定した InterSystems IRIS クラスを削除します。

• deleteExtent() — 引数として className 文字列を取り、指定したクラスのエクステントのすべてのイベントを削除します。

これらのメソッドは主としてテスト用に提供されているので、実際に使用するコードでは使用しないようにしてください。これらの用語の詳しい定義については、"サーバ側プログラミングの入門ガイド" の “クラスとエクステント” を参照してください。

インデックス更新の制御

既定では、データベース内のイベントに対して動作する Event メソッドの 1 つの呼び出しを実行するときに、インデックスは更新されません (“格納されたイベントへのアクセス” を参照してください)。インデックスは非同期に更新され、更新は、すべてのトランザクションが完了し、Event インスタンスが閉じられた後にのみ実行されます。一意のインデックスに対して一意性のチェックは実行されません。

この既定のインデックス作成動作を変更する方法はいくつかあります。Event インスタンスが EventPersister.getEvent() によって作成される場合 (“イベントの作成と格納” を参照)、オプションの indexMode パラメータを設定して既定のインデックス作成動作を指定できます。以下のオプションを使用できます。

• Event.INDEX_MODE_ASYNC_ON — 非同期のインデックス作成を可能にします。これは、indexMode パラメータが指定されていない場合の既定の設定です。

• Event.INDEX_MODE_ASYNC_OFF — startIndexing() メソッドが呼び出されない限り、インデックス作成は実行されません。

• Event.INDEX_MODE_SYNC — インデックス作成は、エクステントが変更されるたびに実行されます。これは多数のトランザクションの場合は非効率的になる可能性があります。クラスにユーザ割り当て IdKey がある場合は、このインデックス・モードを指定する必要があります。

以下の Event メソッドを使用すると、ターゲット・クラスのエクステントに対する非同期インデックス更新を制御できます。

• startIndexing() — ターゲット・クラスのエクステントに対して非同期インデックス作成を開始します。インデックス・モードが Event.INDEX_MODE_SYNC である場合は、例外をスローします。

• stopIndexing() — エクステントに対する非同期インデックス作成を停止します。Event インスタンスを閉じるときにインデックスを更新しないようにする場合は、Event.close() を呼び出す前にこのメソッドを呼び出します。

• waitForIndexing() — int timeout 値を引数として取り、非同期インデックス作成が完了するまで待機します。timeout 値は、待機する秒数を指定します (-1 の場合は永久に待機し、0 の場合は直ちに返します)。インデックス作成が完了した場合は true を返し、インデックス作成が完了する前に待機がタイムアウトした場合は false を返します。インデックス・モードが Event.INDEX_MODE_SYNC である場合は、例外をスローします。

クエリの作成と実行

以下のメソッドは、EventQuery<T> のインスタンスを作成および破棄します。

• Event.createQuery() — SQL クエリのテキストを含む String 引数を取り、EventQuery<T> のインスタンスを返します。パラメータ T は、親 Event のターゲット・クラスです。

• EventQuery<T>.close() — この EventQuery<T> インスタンスを閉じ、それに関連するネイティブ・コード・リソースを解放します。

EventQuery<T> のインスタンスによって実行されるクエリは、指定した汎用タイプ T (クエリ・オブジェクトを作成した Event インスタンスのターゲット・クラス) の Java オブジェクトを返します。EventQuery<T> クラスによってサポートされるクエリは、以下に示すとおり、SQL の SELECT 文のサブセットです。

• クエリは、SELECT 節、FROM 節、および (オプションで) WHERE、ORDER BY などの標準 SQL 節から構成される必要があります。

• SELECT 節および FROM 節は、構文的に正当ですが、現実的にはクエリ実行中には無視されます。マップされているすべてのフィールドは、常に、ターゲット・クラス T のエクステントからフェッチされます。

• SQL 式は、任意の型の配列、組み込みオブジェクト、または組み込みオブジェクトのフィールドのいずれも参照できません。

• InterSystems IRIS システム生成オブジェクト ID は、%ID と呼ばれることがあります。先頭の % のおかげで、これはフィールドが呼び出した id と Java クラス内で競合しません。

以下の EventQuery<T> メソッドは、クエリを定義および実行します。

• setParameter() — この EventQuery<T> と関連付けられた SQL クエリのパラメータを結合します。int index および Object value を引数として取ります。ここで index は設定するパラメータを指定し、value は、指定されているパラメータに結合する値です。

• execute() — この EventQuery<T> と関連付けられた SQL クエリを実行します。クエリが正常に実行された場合、この EventQuery<T> には、後で説明するメソッドでアクセスできる結果セットが含まれます (“クエリ・データの処理” を参照してください)。

以下の例では、xep.samples.SingleStringSample エクステント内のイベントに対して単純なクエリを実行します。

クエリの使用法 ： クエリの作成と実行

  Event newEvent = myPersister.getEvent("xep.samples.SingleStringSample");
  EventQuery<SingleStringSample> myQuery = null;
  String sql =
    "SELECT * FROM xep_samples.SingleStringSample WHERE %ID BETWEEN ? AND ?";

  myQuery = newEvent.createQuery(sql);
  myQuery.setParameter(1,3);  // assign value 3 to first SQL parameter
  myQuery.setParameter(2,12);  // assign value 12 to second SQL parameter
  myQuery.execute();   // get resultset for IDs between 3 and 12

EventPersister.getEvent() メソッドは、ターゲット・クラスとして SingleStringSample を指定して newEvent という名前の Event インスタンスを作成します。

Event.createQuery() メソッドは、SQL クエリを実行してその結果セットを保持する myQuery という名前の EventQuery<T> のインスタンスを作成します。sql 変数には、2 つのパラメータ値の間の ID を持つターゲット・クラス内のすべてのイベントを選択する SQL 文が含まれています。

EventQuery<T>.setParameter() メソッドが 2 回呼び出されて、2 つのパラメータに値を割り当てます。

EventQuery<T>.execute() メソッドが呼び出されると、ターゲット・クラスのエクステントに対して指定されたクエリが実行され、結果セットが myQuery に格納されます。

既定では、結果セットの各オブジェクトのすべてのデータがフェッチされ、各オブジェクトが完全に初期化されます。各オブジェクトでフェッチされるデータの量および型を制限するオプションについては、“フェッチ・レベルの定義” を参照してください。

クエリ・データの処理

クエリが実行された後、ここに記載されているメソッドを使用して、クエリ結果セット内の項目にアクセスし、データベース内の対応する永続イベントを更新または削除できます。EventQueryIterator<T> クラスは、java.util.Iterator<T> を実装します (ここで T は親 EventQuery<T> インスタンスのターゲット・クラスです)。次の EventQuery<T> メソッドは、EventQueryIterator<T> のインスタンスを作成します。

• getIterator() — 現在の結果セットの EventQueryIterator<T> 反復子を返します。

EventQueryIterator<T> は、java.util.Iterator<T> メソッドである hasNext()、next()、および remove() と以下のメソッドを実装します。

• set() — ターゲット・クラスのオブジェクトを取り、それを使用して next() によって最後にフェッチされた永続イベントを更新します。

以下の例は、EventQueryIterator<T> のインスタンスを作成し、それを使用して結果セットの各項目を更新します。

クエリの使用法 ： EventQueryIterator<T> での反復

  myQuery.execute();  // get resultset
  EventQueryIterator<xep.samples.SingleStringSample> myIter = myQuery.getIterator();
  while (myIter.hasNext()) {
    currentEvent = myIter.next();
    currentEvent.name = "in process: " + currentEvent.name;
    myIter.set(currentEvent);
  }

EventQuery<T>.execute() の呼び出しによって、前の例で説明したクエリが実行されます (“クエリの作成と実行” を参照してください)。また、結果セットは myQuery に格納されます。結果セットの各項目は SingleStringSample オブジェクトです。

getIterator() を呼び出すと、現在 myQuery に格納されている結果セットの反復子 myIter が作成されます。

while ループにおいて、hasNext() は、結果セットのすべての項目が処理されるまで true を返します。

• next() の呼び出しによって、結果セットから次の SingleStringSample オブジェクトが返され、それが currentEvent に割り当てられます。

• currentEvent.name プロパティは変更されます。

• set() メソッドが呼び出され、更新された currentEvent オブジェクトがデータベースに格納されます。

SingleStringSample クラスのリストについては、“XepSimple サンプル・アプリケーション” を参照してください。

代替クエリ反復メソッド

EventQuery<T> クラスも、EventQueryIterator<T> を使用せずに結果セットを処理するのに使用できるメソッドを提供します(これは、ObjectScript で提供されるものと類似する反復メソッドを好む開発者向けの代替メソッドです)。クエリが実行された後、以下の EventQuery<T> メソッドを使用して、クエリ結果セット内の項目にアクセスし、データベース内の対応する永続イベントを更新または削除できます。

• getNext() — ターゲット・クラスの次のオブジェクトを結果セットから返します。結果セットにそれ以上項目がない場合は、null を返します。引数として null またはターゲット・クラスのオブジェクトが必要です(このリリースでは、引数はクエリに影響しないプレースホルダです)。

• updateCurrent() — 引数としてターゲット・クラスのオブジェクトを取り、それを使用して getNext() によって最後に返された永続イベントを更新します。

• deleteCurrent() — getNext() によって最後に返された永続イベントをデータベースから削除します。

• getAll() — getNext() を使用して結果セットからすべての項目を取得し、それらの項目を List で返します。更新または削除には使用できません。getAll() および getNext() は同じ結果セットにアクセスできません。一方のメソッドが呼び出されると、他方のメソッドは execute() が再び呼び出されるまで使用できません。

Id または IdKey によって特定された永続イベントへのアクセス方法、およびその変更方法の詳細は、“格納されたイベントへのアクセス” を参照してください。

Important:

EventQuery<T> および EventQueryIterator<T> 反復メソッドは同時に使用しない

クエリ結果には、EventQuery<T> メソッドを直接呼び出すか、または EventQueryIterator<T> のインスタンスを取得してそのメソッドを使用することによってアクセスできますが、これらのアクセス・メソッド両方を同時に使用しないでください。反復子を取得してそのメソッドを呼び出し、同時に EventQuery<T> メソッドも直接呼び出すと、予期できない結果を招く可能性があります。

クエリの使用法 ： クエリ・データの更新と削除

  myQuery.execute();   // get resultset
  SingleStringSample currentEvent = myQuery.getNext(null);
  while (currentEvent != null) {
    if (currentEvent.name.startsWith("finished")) {
      myQuery.deleteCurrent();   // Delete if already processed
    } else {
      currentEvent.name = "in process: " + currentEvent.name;
      myQuery.updateCurrent(currentEvent);    // Update if unprocessed
    }
    currentEvent = myQuery.getNext(currentEvent);
  }
  myQuery.close();

この例では、EventQuery<T>.execute() の呼び出しによって前の例で説明したクエリが実行されることが前提になっています (“クエリの作成と実行” を参照)。また、結果セットは myQuery に格納されます。結果セットの各項目は SingleStringSample オブジェクトです。

getNext() の最初の呼び出しによって、結果セットから最初の項目が取得され、それが currentEvent に割り当てられます。

while ループで、以下の処理が結果セットの各項目に適用されます。

• currentEvent.name が文字列 "finished" で始まる場合、deleteCurrent() は対応する永続イベントをデータベースから削除します。

• それ以外の場合、currentEvent.name の値が変更され、updateCurrent() が呼び出されます。これは currentEvent を引数として取り、これを使用してデータベースの永続イベントを更新します。

• getNext() の呼び出しによって、結果セットから次の SingleStringSample オブジェクトが返され、それが currentEvent に割り当てられます。

ループが終了した後、close() が呼び出され、myQuery に関連付けられたネイティブ・コード・リソースを解放します。

Note:

リソースを解放するために必ず close() を呼び出す

接続に関連するすべてのロック、ライセンス、およびその他のリソースを確実に解放するために、範囲外になる前に必ず EventPersister のインスタンスで close() を呼び出します。

フェッチ・レベルの定義

フェッチ・レベルは、クエリを実行するときに返されるデータの量を制御するために使用できる Event プロパティです。これは、基礎となるイベントが複雑で、かつイベント・データの小さいサブセットのみが必要な場合に特に便利です。

以下の EventQuery<T> メソッドは、現在のフェッチ・レベルを設定し、返します。

• getFetchLevel() — Event の現在のフェッチ・レベルを示す int を返します。

• setFetchLevel() — 引数として Event フェッチ・レベル列挙の値の 1 つを取り、そのフェッチ・レベルを Event に対して設定します。

以下のフェッチ・レベル値がサポートされます。

• Event.OPTION_FETCH_LEVEL_ALL — これが既定です。すべてのデータがフェッチされ、返されるイベントは完全に初期化されます。

• Event.OPTION_FETCH_LEVEL_DATATYPES_ONLY — データ型フィールドのみがフェッチされます。これには、すべてのプリミティブ型、すべてのプリミティブ・ラッパ、java.lang.String、java.math.BigDecimal、java.util.Date、java.sql.Date、java.sql.Time、java.sql.Timestamp、および enum 型が含まれます。その他のフィールドはすべて null に設定されます。

• Event.OPTION_FETCH_LEVEL_NO_ARRAY_TYPES — 配列を除くすべてのタイプがフェッチされます。ディメンジョンに関係なく、配列タイプのすべてのフィールドは null に設定されます。すべてのデータ型、オブジェクト・タイプ (シリアル化タイプを含む) およびコレクションがフェッチされます。

• Event.OPTION_FETCH_LEVEL_NO_COLLECTIONS — java.util.List、java.util.Map、および java.util.Set の実装を除くすべてのタイプがフェッチされます。

• Event.OPTION_FETCH_LEVEL_NO_OBJECT_TYPES — オブジェクト・タイプを除くすべてのタイプがフェッチされます。シリアル化タイプもオブジェクト・タイプと見なされ、フェッチされません。すべてのデータ型、配列タイプ、およびコレクションがフェッチされます。

スキーマ・インポート・モデル

XEP は、フラット・スキーマとフル・スキーマの 2 つの異なるスキーマ・インポート・モデルを提供しています。これらのモデル間の主な相違は、Java オブジェクトが InterSystems IRIS イベントに投影される方法です。

• 埋め込みオブジェクト・プロジェクション・モデル (フラット・スキーマ) — フラット・スキーマ をインポートします。そのスキーマでは、インポートされたクラスによって参照されるオブジェクトがすべてシリアル化されて埋め込まれ、すべての上位クラスで宣言されたフィールドはすべて、それらが、インポートされたクラス自体で宣言されているかのように収集され、投影されます。そのクラスのインスタンスのすべてのデータは、単一の InterSystems IRIS %Library.PersistentOpens in a new tab オブジェクトとして格納され、元の Java クラス構造に関する情報は保持されません。

• フル・オブジェクト・プロジェクション・モデル (フル・スキーマ) — フル・スキーマ をインポートします。そのスキーマでは、インポートされたクラスによって参照されるオブジェクトがすべて別の InterSystems IRIS %PersistentOpens in a new tab オブジェクトとして投影されます。継承されたフィールドは、同様に InterSystems IRIS %PersistentOpens in a new tab クラスにインポートされている上位クラスのフィールドへの参照として投影されます。Java ソース・クラスと InterSystems IRIS の投影されたクラスの間には 1 対 1 の対応があるため、Java クラス継承構造が保持されます。

フル・オブジェクト・プロジェクションでは、元の Java クラスの継承構造が保持されますが、パフォーマンスに影響する場合があります。パフォーマンスが重要であり、イベント・スキーマが比較的単純である場合、フラット・オブジェクト・プロジェクションが最適な選択になります。パフォーマンスの低下を許容できる場合、より豊富な機能および複雑なスキーマのために、フル・オブジェクト・プロジェクションを使用できます。

埋め込みオブジェクト・プロジェクション・モデル (フラット・スキーマ)

既定では、XEP は、平坦化することで参照オブジェクトを投影するスキーマをインポートします。つまり、インポートされたクラスによって参照されるオブジェクトがすべてシリアル化されて埋め込まれ、すべての上位クラスで宣言されたフィールドはすべて、それらが、インポートされたクラス自体で宣言されているかのように収集され、投影されます。対応する InterSystems IRIS イベントは、%Library.PersistentOpens in a new tab を拡張し、シリアル化されて埋め込まれたオブジェクト (元の Java オブジェクトに外部オブジェクトへの参照が含まれていた) を含んでいます。

つまり、フラット・スキーマでは、厳密な意味での継承は InterSystems IRIS 側に保持されません。例えば、以下の 3 つの Java クラスを考えてみます。

class A {
    String a;
}
class B extends class A {
    String b;
}
class C extends class B {
    String c;
}

クラス C をインポートすると、以下の InterSystems IRIS クラスができます。

Class C Extends %Persistent ... {
     Property a As %String;
     Property b As %String;
     Property c As %String;
}

対応する InterSystems IRIS イベントは、特別にインポートしない限り、A と B のいずれのクラスに対しても生成されません。InterSystems IRIS 側のイベント C は、A も B も拡張しません。インポートされると A および B は、以下の構造になります。

Class A Extends %Persistent ... {
     Property a As %String;
}
Class B Extends %Persistent ... {
     Property a As %String;
     Property b As %String;
}

すべての処理は、対応する InterSystems IRIS イベントに対してのみ実行されます。例えば、タイプ C のオブジェクトに対して store() を呼び出すと、対応する C InterSystems IRIS イベントのみが格納されます。

Java の子クラスが、そのスーパークラスでも宣言される同じ名前のフィールドを非表示にすると、XEP エンジンは常にその子フィールドの値を使用します。

アノテーションの使用法

XEP エンジンは、Java クラスを調べることで、XEP イベント・メタデータを推測します。追加情報は、アノテーションを使用して Java クラスで指定できます。アノテーションは com.intersystems.xep.annotations パッケージにあります。Java オブジェクトは、XEP 永続イベントの定義に準拠している限り (“インポートされるクラスの要件” を参照してください)、InterSystems IRIS イベントとして投影され、カスタマイズは必要ありません。

アノテーションには、投影されるクラス内の個別のフィールドに適用されるものと、クラス全体に適用されるものがあります。

• フィールド・アノテーション — インポートされるクラスのフィールドに適用されます。

  • @Id — そのフィールドが IdKey として機能するようになることを指定します。

  • @Serialized — フィールドをシリアル化形式で格納および取得する必要があることを示します。

  • @Transient — フィールドをインポートから除外する必要があることを示します。

• クラス・アノテーション — インポートされるクラス全体に適用されます。

  • @Embedded — フル・スキーマでこのクラスのフィールドを、参照ではなく (フラット・スキーマと同様に) 埋め込みとする必要があることを示します。

  • @Index — クラスのインデックスを宣言します。

  • @Indices — 同じクラスの複数のインデックスを宣言します。

@Id (フィールド・レベル・アノテーション)

@Id でマークされたフィールドの値は、標準のオブジェクト ID を置換する IdKey として使用されます (“IdKey の使用法” を参照してください)。このアノテーションは、クラスごとに 1 つのフィールドでのみ使用でき、そのフィールドは String、int、または long である必要があります (double は許容されますが推奨されません)。複合 IdKey を作成するには、代わりに @Index アノテーションを使用します。@Id でマークされたクラスは、@Index を使用して複合プライマリ・キーを宣言することもできません。両方のアノテーションが同じクラスに対して使用されている場合、例外がスローされます。

以下のパラメータを指定する必要があります。

• generated — XEP がキー値を生成する必要があるかどうかを指定する boolean。

  • generated = true — (既定の設定) キー値は InterSystems IRIS によって生成され、@Id でマークされたフィールドは Long である必要があります。このフィールドは、挿入または保存の前は null であることが前提となっており、そのような操作の完了時に XEP によって自動的に入力されます。

  • generated=false — マークされたフィールドのユーザ割り当て値が IdKey 値として使用されます。フィールドは、String、int、Integer、long、または Long にできます。

次の例では、ssn フィールドのユーザ割り当て値がオブジェクト ID として使用されます。

import com.intersystems.xep.annotations.Id;
public class Person {
  @Id(generated=false)
  Public String  ssn;
  public String  name;
  Public String dob;
}

@Serialized (フィールド・レベル・アノテーション)

@Serialized アノテーションは、該当のフィールドをシリアル化形式で格納および取得する必要があることを示します。

このアノテーションは、java.io.Serializable インタフェース (配列を含みます。これは暗黙的にシリアル化可能です) を実装するフィールドの格納を最適化します。XEP エンジンは、データの格納または取得のための既定のメカニズムを使用するのではなく、シリアル・オブジェクト用の関連する読み取りまたは書き込みメソッドを呼び出します。マークされたフィールドがシリアル化可能でない場合は、例外がスローされます。シリアル化フィールドの投影の詳細は、“データ型のマッピング” を参照してください。

例 ：

import com.intersystems.xep.annotations.Serialized;
public class MyClass {
  @Serialized
  public  xep.samples.Serialized   serialized;
  @Serialized
  public  int[][][][]   quadIntArray;
  @Serialized
  public  String[][]   doubleStringArray;
}

// xep.samples.Serialized:
public class Serialized implements java.io.Serializable {
  public  String  name;
  public  int     value;
}

@Transient (フィールド・レベル・アノテーション)

@Transient アノテーションは、該当のフィールドをインポートから除外する必要があることを示します。アノテーションを付けられたフィールドは、InterSystems IRIS に投影されず、イベントが格納される、またはロードされるときに無視されます。

例 ：

import com.intersystems.xep.annotations.Transient;
public class MyClass {
  // this field will NOT be projected:
  @Transient
  public  String  transientField;

  // this field WILL be projected:
  public  String  projectedField;
}

@Embedded (クラス・レベル・アノテーション)

@Embedded アノテーションは、フル・スキーマが生成される場合に使用できます (“スキーマ・インポート・モデル” を参照してください)。InterSystems IRIS に投影するときに、このクラスのフィールドを、参照ではなく (フラット・スキーマと同様に) シリアル化して埋め込む必要があることを示します。

例 ：

import com.intersystems.xep.annotations.Embedded;
@Embedded
public class Address {
  String  street;
  String  city;
  String  zip;
  String  state;
}

import com.intersystems.xep.annotations.Embedded;
public class MyOuterClass {
  @Embedded
  public static class MyInnerClass {
    public String   innerField;
  }
}

@Index (フィールド・レベル・アノテーション)

@Index アノテーションを使用して、インデックスを宣言できます。

以下のパラメータに引数を指定する必要があります。

• name — 複合インデックスの名前を含む String。

• fields — 複合インデックスを構成するフィールドの名前を含む String の配列。

• type — インデックス・タイプ。xep.annotations.IndexType 列挙には、以下の使用可能なタイプがあります。

  • IndexType.none — 既定値。インデックスがないことを示します。

  • IndexType.bitmap — ビットマップ・インデックス ("InterSystems SQL の使用法" の “ビットマップ・インデックス” を参照してください)。

  • IndexType.bitslice — ビットスライス・インデックス ("InterSystems SQL の使用法" の “概要” を参照してください)。

  • IndexType.simple — 1 つ以上のフィールドに対する標準インデックス。

  • IndexType.idkey — 標準 ID の代わりに使用されるインデックス (“IdKey の使用法” を参照してください)。

例 ：

import com.intersystems.xep.annotations.Index;
import com.intersystems.xep.annotations.IndexType;

@Index(name="indexOne",fields={"ssn","dob"},type=IndexType.idkey)
public class Person {
  public String  name;
  public Date dob;
  public String  ssn;
}

@Indices (クラス・レベル・アノテーション)

@Indices アノテーションを使用すると、1 つのクラスに対してさまざまなインデックスからなる 1 つの配列を指定できます。その配列の各要素は、@Index タグです。

例 ：

import com.intersystems.xep.annotations.Index;
import com.intersystems.xep.annotations.IndexType;
import com.intersystems.xep.annotations.Indices;

@Indices({
  @Index(name="indexOne",fields={"myInt","myString"},type=IndexType.simple),
  @Index(name="indexTwo",fields={"myShort","myByte","myInt"},type=IndexType.simple)
})
public class MyTwoIndices {
  public int  myInt;
  public Byte  myByte;
  public short  myShort;
  public String  myString;
}

IdKey の使用法

IdKey は、既定のオブジェクト ID の代わりに使用されるインデックス値です。単純 IdKey と複合 IdKey のどちらも XEP によってサポートされており、フル・スキーマでインポートされる Java クラスにはユーザ生成 IdKey が必要です (“スキーマのインポート” を参照してください)。単一フィールドに対する IdKey は @Id アノテーションで作成できます。複合 IdKey を作成するには、IndexType idkey と共に @Index アノテーションを追加します。例えば、以下のクラスを指定したとします。

  class Person {
    String name;
    Integer id;
    Date dob;
  }

既定のストレージ構造では、添え字として標準オブジェクト ID を使用します。

^PersonD(1)=$LB("John",12,"1976-11-11")

以下のアノテーションは、name および id フィールドを使用して、標準オブジェクト ID を置き換える newIdKey という名前の複合 IdKey を作成します。

  @Index(name="newIdKey",fields={"name","id"},type=IndexType.idkey)

これは、以下のグローバル構造になります。

^PersonD("John",12)=$LB("1976-11-11")

XEP では、SQL コマンドなど他の方法で追加された IdKey も処理されます ("InterSystems SQL の使用法" の “インデックスでの Unique、PrimaryKey、IDKey キーワードの使用” を参照してください)。XEP エンジンは、基本クラスに IdKey が含まれているかどうかを自動的に判別し、適切なグローバル構造を生成します。

IdKey の使用法にはいくつかの制限があります。

• IdKey 値は一意である必要があります。IdKey がユーザ生成である場合、一意性は呼び出し元のアプリケーションで確保する必要があり、XEP によって強制されることはありません。アプリケーションで、データベースに既に存在しているキー値を持つイベントの追加が試みられると、その試みは暗黙的に無視され、既存のイベントは変更されません。

• IdKey を宣言するクラスには、それが他のインデックスも宣言している場合、非同期にインデックスを付けることはできません。

• 複合 IdKey ではフィールドの数に制限はありませんが、フィールドが String、int、Integer、long、または Long であることが必要です。double も使用できますが、非推奨です。

• 非常に高い継続的な挿入レートを必要とするまれな特定の状況では、パフォーマンスが低下することがあります。

IdKey に基づくイベントの取得、更新、および削除を可能にする Event メソッドの説明は、“格納されたイベントへのアクセス” を参照してください。

IdKey および標準 InterSystems IRIS ストレージ・モデルの詳細は、"グローバルの使用法" の “多次元ストレージの SQL およびオブジェクトの使用法” を参照してください。SQL での IdKey の詳細は、"InterSystems SQL の使用法" の “インデックスの定義と構築” を参照してください。

InterfaceResolver の実装

フラット・スキーマがインポートされるとき、継承階層に関する情報は保持されません (“スキーマ・インポート・モデル” を参照してください)。これにより、インタフェースとして宣言されているタイプを持つフィールドを処理するときに問題が発生します。これは、XEP エンジンは、フィールドの実際のクラスを把握する必要があるためです。既定では、そのようなフィールドはフラット・スキーマにインポートされません。この動作は、com.intersystems.xep.InterfaceResolver の実装を作成し、処理中に特定のインタフェース・タイプを解決することで、変更できます。

InterfaceResolver の実装は、フラット・スキーマ・インポート・メソッド importSchema() を呼び出す前に EventPersister に渡されます (“スキーマのインポート” を参照してください)。これにより、XEP エンジンに、処理中にインタフェース・タイプを解決する方法が提供されます。以下の EventPersister メソッドは、使用される実装を指定します。

• EventPersister.setInterfaceResolver() — 引数として InterfaceResolver のインスタンスを取ります。importSchema() が呼び出されると、指定されたインスタンスを使用して、インタフェースとして宣言されたフィールドを解決します。

以下の例は、クラスごとに InterfaceResolver の異なるカスタマイズされた実装を呼び出して、2 つの異なるクラスをインポートします。

スキーマのカスタマイズ ： InterfaceResolver の適用

  try {
    myPersister.setInterfaceResolver(new test.MyFirstInterfaceResolver());
    myPersister.importSchema("test.MyMainClass");

    myPersister.setInterfaceResolver(new test.MyOtherInterfaceResolver());
    myPersister.importSchema("test.MyOtherClass");
  }
  catch (XEPException e) {System.out.println("Import failed:\n" + e);}

setInterfaceResolver() の最初の呼び出しによって、インポート・メソッドの呼び出し中に使用する実装として MyFirstInterfaceResolver (次の例で説明) の新しいインスタンスが設定されます。この実装は、setInterfaceResolver() が再び呼び出されて別の実装が指定されるまで、importSchema() のすべての呼び出しで使用されます。

importSchema() の最初の呼び出しで、クラス test.MyMainClass がインポートされます。これには、インタフェース test.MyFirstInterface として宣言されたフィールドが含まれています。MyFirstInterfaceResolver のインスタンスが、そのインポート・メソッドで使用され、このフィールドの実際のクラスが解決されます。

setInterfaceResolver() の 2 回目の呼び出しによって、importSchema() が再び呼び出されたときに使用する新しい実装として別の InterfaceResolver クラスのインスタンスが設定されます。

InterfaceResolver のすべての実装で、以下のメソッドを定義する必要があります。

• InterfaceResolver.getImplementationClass() は、インタフェースとして宣言されたフィールドの実際のデータ型を返します。このメソッドには以下のパラメータがあります。

  • interfaceClass — 解決されるインタフェース。

  • declaringClass — interfaceClass として宣言されたフィールドが含まれているクラス。

  • fieldName — インタフェースとして宣言された declaringClass のフィールドの名前が含まれている文字列。

次の例は、インタフェース、そのインタフェースの実装、およびそのインタフェースのインスタンスを解決する InterfaceResolver の実装を定義します。

スキーマのカスタマイズ ： InterfaceResolver の実装

この例では、解決されるインタフェースは、test.MyFirstInterface です。

package test;
public interface MyFirstInterface{ }

test.MyFirstImpl クラスは、InterfaceResolver によって返される必要がある test.MyFirstInterface の実装です。

package test;
public class MyFirstImpl implements MyFirstInterface {
  public MyFirstImpl() {};
  public MyFirstImpl(String s) { fieldOne = s; };
  public String  fieldOne;
}

InterfaceResolver の以下の実装は、インタフェースが test.MyFirstInterface である場合はクラス test.MyFirstImpl を返し、それ以外の場合は null を返します。

package test;
import com.intersystems.xep.*;
public class MyFirstInterfaceResolver implements InterfaceResolver {
  public MyFirstInterfaceResolver() {}
  public Class<?> getImplementationClass(Class declaringClass,
         String fieldName, Class<?> interfaceClass) {
    if (interfaceClass == xepdemo.MyFirstInterface.class) {
      return xepdemo.MyFirstImpl.class;
    }
    return null;
  }
}

MyFirstInterfaceResolver のインスタンスが setInterfaceResolver() によって指定されている場合、importSchema() の後続の呼び出しでは自動的にそのインスタンスが使用されて、test.MyFirstInterface として宣言されているすべてのフィールドが解決されます。そのようなフィールドごとに、そのフィールドを含むクラスにパラメータ declaringClass を設定し、fieldName をそのフィールドの名前に設定し、interfaceClass を test.MyFirstInterface に設定して、getImplementationClass() メソッドが呼び出されます。このメソッドは、インタフェースを解決し、test.MyFirstImpl か null のいずれかを返します。

スキーマ・マッピング・ルール

このセクションでは、XEP スキーマがどのように構築されるかについて説明します。以下の項目について説明します。

• インポートされるクラスの要件 — 永続イベントとして投影できるオブジェクトを作成するために Java クラスが満たす必要がある構造ルールについて説明します。

• 名前付け規約 — Java クラスおよびフィールドの名前を InterSystems IRIS の名前付け規則に従うように変換する方法について説明します。

• データ型のマッピング — 使用できる Java データ型をリストし、これらが対応する InterSystems IRIS のデータ型にどのようにマップされるかについて説明します。