第8章 ConfigurationBuilder API

8.1. ConfigurationBuilder API

ConfigurationBuilder API は Red Hat JBoss Data Grid のプログラミング可能な設定 API です。

ConfigurationBuilder API は、以下のことが行えるよう設計されています。

  • コーディングプロセスをより効率的にするための設定オプションのチェーンコーディング
  • 設定の可読性の向上

Red Hat JBoss Data Grid では、ConfigurationBuilder API は、CacheLoaders を有効にし、グローバルおよびキャッシュレベルの操作を設定するためにも使用されます。

注記

プログラムを使用した設定は、Red Hat JBoss Data Grid のライブラリーモードでのみ実行できます。

8.2. ConfigurationBuilder API の使用

8.2.1. CacheManager およびレプリケートされたキャッシュのプログラムによる作成

Red Hat JBoss Data Grid のプログラムによる設定は、ほぼ ConfigurationBuilder API および CacheManager のみが関係します。以下はプログラムによる CacheManager 設定の例になります。

CacheManager のプログラムを使用した設定

EmbeddedCacheManager manager = new DefaultCacheManager("my-config-file.xml");
Cache defaultCache = manager.getCache();
Configuration c = new ConfigurationBuilder().clustering().cacheMode(CacheMode.REPL_SYNC)
.build();

String newCacheName = "repl";
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

  1. XML ファイルで初めに CacheManager を作成します。必要な場合は、ユースケースの要件を満たす仕様に基づいて実行時にこの CacheManager をプログラミングできます。

  2. プログラムを使用して、同期的にレプリケートされたキャッシュを新規作成します。

    • ConfigurationBuilder ヘルパーオブジェクトを使用して新しい設定オブジェクトインスタンスを作成します。

      設定の最初の行で、ConfigurationBuilder を使用して新しいキャッシュ設定オブジェクト (c) が作成されます。設定 c には、キャッシュモードを除くすべてのキャッシュ設定オプションのデフォルト値が割り当てられ、この値は上書きされ、同期レプリケーション (REPL_SYNC) に設定されます。

    • マネージャーで設定を定義または登録します。

      設定の 3 行目で、キャッシュマネージャーは名前付きキャッシュ設定を定義するために使用されます。この名前付きキャッシュ設定は repl と呼ばれ、設定は最初の行のキャッシュ設定 c に提供された設定に基づきます。

    • 設定の 4 行目で、キャッシュマネージャーで保持された repl の一意のインスタンスに対する参照を取得するために、キャッシュマネージャーが使用されます。このキャッシュインスタンスはデータを格納および取得する操作を実行するために使用できます。

8.2.2. クラスター全体の動的キャッシュ作成

上記の例のように、getCache() メソッドを使用する場合、キャッシュは 1 つのノードでのみ作成されます。キャッシュをクラスターに参加する新しいノードで動的に作成する必要がある場合は、代わりに createCache() メソッドを使用します。 

Cache<String, String> cache = manager.administration().createCache("newCacheName", "newTemplate");

このように作成されたキャッシュはクラスターのすべてのノードで利用可能になりますが、それは一時的です。クラスター全体をシャットダウンし、再起動しても、キャッシュは自動的に再作成されません。キャッシュを永続化するには、PERMANENT フラグを以下のように使用します。 

Cache<String, String> cache = manager.administration().withFlags(AdminFlag.PERMANENT).createCache("newCacheName", "newTemplate");

上記は、グローバル状態を有効にし、適切な設定ストレージを選択しないと動作しません。選択可能な設定ストレージは以下のとおりです。

  • VOLATILE: 名前が意味するとおり、この設定ストレージは PERMANENT キャッシュをサポートしません。
  • OVERLAY: caches.xml という名前のファイルのグローバルな共有状態永続パスに設定を保存します。
  • MANAGED: サーバーデプロイメントでのみサポートされ、PERMANENT キャッシュをサーバーモデルに保存します。
  • CUSTOM: カスタムの設定ストア。

8.2.3. デフォルトの名前付きキャッシュを使用したカスタマイズされたキャッシュの作成

デフォルトキャッシュ設定 (またはカスタマイズされた設定) は新しいキャッシュを作成する土台として使用できます。

例として、infinispan-config-file.xml で、レプリケートされたキャッシュの設定がデフォルト値として指定され、カスタマイズされたライフスパン値を持つ分散キャッシュが必要であるとします。必要な分散キャッシュは infinispan-config-file.xml ファイルで指定されたデフォルトキャッシュのすべての内容 (言及された内容を除く) を保持する必要があります。

デフォルトキャッシュのカスタマイズ

String newCacheName = "newCache";
EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
Configuration dcc = manager.getDefaultCacheConfiguration();
Configuration c = new ConfigurationBuilder().read(dcc).clustering()
	.cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
	.build();
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

  1. デフォルトの Configuration オブジェクトのインスタンスを読み取り、デフォルトの設定を取得します。
  2. ConfigurationBuilder を使用して、新しい設定オブジェクトでキャッシュモードと L1 キャッシュライフスパンを構築および変更します。
  3. キャッシュマネージャーでキャッシュ設定を登録または定義します。
  4. 指定された設定が含まれる newCache への参照を取得します。

8.2.4. デフォルトでない名前付きキャッシュを使用したカスタマイズされたキャッシュの作成

デフォルトでない名前付きキャッシュを使用して新しいカスタマイズされたキャッシュを作成する必要があることがあります。この手順は、デフォルトの名前付きキャッシュを使用する場合の手順に似ています。

違いは、デフォルトのキャッシュの代わりに replicatedCache という名前のキャッシュを取得することです。

デフォルトでない名前付きキャッシュを使用したカスタマイズされたキャッシュの作成

String newCacheName = "newCache";
EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
Configuration rc = manager.getCacheConfiguration("replicatedCache");
Configuration c = new ConfigurationBuilder().read(rc).clustering()
	.cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
	.build();
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

  1. replicatedCache を読み取り、デフォルト設定を取得します。
  2. ConfigurationBuilder を使用して、新しい設定オブジェクトで必要な設定を構築および変更します。
  3. キャッシュマネージャーでキャッシュ設定を登録または定義します。
  4. 指定された設定が含まれる newCache への参照を取得します。

8.2.5. Configuration Builder を使用したプログラムによるキャッシュの作成

デフォルトキャッシュ値で xml ファイルを使用して新しいキャッシュを作成する代わりに、ConfigurationBuilder API を使用して XML ファイルなしで新しいキャッシュを作成します。ConfigurationBuilder API は設定オプションに対してチェーンされたコードを作成するときに使いやすさを提供することを目的としています。

以下の新しい設定は、グローバルおよびキャッシュレベル設定に対して有効です。GlobalConfiguration オブジェクトは、GlobalConfigurationBuilder を使用して構築され、Configuration オブジェクトは ConfigurationBuilder を使用して構築されます。

8.2.6. グローバル設定の例

8.2.6.1. トランスポート層のグローバル設定

通常使用される設定オプションは、トランスポート層を設定します。これにより、どのようにノードが他のノードを検出するかが Red Hat JBoss Data Grid に通知されます。

トランスポート層の設定

GlobalConfiguration globalConfig = new GlobalConfigurationBuilder()
  .transport().defaultTransport()
  .build();

8.2.6.2. キャッシュマネージャー名のグローバル設定

以下のサンプル設定では、グローバル JMX 統計レベルからオプションを使用してキャッシュマネージャーの名前を設定できます。この名前は、特定のキャッシュマネージャーと同じシステムの他のキャッシュマネージャーを区別します。

キャッシュマネージャー名の設定

GlobalConfiguration globalConfig = new GlobalConfigurationBuilder()
  .globalJmxStatistics()
    .cacheManagerName("SalesCacheManager")
    .mBeanServerLookup(new JBossMBeanServerLookup())
    .enable()
  .build();

8.2.6.3. JGroups のグローバル設定

Red Hat JBoss Data Grid がクラスターモードで動作するには、適切な JGroups 設定が必要になります。以下の設定例は、事前定義された JGroups 設定ファイルを設定に渡す方法を示しています。

JGroups のプログラムを使用した設定

GlobalConfiguration gc = new GlobalConfigurationBuilder()
    .transport()
        .defaultTransport()
    .addProperty("configurationFile","jgroups.xml")
    .build();

Red Hat JBoss Data Grid は最初にクラスパスにある jgroups.xml を検索します。クラスパスでインスタンスが見つからない場合は、絶対パス名を検索します。

8.2.7. キャッシュレベル設定の例

8.2.7.1. クラスターモードのキャッシュレベル設定

以下の設定により、グローバルでないキャッシュレベルでのキャッシュのクラスターモードなどのオプションを使用できます。

キャッシュレベルでのクラスターモードの設定

Configuration config = new ConfigurationBuilder()
  .clustering()
    .cacheMode(CacheMode.DIST_SYNC)
    .sync()
    .l1().lifespan(25000L).enable()
    .hash().numOwners(3)
  .build();

8.2.7.2. キャッシュレベルのエビクションおよびエクスパレーションの設定

以下の設定を使用して、キャッシュレベルでキャッシュのエクスパレーションまたはエビクションオプションを設定します。

エクスパレーションおよびエビクションのキャッシュレベルでの設定

Configuration config = new ConfigurationBuilder()
           .memory()
             .size(20000)
           .expiration()
             .wakeUpInterval(5000L)
             .maxIdle(120000L)
           .build();

8.2.7.3. JTA トランザクションのキャッシュレベルの設定

JTA トランザクション設定のキャッシュと対話するには、トランザクション層を設定し、任意でロック設定をカスタマイズします。トランザクションキャッシュでは、トランザクションリカバリーを有効にして未完了のトランザクションに対応することが推奨されます。さらに、JMX 管理および統計収集も有効にすることが推奨されます。

JTA トランザクションのキャッシュレベルでの設定

Configuration config = new ConfigurationBuilder()
  .locking()
    .concurrencyLevel(10000).isolationLevel(IsolationLevel.REPEATABLE_READ)
    .lockAcquisitionTimeout(12000L).useLockStriping(false).writeSkewCheck(true)
  .transaction()
    .transactionManagerLookup(new GenericTransactionManagerLookup())
  .recovery().enable()
  .jmxStatistics().enable()
  .build();

8.2.7.4. チェーンされた永続ストアを使用したキャッシュレベルでの設定

以下の設定は、キャッシュレベルで 1 つまたは複数のチェーンされた永続ストアを設定するために使用できます。

チェーンされた永続ストアのキャッシュレベルでの設定

Configuration conf = new ConfigurationBuilder()
          .persistence()
            .passivation(false)
            .addSingleFileStore()
               .location("/tmp/firstDir")
          .persistence()
            .passivation(false)
            .addSingleFileStore()
               .location("/tmp/secondDir")
          .build();

8.2.7.5. 高度なエクスターナライザーのキャッシュレベルでの設定

高度なエクスターナライザーに対するキャッシュレベル設定などの高度なオプションは、以下のようにプログラムを使用して設定することもできます。

高度なエクスターナライザーのキャッシュレベルでの設定

GlobalConfiguration globalConfig = new GlobalConfigurationBuilder()
  .serialization()
    .addAdvancedExternalizer(new PersonExternalizer())
    .addAdvancedExternalizer(999, new AddressExternalizer())
  .build();

8.2.7.6. パーティション処理のキャッシュレベルでの設定 (ライブラリーノード)

スプリットブレインが発生した場合、パーティション処理ストラテジーを選択して、データの一貫性または可用性を提供できます。可用性を選択し、データの一貫性が失われる場合、マージポリシーを選択して、ノードが再参加時にデータをマージする方法を定義することもできます。設定例を以下に示します。 

ConfigurationBuilder dcc = new ConfigurationBuilder();
dcc.clustering().partitionHandling()
                    .whenSplit(PartitionHandling.DENY_READ_WRITES)
                    .mergePolicy(MergePolicies.REMOVE_ALL);

パーティション処理に関する詳細は、『Administration and Configuration Guide』を参照してください。

注記

クライアントサーバーモードでパーティション処理を設定するには、『Administration and Configuration Guide』の説明にしたがって宣言的に有効にする必要があります。