索引によるデータへのアクセス (索引 API)

より効率的なデータ・アクセスのために索引付けを使用します。

このタスクについて

HashIndex クラスは、組み込みアプリケーション索引インターフェースである MapIndexMapRangeIndex の両方をサポートすることのできる組み込み索引プラグイン実装です。 ユーザー独自の索引を作成することもできます。HashIndex を静的索引または動的索引としてバックアップ・マップに追加し、MapIndex または MapRangeIndex の索引プロキシー・オブジェクトを取得し、その索引プロキシー・オブジェクトを使用してキャッシュ・オブジェクトを検索することができます。

ローカル・マップ内のキーを反復処理する場合は、デフォルトの索引を 使用できます。この索引はまったく構成を必要としませんが、エージェントを使用するか ShardEvents.shardActivated(ObjectGrid shard) メソッドから 取得した ObjectGrid インスタンスを使用して、断片に対して使用しなければなりません。

注: 分散環境では、索引オブジェクトがクライアント ObjectGrid から 取得された場合、その索引のタイプはクライアント索引オブジェクトになり、すべての索引操作は リモート・サーバー ObjectGrid で実行されます。マップが区画化されている場合、索引操作は 各区画でリモートに実行されます。 各区画の結果はマージされてからアプリケーションに返されます。パフォーマンスは、区画数と、各区画が戻す結果のサイズによって決まり ます。これらの要因が両方とも大きいと、パフォーマンスが低下することがあります。

手順

  1. デフォルトのローカル索引以外の索引を使用する場合、索引プラグインをバックアップ・マップに追加します。
    • XML 構成:
      <backingMapPluginCollection id="person">
           <bean id="MapIndexplugin" 
      			className="com.ibm.websphere.objectgrid.plugins.index.HashIndex">
               <property name="Name" type="java.lang.String" value="CODE" 
      						description="index name" />
               <property name="RangeIndex" type="boolean" value="true" 
      						description="true for MapRangeIndex" />
               <property name="AttributeName" type="java.lang.String" value="employeeCode" 
      						description="attribute name" />
           </bean>
      </backingMapPluginCollection>

      この XML 構成例では、 組み込み HashIndex クラスが索引プラグインとして使用されています。HashIndex クラスは、 ユーザーが構成できるプロパティーをサポートしています。上の例にある Name、RangeIndex、 AttributeName などです。

      • Name プロパティーは、この索引プラグインを識別するストリングである CODE と構成されています。Name プロパティー値は、BackingMap の有効範囲内で固有で なければならず、BackingMap の ObjectMap インスタンスから名前で索引オブジェクトを取り出す のに使用できます。
      • RangeIndex プロパティーは true と構成されています。これが意味するのは、取り出された索引オブジェクトをアプリケーションが MapRangeIndex インターフェースにキャストできるということです。RangeIndex プロパティーが false と構成されている場合は、アプリケーションは取り出された索引オブジェクトを MapIndex インターフェースにしかキャストできません。MapRangeIndex は、 範囲関数 greater than や less than、あるいは両方を使用するデータ検出をサポートしますが、MapIndex は equals 関数 のみをサポートします。索引が照会によって使用される場合、RangeIndex プロパティーは、単一属性索引に対して true と構成されていなければなりません。リレーションシップ索引および複合索引に対しては、RangeIndex プロパティーは false と構成される必要があります。
      • AttributeName プロパティーは employeeCode と構成されています。これは、キャッシュに入れられたオブジェクトの employeeCode 属性を使用して、単一属性索引が構築されることを意味しています。複数の属性を持つ、キャッシュに入れられたオブジェクトをアプリケーションが 検索する必要がある場合、AttributeName プロパティーには、属性をコンマで区切ったリストを設定 でき、そうすると複合索引が生成されます。
    • プログラマチック構成:

      BackingMap インターフェースには、静的索引プラグインを追加するために使用できるメソッドとして、addMapIndexpluginsetMapIndexplugins の 2 つがあります。詳しくは、BackingMap APIを参照してください。次の例は、XML 構成の例と同じ構成を作成します。

      import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
      import com.ibm.websphere.objectgrid.ObjectGridManager;
      import com.ibm.websphere.objectgrid.ObjectGrid;
      import com.ibm.websphere.objectgrid.BackingMap;
      
          ObjectGridManager ogManager = ObjectGridManagerFactory.getObjectGridManager();
          ObjectGrid ivObjectGrid = ogManager.createObjectGrid( "grid" );
          BackingMap personBackingMap = ivObjectGrid.getMap("person");
      
          // use the builtin HashIndex class as the index plugin class.
          HashIndex mapIndexplugin = new HashIndex();
          mapIndexplugin.setName("CODE");
          mapIndexplugin.setAttributeName("EmployeeCode");
          mapIndexplugin.setRangeIndex(true);
          personBackingMap.addMapIndexplugin(mapIndexplugin);
  2. 索引を使用してマップのキーと値にアクセスします。
    • ローカル索引:
      ローカル・マップ内のキーと値を反復処理する場合は、デフォルトの索引を 使用できます。デフォルトの索引は、エージェントを使用するか、ShardEvents.shardActivated(ObjectGrid shard) メソッドから 取得した ObjectGrid インスタンスを使用するかして、断片に対してのみ機能します。 次の例を参照してください。
      MapIndex keyIndex = (MapIndex)
      objMap.getIndex(MapIndexPlugin.SYSTEM_KEY_INDEX_NAME);
      Iterator keyIterator = keyIndex.findAll();
    • 静的索引:

      静的索引プラグイン が BackingMap 構成に追加され、含んでいる ObjectGrid インスタンスが初期化された後であれば、 アプリケーションは BackingMap の ObjectMap インスタンスから名前によって索引オブジェクトを取得できます。 索引オブジェクトは、アプリケーション索引インターフェースにキャストします。これで、アプリケーション索引インターフェース がサポートしている操作を実行できるようになります。

      Session session = ivObjectGrid.getSession();
      ObjectMap map = session.getMap("person ");
      MapRangeIndex codeIndex = (MapRangeIndex) m.getIndex("CODE");
      Iterator iter = codeIndex.findLessEqual(new Integer(15));
      while (iter.hasNext()) {
      		Object key = iter.next();
      		Object value = map.get(key);
      }
      // Close the session (optional in Version 7.1.1 and later) for improved performance
      session.close();
    • 動的索引:

      BackingMap インスタンスから動的索引を、いつでもプログラマチックに作成および除去することができます。 動的索引と静的索引の違いは、動的索引は、索引を含む ObjectGrid インスタンスが初期化されたあとでも作成できる、という点です。動的索引付けは、静的索引付けとは違って 非同期プロセスであり、使用される前に作動可能状態に なっている必要があります。このメソッドは、動的索引の取得および使用に、静的索引と同じアプローチを使用します。 動的索引は、不要になると除去できます。BackingMap インターフェースには、動的索引を作成および除去するためのメソッドがあります。

      createDynamicIndex メソッドおよび removeDynamicIndex メソッドの詳細については、BackingMap API を参照してください。

      import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
      import com.ibm.websphere.objectgrid.ObjectGridManager;
      import com.ibm.websphere.objectgrid.ObjectGrid;
      import com.ibm.websphere.objectgrid.BackingMap;
      
              ObjectGridManager ogManager = ObjectGridManagerFactory.getObjectGridManager();
              ObjectGrid og = ogManager.createObjectGrid("grid");
              BackingMap bm = og.getMap("person");
              og.initialize();
      
              // create index after ObjectGrid initialization without DynamicIndexCallback.
              bm.createDynamicIndex("CODE", true, "employeeCode", null);
      
              try {
                  // If not using DynamicIndexCallback, need to wait for the Index to be ready.
                  // The waiting time depends on the current size of the map
                  Thread.sleep(3000);
              } catch (Throwable t) {
                  // ...
              }
      
              // When the index is ready, applications can try to get application index
              // interface instance.
              // Applications have to find a way to ensure that the index is ready to use,
              // if not using DynamicIndexCallback interface.
              // The following example demonstrates the way to wait for the index to be ready
              // Consider the size of the map in the total waiting time.
      
              Session session = og.getSession();
              ObjectMap m = session.getMap("person");
              MapRangeIndex codeIndex = null;
      
              int counter = 0;
              int maxCounter = 10;
              boolean ready = false;
              while (!ready && counter < maxCounter) {
                  try {
                      counter++;
                      codeIndex = (MapRangeIndex) m.getIndex("CODE");
                      ready = true;
                  } catch (IndexNotReadyException e) {
                      // implies index is not ready, ...
                      System.out.println("Index is not ready. continue to wait.");
                      try {
                          Thread.sleep(3000);
                      } catch (Throwable tt) {
                          // ...
                      }
                  } catch (Throwable t) {
                      // unexpected exception
                      t.printStackTrace();
                  }
              }
      
              if (!ready) {
                  System.out.println("Index is not ready.  Need to handle this situation.");
              }
      
              // Use the index to peform queries
              // Refer to the MapIndex or MapRangeIndex interface for supported operations.
              // The object attribute on which the index is created is the EmployeeCode.
              // Assume that the EmployeeCode attribute is Integer type: the
              // parameter that is passed into index operations has this data type.
      
              Iterator iter = codeIndex.findLessEqual(new Integer(15));
      
              // remove the dynamic index when no longer needed
      
              bm.removeDynamicIndex("CODE");
      	// Close the session (optional in Version 7.1.1 and later) for improved performance
      	session.close();

次のタスク

DynamicIndexCallback インターフェースを使用して、索引付けイベントの 発生時に通知を受けることができます。詳しくは、DynamicIndexCallback インターフェースを参照してください。