Embed Size (px)
Citation preview
FUJITSU Software Interstage Terracotta BigMemory Max
ユーザーズガイド
B1WS-1116-01Z0 (00) 2013年6月
まえがき
本書の目的
本製品の導入にあたり、主にシステム設計(製品を導入してどのような情報システムを構築するのか、運用形態を設計す
るための方法)、セットアップ(システム構築のための環境作成方法)について説明します。
また、構築したシステムを運用・管理する方法、そのために使用する機能、使い方を説明します。
本書の構成
本書は以下の構成になっています。
第1部 BigMemory Max
Interstage Terracotta BigMemory Maxについて説明します。
第2部 Terracotta管理コンソール
Terracotta管理コンソールについて説明します。
付録
Terracotta管理コンソールのヘルプや、ライセンスファイル、フレームワーク連携について説明します。
輸出管理規制について
本ドキュメントを輸出または提供する場合は、外国為替、外国貿易法、米国輸出管理関連法規などの規制をご確認のう
え、必要な手続をおとりください。
登録商標について
● Software AG、Terracotta の社名およびすべてのSoftware AG/Terracotta 製品名は、Software AG の商標または登
録商標です。
● Red Hat、RPMおよびRed Hatをベースとしたすべての商標とロゴは、Red Hat, Inc.の米国およびその他の国におけ
る商標または登録商標です。
● Linuxは、Linus Torvalds氏の米国およびその他の国における商標または登録商標です。
● OracleとJavaは、Oracle Corporation およびその子会社、関連会社の米国およびその他の国における登録商標です。
文中の社名、商品名等は各社の商標または登録商標である場合があります。
● VMwareはVMware,Incの米国およびその他の国における登録商標または商標です。
● Microsoft、Windows、またはその他のマイクロソフト製品の名称および製品名は、米国Microsoft Corporationの米
国およびその他の国における登録商標または商標です。
● その他の記載されている商標および登録商標については、一般に各社の商標または登録商標です。
出版年月および版数
2013年 6月 初版
著作権
Copyright in Terracotta 2013 and trademarks at all times remain the property of Software AG.
1
目次
第 1 部 BigMemory Max .......................................................................................................................................................... 17
1 BigMemory Maxにようこそ ........................................................................................................................................ 17
2 BigMemory Maxクイックスタートガイド ........................................................................................................... 18
2.1 BigMemory Maxのインストール ..................................................................................................................... 18
2.2 Terracottaサーバと管理コンソールの起動 ............................................................................................... 20
2.3 その他の構成情報 .................................................................................................................................................. 22
2.4 システム規模の変更 ............................................................................................................................................. 24
3 Hello, World! ....................................................................................................................................................................... 24
3.1 構成情報ファイルの作成 .................................................................................................................................... 25
3.2 HelloWorld.javaの作成 ......................................................................................................................................... 25
3.3 実行 ............................................................................................................................................................................... 26
3.4 次のステップ ............................................................................................................................................................ 26
4 基本CRUD ............................................................................................................................................................................ 26
4.1 構成情報ファイルの作成 .................................................................................................................................... 26
4.2 Crud.javaの作成 ....................................................................................................................................................... 26
4.3 実行 ............................................................................................................................................................................... 28
4.4 次のステップ ............................................................................................................................................................ 28
5 検索 ........................................................................................................................................................................................ 28
5.1 構成情報ファイルの作成 .................................................................................................................................... 29
5.2 Search.javaの作成 ................................................................................................................................................... 29
5.3 実行 ............................................................................................................................................................................... 32
5.4 次のステップ ............................................................................................................................................................ 32
6 結果のソート ..................................................................................................................................................................... 32
2
6.1 構成情報ファイルの作成 .................................................................................................................................... 32
6.2 Sort.javaの作成 ........................................................................................................................................................ 33
6.3 実行 ............................................................................................................................................................................... 35
6.4 次のステップ ............................................................................................................................................................ 35
7 結果のグループ化 ........................................................................................................................................................... 36
7.1 構成情報ファイルの作成 .................................................................................................................................... 36
7.2 Group.javaの作成 .................................................................................................................................................... 37
7.3 実行 ............................................................................................................................................................................... 40
7.4 次のステップ ............................................................................................................................................................ 40
8 Terracottaサーバアレイの追加................................................................................................................................. 40
8.1 事前準備 ..................................................................................................................................................................... 41
8.2 構成情報ファイルの作成 .................................................................................................................................... 41
8.3 ServerArrayTest.javaの作成 .............................................................................................................................. 42
8.4 Terracottaサーバインスタンスの起動 ......................................................................................................... 46
8.5 実行 ............................................................................................................................................................................... 46
8.6 次のステップ ............................................................................................................................................................ 47
9 サンプルコード集 ........................................................................................................................................................... 47
9.1 はじめに ..................................................................................................................................................................... 47
9.2 例 1：XMLによる構成設定 ................................................................................................................................ 48
9.3 例 2：プログラムによる構成設定 ................................................................................................................. 49
9.4 例 3：基本CRUD（Create, Read, Update, Delete） .................................................................................. 50
9.5 例 4：検索 ................................................................................................................................................................ . 52
9.6 例 5：ノンストップ／リジョイン ................................................................................................................. 54
9.7 例 6：Automatic Resource Controlの概要 ................................................................................................... 56
9.8 例 7：キャッシュとしてBigMemoryを利用 .............................................................................................. 57
3
10 構成の概要 ..................................................................................................................................................................... 58
10.1 はじめに ................................................................................................................................................................ . 58
10.2 XML構成 ................................................................................................................................................................ . 59
10.3 キャッシュ構成を動的に変更する ............................................................................................................ 60
10.4 参照渡しと値渡し ............................................................................................................................................. 63
10.5 特殊なシステムプロパティ .......................................................................................................................... 64
10.6 構成設定の詳細情報 ......................................................................................................................................... 64
11 ストレージ層 ................................................................................................................................................................ 65
11.1 はじめに ................................................................................................................................................................ . 65
11.2 メモリストア ....................................................................................................................................................... 65
11.3 メモリストアの構成設定 ............................................................................................................................... 66
11.4 オフヒープストア ............................................................................................................................................. 67
11.5 オフヒープストアの構成設定 ..................................................................................................................... 69
11.6 ディスクストア .................................................................................................................................................. 70
11.7 ディスクストアの構成設定 .......................................................................................................................... 71
11.8 構成情報のサンプル ......................................................................................................................................... 73
12 ストレージ層のサイズ指定 ................................................................................................................................... 75
12.1 はじめに ................................................................................................................................................................ . 75
12.2 属性によるサイズ指定 .................................................................................................................................... 75
12.3 各データセットのサイズ指定とプール利用との比較 ..................................................................... 77
12.4 サイズ指定のサンプル .................................................................................................................................... 79
12.5 分散キャッシュのサイズ指定 ..................................................................................................................... 83
12.6 サイズ制限のオーバーライド ..................................................................................................................... 85
12.7 サイズ制限と、ビルトインのサイズ計算 ............................................................................................. 85
13 ピンニング、有効期限、エビクション ........................................................................................................... 88
4
13.1 はじめに ................................................................................................................................................................ . 88
13.2 有効期限の設定 .................................................................................................................................................. 90
13.3 データのピンニング ......................................................................................................................................... 91
13.4 データの明示的な削除 .................................................................................................................................... 93
13.5 構成設定によるElementのフラッシュとエビクションの仕組み ............................................... 93
13.6 データの鮮度と有効期限 ............................................................................................................................... 94
14 高速再起動 ..................................................................................................................................................................... 95
14.1 はじめに ................................................................................................................................................................ . 95
14.2 データの永続性の実装 .................................................................................................................................... 95
14.3 構成情報のサンプル ......................................................................................................................................... 97
14.4 高速再起動のパフォーマンス ..................................................................................................................... 99
14.5 高速再起動の制限 ............................................................................................................................................. 99
15 BigMemory Max分散構成設定ガイド ................................................................................................................ 99
15.1 はじめに ................................................................................................................................................................ . 99
15.2 CacheManagerの構成設定 ........................................................................................................................... 100
15.3 Terracottaクラスタ構成の要素 ................................................................................................................ 101
15.4 キャッシュサイズの制御 ............................................................................................................................ 105
15.5 キャッシュエビクションの設定.............................................................................................................. 105
15.6 キャッシュ構成情報ファイル内のプロパティ ................................................................................. 106
15.7 キャッシュイベントの構成情報.............................................................................................................. 106
15.8 読み取り時のコピー処理 ............................................................................................................................ 107
15.9 インメモリのデータセットに対する堅牢性の設定 ....................................................................... 108
15.10 両立しない構成情報 ...................................................................................................................................... 108
15.11 Terracotta管理コンソールからの構成情報の抽出 ......................................................................... 109
16 ノンストップオペレーション ............................................................................................................................ 109
5
16.1 はじめに .............................................................................................................................................................. 109
16.2 ノンストップオペレーションの構成設定 .......................................................................................... 110
16.3 ノンストップのタイムアウトと動作 .................................................................................................... 110
16.4 ノンストップ機能で発生する例外 ......................................................................................................... 112
17 Terracotta分散キャッシュ（BigMemory）のデフォルト設定 .......................................................... 114
17.1 はじめに .............................................................................................................................................................. 114
17.2 Terracottaサーバアレイ .............................................................................................................................. 114
17.3 Terracottaクライアント .............................................................................................................................. 116
18 BigMemory Max構成情報のリファレンス.................................................................................................... 118
18.1 ノンストップキャッシュ ............................................................................................................................ 118
18.2 エビクションに関する構成情報の設定 ............................................................................................... 121
18.3 パフォーマンスとキャッシュ整合性 .................................................................................................... 122
18.4 Terracottaクラスタのキャッシュイベント ........................................................................................ 124
18.5 高可用性を優先するキャッシュ構成 .................................................................................................... 125
18.6 トランザクション型キャッシュの利用方法 ..................................................................................... 127
18.7 OSGiとの連携 .................................................................................................................................................... 133
19 BigMemory APIの主なクラスとメソッド ..................................................................................................... 134
19.1 はじめに .............................................................................................................................................................. 134
19.2 CacheManager ................................................................................................................................................... 135
19.3 Cache ..................................................................................................................................................................... 136
19.4 Element ................................................................................................................................................................ 137
20 BigMemory Maxの検索API ................................................................................................................................... 137
20.1 はじめに .............................................................................................................................................................. 137
20.2 Cacheを検索可能にする方法 ..................................................................................................................... 137
20.3 属性の定義 ......................................................................................................................................................... 139
6
20.4 クエリの作成 .................................................................................................................................................... 142
20.5 クエリの結果の取得と管理 ....................................................................................................................... 143
20.6 サンプルアプリケーション ....................................................................................................................... 146
20.7 スクリプト環境 ............................................................................................................................................... 146
20.8 実装とパフォーマンス ................................................................................................................................. 147
20.9 検索を最適化する方法 ................................................................................................................................. 148
21 一括ロード .................................................................................................................................................................. 150
21.1 はじめに .............................................................................................................................................................. 150
21.2 API .......................................................................................................................................................................... 151
21.3 一括ロードAPIを利用したサンプル ...................................................................................................... 152
21.4 処理速度の向上 ............................................................................................................................................... 153
21.5 FAQ ........................................................................................................................................................................ 153
21.6 パフォーマンス向上のヒント .................................................................................................................. 154
22 事前リフレッシュ .................................................................................................................................................... 154
22.1 はじめに .............................................................................................................................................................. 154
22.2 インラインの事前リフレッシュ.............................................................................................................. 155
22.3 事前リフレッシュのスケジュール設定 ............................................................................................... 156
22.4 CacheLoaderの実装 ........................................................................................................................................ 158
23 Ehcacheのトランザクション .............................................................................................................................. 159
23.1 はじめに .............................................................................................................................................................. 159
23.2 トランザクションモードの選択.............................................................................................................. 159
23.3 必要事項 .............................................................................................................................................................. 160
23.4 構成 ....................................................................................................................................................................... 160
23.5 グローバルトランザクション .................................................................................................................. 161
23.6 障害回復 .............................................................................................................................................................. 162
7
23.7 サンプルアプリケーション ....................................................................................................................... 162
23.8 トランザクションマネージャー.............................................................................................................. 164
23.9 ローカルトランザクション ....................................................................................................................... 165
23.10 パフォーマンス ............................................................................................................................................... 167
23.11 FAQ ........................................................................................................................................................................ 168
24 明示的ロック ............................................................................................................................................................. 169
24.1 はじめに .............................................................................................................................................................. 169
24.2 API .......................................................................................................................................................................... 170
24.3 サンプル .............................................................................................................................................................. 172
24.4 動作の仕組み .................................................................................................................................................... 172
25 CacheWriterを用いたライトスルーとライトビハインド ..................................................................... 172
25.1 はじめに .............................................................................................................................................................. 172
25.2 ライトビハインドの長所 ............................................................................................................................ 173
25.3 ライトビハインドの制限と制約.............................................................................................................. 173
25.4 リードスルー方式とライトビハインド方式のキャッシュの組み合わせ............................ 175
25.5 紹介ビデオ ......................................................................................................................................................... 176
25.6 サンプルアプリケーション ....................................................................................................................... 176
25.7 構成情報 .............................................................................................................................................................. 176
25.8 API .......................................................................................................................................................................... 179
25.9 SPI .......................................................................................................................................................................... 180
25.10 FAQ ........................................................................................................................................................................ 183
26 BlockingキャッシュとSelf-Populatingキャッシュ .................................................................................... 184
26.1 はじめに .............................................................................................................................................................. 184
26.2 Blockingキャッシュ ....................................................................................................................................... 184
26.3 SelfPopulatingキャッシュ ........................................................................................................................... 185
8
27 Terracottaクラスタイベント .............................................................................................................................. 185
27.1 はじめに .............................................................................................................................................................. 185
27.2 クラスタトポロジ .......................................................................................................................................... 185
27.3 クラスタイベントの待ち受け .................................................................................................................. 186
28 Cache Decorator ........................................................................................................................................................ 189
28.1 はじめに .............................................................................................................................................................. 189
28.2 Decoratorの作成 .............................................................................................................................................. 189
28.3 Decoratorによる拡張キャッシュのCacheManagerへの追加 ...................................................... 190
28.4 ビルトインのDecorator ............................................................................................................................... 192
29 イベントリスナー .................................................................................................................................................... 193
29.1 CacheManagerのイベントリスナー ....................................................................................................... 193
29.2 Cacheのイベントリスナー ......................................................................................................................... 195
30 Cache Exceptionハンドラー ................................................................................................................................ 202
30.1 はじめに .............................................................................................................................................................. 202
30.2 構成情報を利用する定義 ............................................................................................................................ 202
30.3 Cache ExceptionハンドラーFactoryとCache Exception Handlerの実装方法 ....................... 202
30.4 プログラムによる構成設定 ....................................................................................................................... 204
31 キャッシュ拡張 ........................................................................................................................................................ 204
31.1 はじめに .............................................................................................................................................................. 204
31.2 構成情報を利用する定義 ............................................................................................................................ 205
31.3 Cache ExtensionファクトリとCache Extensionの実装 .................................................................. 205
31.4 プログラムによる構成設定 ....................................................................................................................... 207
32 キャッシュエビクションアルゴリズム ........................................................................................................ 207
32.1 はじめに .............................................................................................................................................................. 207
32.2 メモリストア用に提供されているエビクションアルゴリズム ............................................... 208
9
32.3 独自のエビクションアルゴリズムをプラグインとして使用 .................................................... 209
32.4 ディスクストアのエビクションアルゴリズム ................................................................................. 210
33 クラスロードとクラスローダ ............................................................................................................................ 211
33.1 はじめに .............................................................................................................................................................. 211
33.2 クラスロードのプラグイン ....................................................................................................................... 211
33.3 ehcache.xmlリソースのロード ................................................................................................................. 212
34 Developing Applications With the Terracotta Toolkit .............................................................................. 213
34.1 Introduction ....................................................................................................................................................... 213
34.2 Installing the Terracotta Toolkit ............................................................................................................... 213
34.3 Understanding Versions ............................................................................................................................... 214
35 Working With the Terracotta Toolkit ............................................................................................................... 214
35.1 Introduction ....................................................................................................................................................... 214
35.2 Initializing the Toolkit ................................................................................................................................... 214
35.3 Toolkit Data Structures ................................................................................................................................. 215
35.4 Cluster Information and Messaging ......................................................................................................... 221
35.5 Locks ..................................................................................................................................................................... 224
35.6 Barriers ................................................................................................................................................................ 225
35.7 Utilities ................................................................................................................................................................ . 225
35.8 Shared Characteristics ................................................................................................................................... 225
36 Terracotta Toolkit Reference ............................................................................................................................... 227
36.1 Reconnected Client Rejoin ........................................................................................................................... 227
36.2 Connection Issues ............................................................................................................................................ 228
36.3 Multiple Terracotta Clients in a Single JVM .......................................................................................... 228
37 Javadoc .......................................................................................................................................................................... 229
38 Terracottaツールカタログ ................................................................................................................................... 229
10
38.1 はじめに .............................................................................................................................................................. 229
38.2 アーカイブ・ユーティリティ (archive-tool) ..................................................................................... 230
38.3 データベースバックアップユーティリティ (backup-data) ....................................................... 230
38.4 バックアップステータス (backup-status) .......................................................................................... 231
38.5 クラスタのスレッドや状態のダンプ (debug-tool) ......................................................................... 232
38.6 分散ガベージコレクタ（run-dgc） ....................................................................................................... 233
38.7 サーバ起動スクリプトとサーバ停止スクリプト（start-tc-server, stop-tc-server） ..... 234
38.8 サーバのステータス (server-stat) .......................................................................................................... 235
38.9 バージョン･ユーティリティ (version)................................................................................................. 236
38.10 Terracotta用Mavenプラグイン ................................................................................................................ 237
39 JMX管理と監視 .......................................................................................................................................................... 237
39.1 はじめに .............................................................................................................................................................. 237
39.2 JMXの概要 .......................................................................................................................................................... 237
39.3 MBeans ................................................................................................................................................................ . 238
39.4 JMXによるリモート処理 ............................................................................................................................. 239
39.5 ObjectNameの名称の構造 ........................................................................................................................... 239
39.6 管理サービス .................................................................................................................................................... 240
39.7 JConsoleのサンプル ....................................................................................................................................... 241
39.8 Hibernateの統計 .............................................................................................................................................. 242
39.9 パフォーマンス ............................................................................................................................................... 242
40 ログ ................................................................................................................................................................................. 243
40.1 はじめに .............................................................................................................................................................. 243
40.2 SLF4Jのログ機能 ............................................................................................................................................. 243
40.3 ログのレベルの推奨値 ................................................................................................................................. 244
41 BigMemoryのシャットダウン ............................................................................................................................ 244
11
41.1 はじめに .............................................................................................................................................................. 244
41.2 データの明示的な削除 ................................................................................................................................. 244
41.3 ServletContextListener .................................................................................................................................. 245
41.4 シャットダウンフック ................................................................................................................................. 245
41.5 異常なシャットダウン ................................................................................................................................. 246
42 BigMemory Max Best Practices ........................................................................................................................... 246
42.1 Tuning Off-Heap Store Performance ....................................................................................................... 246
42.2 Tuning Heap Memory Performance ......................................................................................................... 249
42.3 Common Causes of Failures in a Cluster ................................................................................................ 250
42.4 Manage Sessions in a Cluster ...................................................................................................................... 251
42.5 A Safe Failover Procedure ............................................................................................................................ 253
42.6 A Safe Cluster Shutdown Procedure ........................................................................................................ 253
43 BigMemory Max FAQ ............................................................................................................................................... 254
43.1 Getting Started .................................................................................................................................................. 254
43.2 Configuration, Development, and Operations ..................................................................................... 255
43.3 Environment and Interoperability ........................................................................................................... 258
43.4 Troubleshooting ............................................................................................................................................... 259
43.5 Specific Errors and Warnings ..................................................................................................................... 261
44 Terracottaサーバアレイ ....................................................................................................................................... 263
44.1 はじめに .............................................................................................................................................................. 264
44.2 機能と用語の解説 .......................................................................................................................................... 265
44.3 詳細情報のリンク .......................................................................................................................................... 268
45 Terracottaサーバアレイのアーキテクチャー ............................................................................................ 268
45.1 開発用のTerracottaクラスタ ..................................................................................................................... 268
45.2 信頼性を高めるためのTerracottaクラスタ ........................................................................................ 269
12
45.3 可用性の高いTerracottaサーバアレイ ................................................................................................. 272
45.4 拡張性を備えたTerracottaサーバアレイ ............................................................................................ 277
46 Terracotta構成情報ファイルの編集 ............................................................................................................... 280
46.1 はじめに .............................................................................................................................................................. 280
46.2 構成情報設定のヒント ................................................................................................................................. 280
46.3 Terracottaサーバの構成情報ファイルの指定方法 ......................................................................... 281
46.4 Terracottaクライアントの構成情報ファイルの指定方法 ........................................................... 282
46.5 開発環境の構成設定 ...................................................................................................................................... 283
46.6 本番業務環境の構成設定 ............................................................................................................................ 287
46.7 インターフェースに対するポートのバインド ................................................................................. 288
46.8 利用中の構成情報の確認 ............................................................................................................................ 289
47 Terracottaクラスタの可用性を高めるための構成設定 ......................................................................... 289
47.1 はじめに .............................................................................................................................................................. 289
47.2 可用性を高めるための基本的な構成設定 .......................................................................................... 290
47.3 高可用性に関する機能 ................................................................................................................................. 291
47.4 効果的なクライアントとサーバの再接続設定：サンプル ........................................................ 301
47.5 配備済み環境の可用性のテスト.............................................................................................................. 302
48 クラスタのセキュリティ ..................................................................................................................................... 312
48.1 はじめに .............................................................................................................................................................. 312
48.2 SSLを使ったセキュリティの構成設定 ................................................................................................. 312
48.3 LDAP (JAAS経由）を使ったセキュリティの構成設定 .................................................................. 312
48.4 JMX認証を使ったセキュリティの構成設定 ....................................................................................... 313
48.5 認証を必要とするサーバに対するスクリプト使用 ....................................................................... 315
48.6 サーバのセキュリティを拡張する ......................................................................................................... 315
49 Terracottaクラスタのセキュリティ設定 ...................................................................................................... 316
13
49.1 はじめに .............................................................................................................................................................. 316
49.2 概要 ....................................................................................................................................................................... 316
49.3 サーバのセキュリティのセットアップ ............................................................................................... 320
49.4 TerracottaクライアントでSSLを有効化する ..................................................................................... 326
49.5 Terracotta管理サーバのセキュリティ ................................................................................................. 329
49.6 セキュリティで保護されたサーバの運用 .......................................................................................... 331
50 LDAPを使った認証のセットアップ ................................................................................................................ 335
50.1 はじめに .............................................................................................................................................................. 335
50.2 Configuration Overview ................................................................................................................................ 335
50.3 Active Directoryの構成設定 ....................................................................................................................... 336
50.4 標準LDAPの構成設定 .................................................................................................................................... 337
50.5 CDATAコンストラクタを使う .................................................................................................................. 339
51 Terracottaサーバアレイの運用 ......................................................................................................................... 340
51.1 自動リソース制御 .......................................................................................................................................... 340
51.2 メモリが一杯になる直前の状態.............................................................................................................. 343
51.3 クラスタイベント .......................................................................................................................................... 344
51.4 分散インメモリデータのリアルタイムバックアップ .................................................................. 348
51.5 サーバとクライアントの再接続.............................................................................................................. 349
51.6 稼働中のクラスタにおけるクラスタトポロジの変更 .................................................................. 350
51.7 プロダクションモード ................................................................................................................................. 352
51.8 分散ガベージコレクション（DGC） ..................................................................................................... 352
52 Terracotta構成情報リファレンス .................................................................................................................... 353
52.1 はじめに .............................................................................................................................................................. 353
52.2 構成情報の変数 ............................................................................................................................................... 353
52.3 パスの指定方法 ............................................................................................................................................... 354
14
52.4 tc.propertiesのオーバーライド ................................................................................................................ 354
52.5 構成情報のセクション ................................................................................................................................. 356
52.6 構成情報の<clients>セクション .............................................................................................................. 364
第 2 部 Terracotta管理コンソール ................................................................................................................................. 365
1 Terracotta管理コンソール ....................................................................................................................................... 365
1.1 TMSのインストールと構成情報の設定 .................................................................................................... 366
1.2 TMSの更新 .............................................................................................................................................................. 367
2 Terracotta管理コンソールのセキュリティの設定 ....................................................................................... 367
2.1 はじめに .................................................................................................................................................................. 367
2.2 セキュリティ保護なし ..................................................................................................................................... 368
2.3 デフォルトのセキュリティ保護 .................................................................................................................. 368
2.4 基本セキュリティ接続 ..................................................................................................................................... 368
2.5 SSLの追加 ................................................................................................................................................................ 371
2.6 証明書を使用するクライアント認証 ........................................................................................................ 372
2.7 TMCクライアントにSSL接続の使用を強制する方法 ......................................................................... 374
3 Terracotta REST API..................................................................................................................................................... 375
3.1 はじめに .................................................................................................................................................................. 375
3.2 管理サービスREST APIへの接続 .................................................................................................................. 376
3.3 HTTP運用のためのURI構築 ............................................................................................................................ 376
3.4 HTTPの仕様 ........................................................................................................................................................... 379
3.5 URIでクエリパラメーターを使う ............................................................................................................... 386
3.6 APIのバージョン ................................................................................................................................................. 386
3.7 JSONスキーマ ........................................................................................................................................................ 387
3.8 TSA向けREST API ................................................................................................................................................ 387
付録 ................................................................................................................................................................................................... 390
15
1 Terracotta管理コンソールのヘルプ .................................................................................................................... 390
1.1 ユーザーアカウントの設定 ............................................................................................................................ 390
1.2 TMCユーザーインターフェイス .................................................................................................................. 391
1.3 接続の管理.............................................................................................................................................................. 392
1.4 接続グループの監視 .......................................................................................................................................... 395
1.5 アプリケーションデータの管理 .................................................................................................................. 396
1.6 クラスタの監視 .................................................................................................................................................... 402
1.7 クラスタの管理 .................................................................................................................................................... 404
1.8 クラスタのトラブルシューティング ........................................................................................................ 405
1.9 プリファレンス .................................................................................................................................................... 407
2 Terracottaライセンスファイルの取り扱い ..................................................................................................... 407
2.1 ライセンスファイルを配置場所の明示的に指定する ....................................................................... 408
2.2 製品と機能の確認 ............................................................................................................................................... 408
3 BigMemory GoとHibernateの連携 ........................................................................................................................ 409
3.1 はじめに .................................................................................................................................................................. 409
3.2 ダウンロードとインストール ....................................................................................................................... 409
3.3 Mavenを利用したビルド ................................................................................................................................. 410
3.4 BigMemory Goを 2 次キャッシュプロバイダーとして設定 ........................................................... 410
3.5 クエリキャッシュと 2 次キャッシュの設定 ......................................................................................... 411
3.6 その他の設定 ......................................................................................................................................................... 411
3.7 クエリキャッシュと 2 次キャッシュ ........................................................................................................ 411
3.8 Hibernateのエンティティで 2 次キャッシュを使用するための構成 ........................................ 412
3.9 構成 ............................................................................................................................................................................ 413
3.10 デモアプリケーション ................................................................................................................................. 417
3.11 パフォーマンス向上のヒント .................................................................................................................. 417
16
3.12 FAQ ........................................................................................................................................................................ 417
4 BigMemory GoとSpringの連携................................................................................................................................ 419
4.1 はじめに .................................................................................................................................................................. 419
4.2 Spring 3.1 ................................................................................................................................................................ . 419
4.3 Spring 2.5 - 3.1: Spring用アノーテーション ........................................................................................... 419
4.4 Springプロジェクト用のアノーテーション ........................................................................................... 420
17
第 1 部 BigMemory Max
1 BigMemory Maxにようこそ
BigMemory Max は、分散サーバのメモリ内の全データを管理します。
BigMemory Max を使用すれば、メモリ容量の制限がなくなります。データセンターのマシンに設置
されている RAM のすべてを利用できるようになります。
BigMemory Max の 3 つの特徴：
• 分散サーバ全体のメモリを活用。メモリ容量の上限はありません。
• データの整合性を保証。
• メモリ内のデータに対する高度な監視、検索および管理機能を提供。
まず、BigMemory Max をダウンロードします。「Hello, World!」を見て、ライセンスキーのインス
トール、BigMemory Max の構成設定、BigMemory Max のデータストアをお使いのアプリケーショ
ンに接続する方法を、確認してください。
18
2 BigMemory Maxクイックスタートガイド
2.1 BigMemory Maxのインストール
BigMemory Max のインストールは非常に簡単です。キットをダウンロードし、利用中のアプリケー
ションのクラスパスにファイルを指定するだけです。必要な環境は JDK 1.6 だけです。
1. BigMemory Maxキットはダウンロードページから入手できます。
キットのファイル形式は「tar.gz」です。コマンドラインまたは専用のソフトウェアで解凍し
てください。
2. クラスパスに、以下の JAR ファイルを登録します。これらのファイルは、ダウンロードキット
に同梱されています。
– common/lib/bigmemory-<version>.jar – BigMemory の有効化に必要な JAR ファイルで
す。
– apis/ehcache/lib/ehcache-ee-<version>.jar – BigMemory Max にアクセスするための API集です。
– apis/ehcache/lib/slf4j-api-<version>.jar – BigMemory Max のログフレームワークを利用
するためのブリッジおよびログファサードです。
– apis/ehcache/lib/slf4j-jdk14-<version>.jar – SLF4Jログフレームワークjava.util.loggingのバインディングJARです。これ以外のログフレームワークへのバインドを行うJARは、SLF4JのWebサイトから入手できます。
– apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar – Terracotta サーバアレイの
ライブラリを含む JAR ファイルです。
3. BigMemory Max のライセンスキーファイルを BigMemory Max のホームディレクトリに保存し
ます。
ホームディレクトリではなく、アプリケーションのクラスパスにライセンスキーファイルを登
録することも可能です。あるいは、以下の Java のシステムプロパティでも登録できます。
-Dcom.tc.productkey.path=/path/to/terracotta-license.key
4. BigMemory Max は、Ehcache をユーザー向けのインターフェースとして使用します。
BigMemory Max の構成設定を行なうには、構成情報ファイル ehcache.xml を新規作成、あるい
は BigMemory Max キットの「config-samples/」ディレクトリのサンプルを更新してください。
以下に例を示します。
19
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="myBigMemoryMaxConfig"> <!-- Tell BigMemory where to write its data to disk. --> <diskStore path="/path/to/my/disk/store/directory"/> <!-- Set 'maxBytesLocalOffHeap' to the amount of off-heap in-memory storage you want to use. This memory is invisible to the Java garbage collector, providing for gigabytes to terabytes of in-memory data without garbage collection pauses. --> <cache name="myBigMemoryMaxStore" maxBytesLocalHeap="512M" maxBytesLocalOffHeap="8G"> <!-- Tell BigMemory to use the "localRestartable" persistence strategy for fast restart (optional). --> <persistence strategy="localRestartable"/> <!-- Include the terracotta element so that the data set will be managed as a client of the Terracotta server array. --> <terracotta/> <!-- Specify where to find the server array configuration. In this case, the configuration is retrieved from the local server. --> <terracottaConfig url="localhost:9510" /> </cache> </ehcache>
ehcache.xml ファイルは、クラスパスの最上位層に保存してください。
構成情報の詳細は、「構成情報のドキュメント」を参照してください。また、BigMemory Maxキットの config-samples ディレクトリに記録されている構成情報ファイル「ehcache.xml」も
参考にしてください。
5. Java オプションの-XX:MaxDirectMemorySize を使用して、JVM に十分なダイレクトメモリ領域
を割り当てます。ダイレクトメモリは、他のアプリケーションも使用します。したがって、構
成情報でオフヒープ領域に割り当てた値に、最低でも 250MB を追加した値を指定してくださ
い。以下に例を示します。
20
-XX:MaxDirectMemorySize=9G
MaxDirectMemorySize では、BigMemory に割り当てるメモリのサイズを指定します。この作
業の詳細は、「JVM へのダイレクトメモリの割り当て」を参照してください。
また、Java オプションの-Xmx も使用して、十分なヒープ領域を確保します。ヒープ領域も、
他のアプリケーションによって使用されます。したがって、構成情報でオンヒープ領域に割り
当てた値に他のアプリケーションが使用する値を追加し、その値を指定してください。以下に
例を示します。
-Xmx1g
最後に、必要であれば環境変数 JAVA_HOME を定義してください。
6. BigMemory の基本的な使用方法は「Hello, World!」を参照してください。また、BigMemory Max が提供する多様な機能と、それらの組み合わせ方法は「code samples」を参照してくださ
い。
2.2 Terracottaサーバと管理コンソールの起動
BigMemory Max で大きなデータセットを扱う場合は、それらを TSA（Terracotta サーバアレイ）に
分散配置し、TMC（Terracotta 管理コンソール）で管理します。
1. Terracotta サーバの構成設定を行なうには、構成情報ファイル tc-config.xml を新規作成、ある
いは BigMemory Max キットの「config-samples/」ディレクトリのサンプルを更新してくださ
い。以下に例を示します。
<?xml version="1.0" encoding="UTF-8" ?> <tc:tc-config xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd"> <servers> <server host="localhost" name="My Server Name"> <!-- Specify the path where the server should store its data. --> <data>/local/disk/path/to/terracotta/server1-data</data> <!-- Specify the port where the server should listen for client traffic. --> <tsa-port>9510</tsa-port> <jmx-port>9520</jmx-port> <tsa-group-port>9530</tsa-group-port> <!-- Enable BigMemory on the server. --> <offheap> <enabled>true</enabled>
21
<maxDataSize>4g</maxDataSize> </offheap> </server> <!-- Add the restartable element for Fast Restartability (optional). --> <restartable enabled="true"/> </servers> <clients> <logs>logs-%i</logs> </clients> </tc:tc-config>
tc-config.xml を、Terracotta の「server/」ディレクトリに保存します。
構成情報に指定するオプションの詳細は「TSA 構成情報のドキュメント」を参照してください。
2. ターミナルを操作し、Terracotta の「server/」ディレクトリに移動します。start-tc-server コ
マンドを実行します。
%> cd /path/to/bigmemory-max-<version>/server %> ./bin/start-tc-server.sh
サーバ起動を確認するメッセージが端末に表示されます。
注意: Microsoft Windows の場合、拡張子「BAT」をスクリプトファイルとして実行してくださ
い。また、スラッシュ（"/")をバックスラッシュ「"\"」に置き換えてください。
3. ターミナルを操作し、Terracotta の「tools/Management-console/」ディレクトリに移動します。
start-tmc コマンドを実行します。
%> cd /path/to/bigmemory-max-<version>/tools/management-console %> ./bin/start-tmc.sh
4. ブラウザを起動し、URLhttp://localhost:9889/tmc を開きます。TMC に初めて接続すると、認
証セットアップのページが表示されます。このページで、TMC を利用する際の認証の有無を
選択します。
22
5. 配備済みのクライアントとサーバは、すべて TMC を利用して管理します。TMC の詳細は、
「TMC のドキュメント」を参照してください。
2.3 その他の構成情報
BigMemory Max の構成設定の概要は、「構成の概要のページ」を参照してください。ここでは、特
に注目すべき構成情報を紹介します。
2.3.1 Automatic Resource Control ARC（Automatic Resource Control）を利用すると、パフォーマンスを細かく調整できるようになり
ます。この機能を利用して、スループット、遅延、データアクセスのバランスを調整してください。
領域サイズを指定するパラメーターは、ストレージ層ごとに指定できます。また、アクセス頻度の
23
高いデータや常にメモリ上に配置したいデータを、特定のストレージ層に固定するためのパラメー
ターもあります。
ストレージ層のサイズ指定
チューニングを実施するには、ストレージ層に適切なサイズを設定する必要があります。
BigMemory Max の各ストレージ層のサイズは、さまざまな構成情報を使って指定します。「ストレ
ージ層のサイズ指定」では、ストレージ層に対するメモリの動的な割り当てや自動バランスによっ
て、ストレージ層のサイズを細かくチューニングする方法を説明します。
データのピンニング
インメモリのストレージ層の運用では、BigMemory Max の各ストレージ層のデータの有効期限を正
しく管理することが非常に重要です。データのピンニング、有効期限、エビクションの詳細は「デ
ータの有効期限」を参照してください。
2.3.2 高速再起動 BigMemory Max は十分な耐障害性を持っています。インメモリのデータをローカルディスクに常時
記録することで、インメモリのデータを完全な状態で保持する機能を提供しています。このため、
計画に基づいたシャットダウンや障害によるシャットダウンのあとでも、インメモリのデータの内
容を保証します。「高速再起動」では、データ永続化、高速再起動と、インメモリデータ（ヒープ
ストアとオフヒープストア）用にローカルディスクをストレージ層として使用する方法を説明しま
す。
2.3.3 BigMemory MaxのAPIの使用 BigMemory Max は、さまざまな種類の API を提供しています。API を初めて使用する場合は、「サ
ンプルコード集」を参照してください。ここでは、特に重要な API の機能を紹介します。
検索
数ギガバイトや数テラバイトといったサイズに達する数十億のエントリーを 1 秒以下で検索し、検
索結果を返します。データのインデックス作成によるオーバーヘッドは、ほとんどありません。
「GroupBy」のような機能も提供します。
「検索 API」を利用すると、インデックス生成前のデータに対し、任意の複合クエリを実行できま
す。値の代替インデックスを作成すると、キーだけを使用したデータの参照に加え、複数の条件を
利用した参照も可能になります。
トランザクションのキャッシュ
拡張機能のトランザクションモードでは、記録データに対する不可分な操作が可能です。この機能
により、データベース内容との整合性を保証します。
24
「トランザクション」のページでは、BigMemory Max のトランザクションの技術的な情報と、構成
情報の設定方法を説明します。XA トランザクションやローカルトランザクションでは、「明示的
ロック」も利用できます。
2.3.4 管理と監視 「Terracotta 管理コンソール」（TMC）は、Web を利用して監視と管理を行うアプリケーションで
す。エラーの検出やキャッシュ活用のチューニングを提供します。TMC は、本番業務の管理システ
ムとも統合しやすいアクセスポイントとなっています。
TMC 以外に、「JMX を利用した管理と監視」を行う方法もあります。
BigMemory Max は、柔軟度の高い「SLF4J ログフレームワーク」を利用してログを作成します。
2.4 システム規模の変更
• インメモリで大量のデータを取り扱うための構成設定方法は「分散構成設定ガイド」を参照し
てください。
• BigMemory Max の能力を最大限に活用するための方法は「Terracotta サーバアレイ」を参照し
てください。
3 Hello, World!
BigMemory を利用する前に、Ehcache のインスタンスを 1 つ以上セットアップしておく必要があり
ます。BigMemory は、主要なプログラミングインターフェースとして Ehcache を利用するからで
す。
• BigMemory Max のキットをダウンロードし、解凍します。
• クラスパスにライセンスキー（terracotta-license.key）を登録します。
• クラスパスに、以下の JAR ファイルを登録します。このファイルは、BigMemory Max 4.x.x の
ダウンロードキットに同梱されています。
• common/lib/bigmemory-4.x.x.jar
• apis/ehcache/lib/ehcache-ee-2.7.1.jar
• apis/ehcache/lib/slf4j-api-1.6.6.jar
• apis/ehcache/lib/slf4j-jdk14-1.6.6.jar
25
3.1 構成情報ファイルの作成
基本構成情報ファイルを作成して「ehcache.xml」という名前で保存し、それをクラスパスに登録し
ます。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="HelloWorldConfig"> <cache name="hello-world" maxBytesLocalHeap="64M"/> </ehcache>
このように指定すると、BigMemory は、64MB（メガバイト）のサイズを持つ「hello-world」とい
う名前のデータストア領域を、Java 仮想マシンのヒープ領域に確保します。
3.2 HelloWorld.javaの作成
「HelloWorld」という名前の Java クラスを作成し、コンパイルします。
import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; public class HelloWorld { public static void main(final String[] args) { // Create a cache manager final CacheManager cacheManager = new CacheManager(); // create the data store called "hello-world" final Cache dataStore = cacheManager.getCache("hello-world"); // create a key to map the data to final String key = "greeting"; // Create a data element final Element putGreeting = new Element(key, "Hello, World!"); // Put the element into the data store dataStore.put(putGreeting);
26
// Retrieve the data element final Element getGreeting = dataStore.get(key); // Print the value System.out.println(getGreeting.getObjectValue()); } }
3.3 実行
このプログラムを実行すると、BigMemory は、ライセンス情報と起動情報、そして「Hello, World!」という文字列を表示します。
3.4 次のステップ
「次のステップ：基本 CRUD（Create, Read, Update, Delete） ›」
4 基本CRUD 前のページの作業で、Ehcache インターフェースを利用した BigMemory インスタンスの準備が整
いました。このページでは、基本的な CRUD（Create, Read, Update, Delete）関数の利用方法を紹介
します。
4.1 構成情報ファイルの作成
構成情報ファイル「ehcache-crud.xml」を作成し、クラスパスに登録します。こうして、「crud」という名前の新しいキャッシュを作成します。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="CRUDConfig" maxBytesLocalHeap="64M"> <cache name="hello-world"/> <cache name="crud"/> </ehcache>
(maxByteLocalHeap 属性が最上位の<ehcache>要素で定義されていることに注目してください。
BigMemory のメモリプロファイルの設定方法には、各データセットに対して個別に設定する方法と、
すべてのデータセットに対する共通定義を設定する方法があります。)
4.2 Crud.javaの作成
ここでは、「Crud」という名前の Java クラスを作成し、コンパイルします。
27
import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; public class Crud { public static void main(final String[] args) { // Create a cache manager using the factory method // AND specify the new configuration file final CacheManager cacheManager = CacheManager.newInstance( Crud.class.getResource("/ehcache-crud.xml")); // Get the "crud" cache from the cache manager... final Cache dataStore = cacheManager.getCache("crud"); // Set up the first data element... final String myKey = "My Key"; final String myData = "My Data"; final Element createElement = new Element(myKey, myData); // CREATE data using the put(Element) method... dataStore.put(createElement); System.out.println("Created data: " + createElement); // READ data using the get(Object) method... Element readElement = dataStore.get(myKey); System.out.println("Read data: " + readElement); // Check to make sure the data is the same... if (! myData.equals(readElement.getObjectValue())) { throw new RuntimeException("My data doesn't match!"); } // UPDATE data by mapping a new value to the same key... final String myNewData = "My New Data"; final Element updateElement = new Element(myKey, myNewData); dataStore.put(updateElement); System.out.println("Updated data: " + updateElement);
28
// Test to see that the data is updated... readElement = dataStore.get(myKey); if (! myNewData.equals(readElement.getObjectValue())) { throw new RuntimeException("My data doesn't match!"); } // DELETE data using the remove(Object) method... final boolean wasRemoved = dataStore.remove(myKey); System.out.println("Removed data: " + wasRemoved); if (! wasRemoved) { throw new RuntimeException("My data wasn't removed!"); } // Be polite and release the CacheManager resources... cacheManager.shutdown(); } }
4.3 実行
このプログラム「Crud」を実行すると、以下の情報が出力されます。
Created data: [ key = My Key, value=My Data, version=1, hitCount=0, CreationTime = 1361401376761, LastAccessTime = 1361401376761 ] Read data: [ key = My Key, value=My Data, version=1, hitCount=1, CreationTime = 1361401376761, LastAccessTime = 1361401376775 ] Updated data: [ key = My Key, value=My New Data, version=1, hitCount=0, CreationTime = 1361401376776, LastAccessTime = 1361401376776 ] Removed data: true
4.4 次のステップ
「次のステップ：検索 ›」
5 検索 前のページでは、BigMemory の基本 CRUD（Create, Read, Update, Delete）を紹介しました。このペ
ージでは検索機能を紹介します。
ここでは、身長、体重、BMI といった検索可能な属性を持つ Person オブジェクトのデータセット
を作成します。
29
5.1 構成情報ファイルの作成
構成情報ファイル「ehcache-search.xml」を作成し、クラスパスに登録します。こうして、「search」という名前の新しいキャッシュを作成します。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="SearchConfig" maxBytesLocalHeap="64M"> <cache name="hello-world"/> <cache name="crud"/> <cache name="search"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> <searchAttribute name="bodyMassIndex" /> </searchable> </cache> </ehcache>
5.2 Search.javaの作成
ここでは、「Search」という名前の Java クラスを作成し、コンパイルします。
import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; import net.sf.ehcache.search.Attribute; import net.sf.ehcache.search.Query; import net.sf.ehcache.search.Result; import net.sf.ehcache.search.Results; public class Search { public static void main(final String[] args) { // Create a cache manager using the factory method... final CacheManager cacheManager = CacheManager.newInstance(Crud.class .getResource("/ehcache-search.xml")); // Retrieve the "search" data set... final Cache dataSet = cacheManager.getCache("search");
30
// Create some searchable objects... final Person janeAusten = new Person(1, "Jane", "Austen", 5 * 12 + 7, 130); final Person charlesDickens = new Person(2, "Charles", "Dickens", 5 * 12 + 9, 160); final Person janeDoe = new Person(3, "Jane", "Doe", 5 * 12 + 5, 145); // Put the searchable objects into the data set... dataSet.put(new Element(janeAusten.getId(), janeAusten)); dataSet.put(new Element(charlesDickens.getId(), charlesDickens)); dataSet.put(new Element(janeDoe.getId(), janeDoe)); // Fetch the Body Mass Index (BMI) attribute... Attribute<Object> bmi = dataSet.getSearchAttribute("bodyMassIndex"); // Create a query for all people with a BMI greater than 23... final Query query = dataSet.createQuery().addCriteria(bmi.gt(23F)) .includeValues(); // Execute the query... final Results results = query.execute(); // Print the results... for (Result result : results.all()) { System.out.println(result.getValue()); } } public static class Person { private final String firstName; private final String lastName; private final long id; private final int height; private final int weight; public Person(long id, final String firstName, final String lastName, final int height, final int weight) { this.id = id; this.firstName = firstName;
31
this.lastName = lastName; this.height = height; this.weight = weight; } public String getFirstName() { return firstName; } public String getLastName() { return lastName; } public int getHeight() { return height; } public int getWeight() { return weight; } public float getBodyMassIndex() { return ((float) weight / ((float) height * (float) height)) * 703; } public long getId() { return id; } public String toString() { return "[id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", height=" + height + " in" + ", weight=" + weight + " lbs" + ", bmi=" + getBodyMassIndex() + "]"; } } }
32
5.3 実行
このプログラム「Search」を実行すると、以下の情報が出力されます。
[id=2, firstName=Charles, lastName=Dickens, height=69 in, weight=160 lbs, bmi=23.625288] [id=3, firstName=Jane, lastName=Doe, height=65 in, weight=145 lbs, bmi=24.126627]
5.4 次のステップ
「次のステップ：結果のソート ›」
6 結果のソート 前のページでは、データセットの検索を紹介しました。ここでは、検索結果のソート方法を紹介し
ます。
6.1 構成情報ファイルの作成
構成情報ファイル「ehcache-sort.xml」を作成し、クラスパスに登録します。こうして、「sort」と
いう名前の新しいキャッシュを登録します。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="SortConfig" maxBytesLocalHeap="64M"> <cache name="hello-world"/> <cache name="crud"/> <cache name="search"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> <searchAttribute name="bodyMassIndex" /> </searchable> </cache> <cache name="sort"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> </searchable> </cache> </ehcache>
33
6.2 Sort.javaの作成
ここでは、「Sort」という名前の Java クラスを作成し、コンパイルします。
import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; import net.sf.ehcache.search.Attribute; import net.sf.ehcache.search.Direction; import net.sf.ehcache.search.Query; import net.sf.ehcache.search.Result; import net.sf.ehcache.search.Results; public class Sort { public static void main(final String[] args) { // Create a cache manager using the factory method... final CacheManager cacheManager = CacheManager.newInstance(Sort.class .getResource("/ehcache-sort.xml")); // Retrieve the "sort" data set... final Cache dataSet = cacheManager.getCache("sort"); // Create some objects... final Person janeAusten = new Person(1, "Jane", "Austen", 5 * 12 + 7, 130); final Person charlesDickens = new Person(2, "Charles", "Dickens", 5 * 12 + 9, 160); final Person janeDoe = new Person(3, "Jane", "Doe", 5 * 12 + 5, 145); final Person alexSmith = new Person(4, "Alex", "Smith", 5 * 12 + 5, 160); // Put the objects into the data set... dataSet.put(new Element(janeAusten.getId(), janeAusten)); dataSet.put(new Element(charlesDickens.getId(), charlesDickens)); dataSet.put(new Element(janeDoe.getId(), janeDoe)); dataSet.put(new Element(alexSmith.getId(), alexSmith)); // Fetch the height and weight attributes that we'll use in the query... Attribute<Integer> height = dataSet.getSearchAttribute("height"); Attribute<Integer> weight = dataSet.getSearchAttribute("weight");
34
// Create a query for all people with a height greater than 5' 0", ordered // first by height, then by weight... this will retrieve the entire data // set, but we'll get to see how the results are sorted. final Query query = dataSet.createQuery().addCriteria(height.gt(5 * 12)) .addOrderBy(height, Direction.DESCENDING) .addOrderBy(weight, Direction.DESCENDING).includeValues(); // Execute the query... final Results results = query.execute(); // Print the results... for (Result result : results.all()) { System.out.println(result.getValue()); } } public static class Person { private final String firstName; private final String lastName; private final long id; private final int height; private final int weight; public Person(final long id, final String firstName, final String lastName, final int height, final int weight) { this.id = id; this.firstName = firstName; this.lastName = lastName; this.height = height; this.weight = weight; } public String getFirstName() { return firstName; } public String getLastName() { return lastName;
35
} public int getHeight() { return height; } public int getWeight() { return weight; } public float getBodyMassIndex() { return ((float) weight / ((float) height * (float) height)) * 703; } public long getId() { return id; } public String toString() { return "[id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", height=" + height + " in" + ", weight=" + weight + " lbs" + ", bmi=" + getBodyMassIndex() + "]"; } } }
6.3 実行
このプログラム「Sort」を実行すると、以下の情報が出力されます。
[id=2, firstName=Charles, lastName=Dickens, height=69 in, weight=160 lbs, bmi=23.625288] [id=1, firstName=Jane, lastName=Austen, height=67 in, weight=130 lbs, bmi=20.358654] [id=4, firstName=Alex, lastName=Smith, height=65 in, weight=160 lbs, bmi=26.622484] [id=3, firstName=Jane, lastName=Doe, height=65 in, weight=145 lbs, bmi=24.126627]
出力は、身長（height）でソートされています。最後の２行の身長は同じ値です。これらは、２番
目のキーである体重（weight）でソートされています。
6.4 次のステップ
「次のステップ：結果のグループ化 ›」
36
7 結果のグループ化 Ehcache の検索インターフェースは、検索結果のソートのほか、検索結果のグループ化や集計の機
能も備えています。これまでに紹介したサンプルコードを改造し、これらの機能を使用してみまし
ょう。
7.1 構成情報ファイルの作成
構成情報ファイル「ehcache-group.xml」を作成し、クラスパスに登録します。こうして、「group」という名前の新しいキャッシュを作成します。既存の「Person」クラスに、新しい属性「Gender」を追加します。そして、この属性を、構成情報の「searchAttribute」に追加します。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="SampleConfig" maxBytesLocalHeap="64M"> <cache name="hello-world"/> <cache name="crud"/> <cache name="search"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> <searchAttribute name="bodyMassIndex" /> </searchable> </cache> <cache name="sort"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> </searchable> </cache> <cache name="group"> <searchable> <searchAttribute name="height"/> <searchAttribute name="gender"/> <searchAttribute name="bmi" expression="value.getBodyMassIndex()"/> </searchable> </cache> </ehcache>
37
7.2 Group.javaの作成
ここでは、「Group」という名前の Java クラスを作成し、コンパイルします。
import java.util.List; import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; import net.sf.ehcache.search.Attribute; import net.sf.ehcache.search.Direction; import net.sf.ehcache.search.Query; import net.sf.ehcache.search.Result; import net.sf.ehcache.search.Results; import net.sf.ehcache.search.aggregator.Aggregators; public class Group { public static void main(final String[] args) { // Create a cache manager using the factory method... final CacheManager cacheManager = CacheManager.newInstance(Group.class .getResource("/ehcache-group.xml")); // Retrieve the "sort" data set... final Cache dataSet = cacheManager.getCache("group"); // Create some objects... final Person janeAusten = new Person(1, "Jane", "Austen", "Female", 5 * 12 + 7, 130); final Person charlesDickens = new Person(2, "Charles", "Dickens", "Male", 5 * 12 + 9, 160); final Person janeDoe = new Person(3, "Jane", "Doe", "Female", 5 * 12 + 5, 145); final Person alexSmith = new Person(4, "Alex", "Smith", "Other", 5 * 12 + 5, 160); // Put the objects into the data set... dataSet.put(new Element(janeAusten.getId(), janeAusten)); dataSet.put(new Element(charlesDickens.getId(), charlesDickens)); dataSet.put(new Element(janeDoe.getId(), janeDoe)); dataSet.put(new Element(alexSmith.getId(), alexSmith));
38
// Fetch the search attributes that we'll use in our query and when fetching // our results... Attribute<Integer> height = dataSet.getSearchAttribute("height"); Attribute<String> gender = dataSet.getSearchAttribute("gender"); Attribute<Float> bmi = dataSet.getSearchAttribute("bmi"); // Create a query object. (This query is designed to select the entire data // set.) final Query query = dataSet.createQuery().addCriteria(height.gt(5 * 12)); // Group by the gender attribute so we can perform aggregations on each // gender... query.addGroupBy(gender); query.includeAttribute(gender); // Include an aggregation of the average height and bmi of each gender in // the results... query.includeAggregator(Aggregators.average(height)); query.includeAggregator(Aggregators.average(bmi)); // Include the count of the members of each gender query.includeAggregator(Aggregators.count()); // Make the results come back sorted by gender in alphabetical order query.addOrderBy(gender, Direction.ASCENDING); // Execute the query... final Results results = query.execute(); // Print the results... for (Result result : results.all()) { String theGender = result.getAttribute(gender); List<Object> aggregatorResults = result.getAggregatorResults(); Float avgHeight = (Float) aggregatorResults.get(0); Float avgBMI = (Float) aggregatorResults.get(1); Integer count = (Integer) aggregatorResults.get(2); System.out.println("Gender: " + theGender + "; count: " + count + "; average height: " + avgHeight + "; average BMI: " + avgBMI);
39
} } public static class Person { private final String firstName; private final String lastName; private final long id; private final int height; private final int weight; private String gender; public Person(final long id, final String firstName, final String lastName, final String gender, final int height, final int weight) { this.id = id; this.firstName = firstName; this.lastName = lastName; this.gender = gender; this.height = height; this.weight = weight; } public String getFirstName() { return firstName; } public String getLastName() { return lastName; } public String getGender() { return gender; } public int getHeight() { return height; } public int getWeight() { return weight;
40
} public float getBodyMassIndex() { return ((float) weight / ((float) height * (float) height)) * 703; } public long getId() { return id; } public String toString() { return "[id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", height=" + height + " in" + ", weight=" + weight + " lbs" + ", bmi=" + getBodyMassIndex() + "]"; } } }
7.3 実行
このプログラム「Group」を実行すると、以下の情報が出力されます。
Gender: Female; count: 2; average height: 66.0; average BMI: 22.242641 Gender: Male; count: 1; average height: 69.0; average BMI: 23.625288 Gender: Other; count: 1; average height: 65.0; average BMI: 26.622484
7.4 次のステップ
「次のステップ：サーバアレイの追加 ›」
8 Terracottaサーバアレイの追加 Terracotta サーバアレイは、インメモリデータのサーバアレイです。テラバイト単位のインメモリ
データを備えた遅延のないデータアクセス、高いパフォーマンス、そしてエンタープライズシステ
ムに不可欠な高可用性、スケーラビリティ、耐障害性などを備えたアプリケーションをシームレス
に提供します。
まず Terracotta サーバを起動し、そこからデータセットにアクセスしてみましょう。
41
8.1 事前準備
• Terracotta のインストール先の最上位ディレクトリに、有効な Terracotta ライセンスキーを登
録します。
• クラスパスに、以下の JAR ファイルを登録します。このファイルは、BigMemory Max 4.x.x の
ダウンロードキットに同梱されています。
• apis/toolkit/lib/terracotta-toolkit-runtime-ee-4.x.x.jar
• Terracotta 構成情報を、構成情報ファイルに追加します（以下を参照してください）。
• データクラスがシリアル化可能であることを確認します。
• Terracotta サーバのインスタンスを起動します。
8.2 構成情報ファイルの作成
クラスパスに構成情報ファイル「ehcache-server-array.xml」を新規登録します。これにより、新し
いキャッシュ「server-array」を追加します。（名前は何でもかまいません。ただし、プログラム
側でも、ここで登録した名前を使用する必要があります。）
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="SampleConfig" maxBytesLocalHeap="64M"> <cache name="hello-world"/> <cache name="crud"/> <cache name="search"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> <searchAttribute name="bodyMassIndex" /> </searchable> </cache> <cache name="sort"> <searchable> <searchAttribute name="height"/> <searchAttribute name="weight"/> </searchable> </cache> <cache name="group"> <searchable>
42
<searchAttribute name="height"/> <searchAttribute name="gender"/> <searchAttribute name="bmi" expression="value.getBodyMassIndex()"/> </searchable> </cache> <cache name="server-array"> <searchable> <searchAttribute name="height"/> <searchAttribute name="gender"/> <searchAttribute name="bmi" expression="value.getBodyMassIndex()"/> </searchable> <!-- Add the terracotta element to this cache. This causes this data set to be managed by the Terracotta server array. For the purposes of demonstration, we set the consistency to "strong" to ensure that data is always consistent across the entire distributed system. There are other consistency settings that may be more suitable for different data sets and applications. --> <terracotta consistency="strong"/> </cache> <!-- Add the terracottaConfig element to specify where to find the configuration specific to the server array. In this case, the configuration is retrieved from the server array itself. --> <terracottaConfig url="localhost:9510"/> </ehcache>
8.3 ServerArrayTest.javaの作成
ここでは、「ServerArrayTest」という名前の Java クラスを作成し、コンパイルします。
import java.io.Serializable; import java.util.List; import net.sf.ehcache.Cache; import net.sf.ehcache.CacheManager; import net.sf.ehcache.Element; import net.sf.ehcache.search.Attribute; import net.sf.ehcache.search.Direction; import net.sf.ehcache.search.Query; import net.sf.ehcache.search.Result; import net.sf.ehcache.search.Results;
43
import net.sf.ehcache.search.aggregator.Aggregators; public class ServerArrayTest { public static void main(final String[] args) { // Create a cache manager using the factory method... final CacheManager cacheManager = CacheManager.newInstance(Group.class .getResource("/ehcache-server-array.xml")); // Retrieve the "sort" data set... final Cache dataSet = cacheManager.getCache("server-array"); // Check to see if there's any data in it yet... Element person1 = dataSet.get(1L); if (person1 == null) { System.out.println("We didn't find any data in the server array." + " This must be the first execution."); // The data isn't in the server array yet (this must be the first time we // ran the program), so let's create some objects... final Person janeAusten = new Person(1, "Jane", "Austen", "Female", 5 * 12 + 7, 130); final Person charlesDickens = new Person(2, "Charles", "Dickens", "Male", 5 * 12 + 9, 160); final Person janeDoe = new Person(3, "Jane", "Doe", "Female", 5 * 12 + 5, 145); final Person alexSmith = new Person(4, "Alex", "Smith", "Other", 5 * 12 + 5, 160); // Put the objects into the data set... dataSet.put(new Element(janeAusten.getId(), janeAusten)); dataSet.put(new Element(charlesDickens.getId(), charlesDickens)); dataSet.put(new Element(janeDoe.getId(), janeDoe)); dataSet.put(new Element(alexSmith.getId(), alexSmith)); } else { System.out.println("We found data in the server array from a previous" + " execution. No need to create new data.");
44
} // Fetch the search attributes that we'll use in our query and when fetching // our results... Attribute<Integer> height = dataSet.getSearchAttribute("height"); Attribute<String> gender = dataSet.getSearchAttribute("gender"); Attribute<Float> bmi = dataSet.getSearchAttribute("bmi"); // Create a query object. (This query is designed to select the entire data // set.) final Query query = dataSet.createQuery().addCriteria(height.gt(5 * 12)); // Group by the gender attribute so we can perform aggregations on each // gender... query.addGroupBy(gender); query.includeAttribute(gender); // Include an aggregation of the average height and bmi of each gender in // the results... query.includeAggregator(Aggregators.average(height)); query.includeAggregator(Aggregators.average(bmi)); // Include the count of the members of each gender query.includeAggregator(Aggregators.count()); // Make the results come back sorted by gender in alphabetical order query.addOrderBy(gender, Direction.ASCENDING); // Execute the query... final Results results = query.execute(); // Print the results... for (Result result : results.all()) { String theGender = result.getAttribute(gender); List<Object> aggregatorResults = result.getAggregatorResults(); Float avgHeight = (Float) aggregatorResults.get(0); Float avgBMI = (Float) aggregatorResults.get(1); Integer count = (Integer) aggregatorResults.get(2); System.out.println("Gender: " + theGender + "; count: " + count
45
+ "; average height: " + avgHeight + "; average BMI: " + avgBMI); } } public static class Person implements Serializable { private static final long serialVersionUID = 1L; private final String firstName; private final String lastName; private final long id; private final int height; private final int weight; private String gender; public Person(final long id, final String firstName, final String lastName, final String gender, final int height, final int weight) { this.id = id; this.firstName = firstName; this.lastName = lastName; this.gender = gender; this.height = height; this.weight = weight; } public String getFirstName() { return firstName; } public String getLastName() { return lastName; } public String getGender() { return gender; } public int getHeight() { return height; }
46
public int getWeight() { return weight; } public float getBodyMassIndex() { return ((float) weight / ((float) height * (float) height)) * 703; } public long getId() { return id; } public String toString() { return "[id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", height=" + height + " in" + ", weight=" + weight + " lbs" + ", bmi=" + getBodyMassIndex() + "]"; } } }
8.4 Terracottaサーバインスタンスの起動
BigMemory Max の配付版のディレクトリにある「server」ディレクトリを開きます。次に、そのデ
ィレクトリから「start-tc-server」コマンドを実行します。
%> cd /path/to/bigmemory-max-4.x.x/server %> ./bin/start-tc-server.sh
8.5 実行
最初に「ServerArrayTest」プログラムを実行したときは、サーバアレイ上にデータがありません。
このため、以下のような情報が出力されます。
We didn't find any data in the server array. This must be the first execution. Gender: Female; count: 2; average height: 66.0; average BMI: 22.242641 Gender: Male; count: 1; average height: 69.0; average BMI: 23.625288 Gender: Other; count: 1; average height: 65.0; average BMI: 26.622484
再び「ServerArrayTest」プログラムを実行すると（すでに実行中の Terracotta サーバインスタンス
は再起動しないでください）、今度はサーバアレイからデータを取得できます。次のような情報が
出力されます。
47
We found data in the server array from a previous execution. No need to create new data. Gender: Female; count: 2; average height: 66.0; average BMI: 22.242641 Gender: Male; count: 1; average height: 69.0; average BMI: 23.625288 Gender: Other; count: 1; average height: 65.0; average BMI: 26.622484
デフォルトの構成情報を利用している場合、すべてのデータはインメモリに記録されています（構
成情報で高速再起動を有効化すると、これらのデータを簡単に永続化できます）。これらのデータ
をクリアするには、「ServerArrayTest」プログラムを再実行する前に、サーバを再起動してくださ
い。
8.6 次のステップ
このページでは、BigMemory Max が提供するサーバアレイの使用方法を簡単に紹介しました。初め
て利用する方のために、できる限り簡単な構成情報を使用しました。構成情報を変更することで、
さまざまな機能や配備トポロジを利用できるようになります。これらの情報は、ほかのドキュメン
トに紹介されています。さまざまな構成を試し、実際の業務アプリケーションのパフォーマンスや
スケールに最適な構成を見つけ出してください。
9 サンプルコード集 このページでは、BigMemory Max キットで提供しているサンプルコードを紹介します。BigMemoryのチュートリアルについては、「Hello, World!」を参照してください。
9.1 はじめに
以下のサンプルコードは、BigMemory Max のさまざまな機能を表しています。サンプルコードはす
べて、BigMemory Max キットの/code-samples ディレクトリに格納されています。
名称 説明
「example01-config-file」
BigMemory は、XML 構成情報ファイルを使って設定できます。また、Fluent Configuration API を使ってプログラムで設定することも可能です。このサン
プルでは、XML 構成情報ファイルを使って宣言的に BigMemory Max の基本イ
ンスタンスを設定する方法を紹介します。
「example02-config-programmatic」
Fluent Configuration API を使って、プログラムで BigMemory Max の基本イン
スタンスを設定します。
「example03-crud」
BigMemory Max でできる基本的な作成・読み取り・更新・削除（CRUD）操作
です。
「example04-search」
BigMemory Max の基本的なインメモリ検索機能です。
「example05- ノンストップ機能は、クラスタから切断されたクライアントを続行させるこ
とができます。その後、リジョインによる再接続機能を使って、クライアン
48
nonstop」 トが Terracotta 構成ソースを識別してクラスタを結合できるようにします。
このサンプルでは、BigMemory Max.のノンストップ機能とリジョインによる
再接続機能を例示します。
「example06-arc」 Automatic Resource Control（ARC）は BigMemory Max の強力な機能です。こ
の機能を使ってユーザーは、ヒープメモリとオフヒープメモリにデータをど
れくらい格納するかを制御することができます。このサンプルでは、ARC を
使ってデータ層のサイズを指定する基本的な構成オプションを例示します。
「example07-cache」
BigMemory Max は、強力なインメモリデータ管理ソリューションです。多数
のアプリケーションの中でも、BigMemory Max をキャッシュとして使うこと
で、低速または重いデータベースやリモートデータソースからのデータアク
セスのスピードを高めることができます。この例では、BigMemory Max で利
用できるキャッシュ機能を設定する方法を表しています。
サンプルコードは Maven で動かすため、Terracotta Maven リポジトリを Maven の settings.xml ファイルに追加する必要があります。以下のリポジトリ情報を settings.xml ファイルに追加してくだ
さい。
<repository> <id>terracotta-repository</id> <url>http://www.terracotta.org/download/reflector/releases</url> <releases> <enabled>true</enabled> </releases> </repository>
詳細な情報については、Apache Mavenとの連携をご覧ください。
9.2 例 1：XMLによる構成設定
XML で BigMemory を設定するには、CacheManager インスタンスを作成し、ファイル名または
URL オブジェクトをコンストラクタに送ります。
以下の例は、/xml/ehcache.xml でクラスパスに XML ファイルの URL を入れて CacheManager を作
成する方法を表しています。
CacheManager manager = CacheManager.newInstance( getClass().getResource("/xml/ehcache.xml")); try { Cache bigMemory = manager.getCache("BigMemory"); // now do stuff with it... } finally {
49
if (manager != null) manager.shutdown(); }
このサンプルで用いた XML 構成情報ファイルの内容は以下のとおりです。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" name="config"> <cache name="BigMemory" maxBytesLocalHeap="512M" maxBytesLocalOffHeap="32G" copyOnRead="true" statistics="true" eternal="true"> </cache> </ehcache>
構成要素の maxBytesLocalOffHeap で、オフヒープメモリをどれくらい使うかを設定します。
BigMemory 独自のオフヒープメモリストレージを使って、サーバ上で利用できるすべてのメモリを
一つの JVM で、ギガバイトからテラバイトサイズまで、ガーベジコレクションによる一時中断なく、
使うことができます。
9.3 例 2：プログラムによる構成設定
プログラムでBigMemory Maxを設定するには、Ehcache fluent configuration APIを使います。
Configuration managerConfiguration = new Configuration() .name("bigmemory-config") .cache(new CacheConfiguration() .name("BigMemory") .maxBytesLocalHeap(512, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(1, MemoryUnit.GIGABYTES) .copyOnRead(true) .statistics(true) .eternal(true) ); CacheManager manager = CacheManager.create(managerConfiguration); try { Cache bigMemory = manager.getCache("BigMemory"); // now do stuff with it...
50
} finally { if (manager != null) manager.shutdown(); }
9.4 例 3：基本CRUD（Create, Read, Update, Delete）
CRUD サンプルでは、基本的な作成・読み取り・更新・削除といった操作を例示します。
まず、512MB のヒープメモリと 32GB のオフヒープメモリを使うために設定した BigMemory のデ
ータストアを作成します。
Configuration managerConfiguration = new Configuration(); managerConfiguration.updateCheck(true) .monitoring(Configuration.Monitoring.AUTODETECT) .name("config") .cache(new CacheConfiguration() .name("BigMemory-Crud") .maxBytesLocalHeap(512, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(32, MemoryUnit.GIGABYTES) ); CacheManager manager = CacheManager.create(managerConfiguration); Cache bigMemory = manager.getCache("BigMemory-Crud");
上記は、ナノ秒からマイクロ秒アクセスでヒープに最大 512MB のデータを格納できるという、
BigMemory の Automatic Resource Control（ARC）性能を示しています。この例では、512MB のヒ
ープメモリが一杯になると ARC が自動的にデータを 32GB のオフヒープメモリに移動します。オフ
ヒープで利用できる速度はマイクロ秒です。この設定で、ヒープのサイズを小さく抑えてガーベジ
コレクションによる一時中断やチューニングを避けながら、大量の処理中のメモリを使って超高速
でデータにアクセスすることができます。
重要：BigMemory Max は、ギガバイトからテラバイトのデータを単一の JVM で処理対応することが
でき、最大 32GB まで自由に使うことができます。スワップを避けるため、ハードウェアで物理的
に可能なメモリより多く使うために BigMemory Max を設定しないよう、注意してください。
以上で、BigMemory インスタンスを設定し利用できるようになりました。以下のように、データ作
成を開始します。
final Person timDoe = new Person("Tim Doe", 35, Person.Gender.MALE, "eck street", "San Mateo", "CA"); bigMemory.put(new Element("1", timDoe));
51
以下のように、データを読み取ります。
final Element element = bigMemory.get("1"); System.out.println("The value for key 1 is " + element.getObjectValue());
以下のように、データを更新します。
final Person pamelaJones = new Person("Pamela Jones", 23, Person.Gender.FEMALE, "berry st", "Parsippany", "LA"); bigMemory.put(new Element("1", pamelaJones)); final Element updated = bigMemory.get("1"); System.out.println("The value for key 1 is now " + updated.getObjectValue() + ". key 1 has been updated.");
以下のように、データを削除します。
bigMemory.remove("1"); System.out.println("Try to retrieve key 1."); final Element removed = bigMemory.get("1"); System.out.println("Value for key 1 is " + removed + ". Key 1 has been deleted.");
また、以下のように、一度に複数のエントリーを作成または更新することもできます。
Collection<Element> elements = new ArrayList<Element>(); elements.add(new Element("1", new Person("Jane Doe", 35, Person.Gender.FEMALE, "eck street", "San Mateo", "CA"))); elements.add(new Element("2", new Person("Marie Antoinette", 23, Person.Gender.FEMALE, "berry st", "Parsippany", "LA"))); elements.add(new Element("3", new Person("John Smith", 25, Person.Gender.MALE, "big wig", "Beverly Hills", "NJ"))); elements.add(new Element("4", new Person("Paul Dupont", 25, Person.Gender.MALE, "big wig", "Beverly Hills", "NJ"))); elements.add(new Element("5", new Person("Juliet Capulet", 25, Person.Gender.FEMALE, "big wig", "Beverly Hills", "NJ"))); bigMemory.putAll(elements);
以下のように、一度に複数のエントリーを読み込むこともできます。
final Map<Object, Element> elementsMap = bigMemory.getAll( Arrays.asList("1", "2", "3"));
以下のように、一度に複数のエントリーを削除することもできます。
52
bigMemory.removeAll(Arrays.asList("1", "2", "3"));
さらに、一度にすべてのエントリーを削除することもできます。
bigMemory.removeAll();
9.5 例 4：検索
BigMemory Max は、強力なインメモリ検索機能を搭載しています。このサンプルでは、インメモリ
データに対して基本的な検索をかける方法を示します。
まず、検索可能な属性で BigMemory Max のインスタンスを作成します。
Configuration managerConfig = new Configuration() .cache(new CacheConfiguration().name("MySearchableDataStore") .eternal(true) .maxBytesLocalHeap(512, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(32, MemoryUnit.GIGABYTES) .searchable(new Searchable() .searchAttribute(new SearchAttribute().name("age")) .searchAttribute(new SearchAttribute().name("gender") .expression("value.getGender()")) .searchAttribute(new SearchAttribute().name("state") .expression("value.getAddress().getState()")) .searchAttribute(new SearchAttribute().name("name") .className(NameAttributeExtractor.class.getName())) ) ); CacheManager manager = CacheManager.create(managerConfig); Ehcache bigMemory = manager.getEhcache("MySearchableDataStore");
次に、データを入力します。
bigMemory.put(new Element(1, new Person("Jane Doe", 35, Gender.FEMALE, "eck street", "San Mateo", "CA"))); bigMemory.put(new Element(2, new Person("Marie Antoinette", 23, Gender.FEMALE, "berry st", "Parsippany", "LA"))); bigMemory.put(new Element(3, new Person("John Smith", 25, Gender.MALE, "big wig", "Beverly Hills", "NJ"))); bigMemory.put(new Element(4, new Person("Paul Dupont", 45, Gender.MALE, "cool agent", "Madison", "WI")));
53
bigMemory.put(new Element(5, new Person("Juliet Capulet", 30, Gender.FEMALE, "dah man", "Bangladesh", "MN"))); for (int i = 6; i < 1000; i++) { bigMemory.put(new Element(i, new Person("Juliet Capulet" + i, 30, Person.Gender.MALE, "dah man", "Bangladesh", "NJ"))); }
検索属性を作成し、クエリを作ります。
Attribute<Integer> age = bigMemory.getSearchAttribute("age"); Attribute<Gender> gender = bigMemory.getSearchAttribute("gender"); Attribute<String> name = bigMemory.getSearchAttribute("name"); Attribute<String> state = bigMemory.getSearchAttribute("state"); Query query = bigMemory.createQuery(); query.includeKeys(); query.includeValues(); query.addCriteria(name.ilike("Jul*").and(gender.eq(Gender.FEMALE))) .addOrderBy(age, Direction.ASCENDING).maxResults(10);
クエリを実行して結果を見ます。
Results results = query.execute(); System.out.println(" Size: " + results.size()); System.out.println("----Results-----\n"); for (Result result : results.all()) { System.out.println("Maxt: Key[" + result.getKey() + "] Value class [" + result.getValue().getClass() + "] Value [" + result.getValue() + "]"); }
Aggregators を使って、クエリの結果を計算することもできます。以下の例は、データ内の人たち
の平均年齢を計算したものです。
Query averageAgeQuery = bigMemory.createQuery(); averageAgeQuery.includeAggregator(Aggregators.average(age)); System.out.println("Average age: " + averageAgeQuery.execute().all().iterator().next() .getAggregatorResults());
検索属性に基づくサブセットに限定して計算することもできます。以下の例は、30～40 歳の人を
対象としたデータセットから平均年齢を計算しています。
54
Query agesBetween = bigMemory.createQuery(); agesBetween.addCriteria(age.between(30, 40)); agesBetween.includeAggregator(Aggregators.average(age)); System.out.println("Average age between 30 and 40: " + agesBetween.execute().all().iterator().next() .getAggregatorResults());
Aggregators を使って、検索条件に合うエントリーを探すこともできます。以下の例は、ニュージ
ャージー在住をデータセットとし、その条件に合う人の数を計算しています。
Query newJerseyCountQuery = bigMemory.createQuery().addCriteria( state.eq("NJ")); newJerseyCountQuery.includeAggregator(Aggregators.count()); System.out.println("Count of people from NJ: " + newJerseyCountQuery.execute().all().iterator().next() .getAggregatorResults());
9.6 例 5：ノンストップ／リジョイン
ノンストップ機能は、クラスタから切断されたクライアントの処理を続行する機能です。ノンスト
ップのタイムアウト値に指定された時間で完了できない場合でも処理を続行します。その後、リジ
ョイン機能を使って、クライアントは Terracotta の構成情報ソースを識別します。それによって、
クラスタから切断されたり Terracotta サーバによってタイムアウトになったクライアントをクラス
タと再接続することができます。
この例では、BigMemory Max のノンストップとリジョインの機能を表しています。以下の構成情報
を読み込んだ後、提供されているスクリプトを使ってサーバを起動・稼働します。それからサーバ
を停止させ、ノンストップ機能が動いているかどうか確認します。サーバを再起動し、リジョイン
機能が作動しているか見ます。
Configuration managerConfig = new Configuration() .terracotta(new TerracottaClientConfiguration().url("localhost:9510").rejoin(true)) .cache(new CacheConfiguration().name("nonstop-sample") .persistence(new PersistenceConfiguration().strategy(DISTRIBUTED)) .maxBytesLocalHeap(128, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(1, MemoryUnit.GIGABYTES) .terracotta(new TerracottaConfiguration() .nonstop(new NonstopConfiguration() .immediateTimeout(false) .timeoutMillis(10000).enabled(true) )
55
)); CacheManager manager = CacheManager.create(managerConfig); Ehcache bigMemory = manager.getEhcache("nonstop-sample"); try { System.out.println("**** Put key 1 / value timDoe. ****"); final Person timDoe = new Person("Tim Doe", 35, Person.Gender.MALE, "eck street", "San Mateo", "CA"); bigMemory.put(new Element("1", timDoe)); System.out.println("**** Get key 1 / value timDoe. ****"); System.out.println(bigMemory.get("1")); waitForInput(); System.out .println("**** Now you have to kill the server using the stop-sample-server.bat on Windows or stop-sample-server.sh otherwise ****"); try { while (true) { bigMemory.get("1"); } } catch (NonStopCacheException e) { System.out .println("**** Server is unreachable - NonStopException received when trying to do a get on the server. NonStop is working ****"); } System.out .println("**** Now you have to restart the server using the start-sample-server.bat on Windows or start-sample-server.sh otherwise ****"); boolean serverStart = false; while (serverStart == false) { try { bigMemory.get("1"); //if server is unreachable, exception is thrown when doing the get serverStart = true; } catch (NonStopCacheException e) {
56
} } System.out .println("**** Server is reachable - No More NonStopException received when trying to do a get on the server. Rejoin is working ****"); } finally { if (manager != null) manager.shutdown(); }
9.7 例 6：Automatic Resource Controlの概要
Automatic Resource Control（ARC）は BigMemory Max の強力な機能です。この機能を使ってユー
ザーは、ヒープメモリとオフヒープメモリにデータをどれくらい格納するかを制御することができ
ます。
以下の XML 構成情報で、最大 512MB のヒープメモリと 32GB のオフヒープメモリを配分するよう、
ARC に指示します。この例では、512MB のヒープメモリを使い切った場合、ARC が自動的に最大
32GB のオフヒープメモリにデータを移します。物理的に利用可能な RAM 容量までオフヒープのメ
モリを使用できます。
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd" updateCheck="false" monitoring="autodetect" dynamicConfig="true" name="MyManager" maxBytesLocalHeap="512M" maxBytesLocalOffHeap="32G"> <defaultCache> </defaultCache> <cache name="BigMemory1"> </cache> <cache name="BigMemory2"> </cache> </ehcache>
57
また、データセットごとにリソースを配分することも可能です。以下の例は、８GB のオフヒープ
メモリを BigMemory１データセットに配分、24GB のオフヒープメモリを BigMemory２データセッ
トに配分しています。
<ehcache xmlns ... name="MyManager" maxBytesLocalHeap="512M" maxBytesLocalOffHeap="32G" maxBytesLocalDisk="128G"> <cache name="BigMemory1" maxBytesLocalOffHeap="8G"> </cache> <cache name="BigMemory2" maxBytesLocalOffHeap="24G"> </cache> </ehcache>
9.8 例 7：キャッシュとしてBigMemoryを利用
BigMemory Max は、強力なインメモリデータ管理ソリューションです。多数のアプリケーションの
中でも、BigMemory Max をキャッシュとして使うことで、低速または重いデータベースやリモート
データソースからのデータアクセスのスピードを高めることができます。この例では、BigMemory Max で利用できるキャッシュ機能を設定する方法を表しています。
以下のプログラム構成情報は、TTL（time-to-live）と TTI（time-to-idle）ポリシーをデータセット
に設定する方法を示しています。
Configuration managerConfiguration = new Configuration(); managerConfiguration.updateCheck(true) .monitoring(Configuration.Monitoring.AUTODETECT) .name("cacheManagerCompleteExample") .addCache( new CacheConfiguration() .name("sample-cache") .maxBytesLocalHeap(512, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(1, MemoryUnit.GIGABYTES) .timeToLiveSeconds(4)
58
.timeToIdleSeconds(2) ); CacheManager manager = CacheManager.create(managerConfiguration);
timeToLiveSeconds は、データセット内のエレメントの最長期間を指示するために設定します。最
大 TTL よりも古いエレメントは、データストアから返ってきません。これは、BigMemory を外部
データのキャッシュとして使う場合、またキャッシュの鮮度を保ちたい場合に役立ちます。
timeToIdleSeconds は、エレメントへの最近のアクセスからの最長時間を指示するために設定しま
す。最大 TTI よりもアイドル時間が長いエレメントは、データストアから返ってきません。これは、
BigMemory が外部データのキャッシュとして使われる場合、またアイドル状態のエントリーを削除
するためにエビクションアルゴリズムにバイアスをかけたい場合に役立ちます。
TTL も TTI も設定されていない場合（または０と設定されている場合）、データは明示的に削除さ
れるまで BigMemory 内に残ります。
10 構成の概要
10.1 はじめに
BigMemory Max の構成情報の設定方法には、XML 構成情報ファイルを使用して設定する方法と、
プログラムからクラスコンストラクタを呼び出して設定する方法があります。ランタイムの状況に
応じてアプリケーションに適切な構成情報を設定できるのであれば、どちらの方法で構成情報を設
定しても構いません。
ランタイムから構成を分離できるプロジェクトの場合、構成情報ファイルを使用した設定には以下
のような利点があります。
• 配備時のキャッシュ構成の変更が簡単になります。
• 構成情報をファイルで管理できるため、一元管理しやすくなります。
• アプリケーションコードのライフサイクルから構成のライフサイクルを分離できます。
• 構成情報の問題を起動時にチェックすることで、予期せぬランタイムエラーを防止します。
• 構成ファイルが指定されなかった場合、ランタイムは常にデフォルト構成を読み込みます。
このドキュメントでは、構成情報ファイルで使用するXMLの記述方法を重点的に説明します。プロ
グラムによる構成設定は、このドキュメントのサンプルと Javadocsを参照してください。
59
10.2 XML構成
BigMemory Maxは、ユーザーとの情報交換にEhcacheを使用します。また、BigMemory Maxの構成
情報は、Ehcache構成システムを使って設定します。EhcacheはJavaクラスパス最上層から構成情報
ファイル CacheManagerのコンストラクタを使用すると、異なるパスやファイル名のXML構成ファ
イルを指定できます。
リソースの競合を避けるため、作成する CacheManager インスタンスごとに、XML で記載した構成
情報ファイルが必要です。例えば、ディレクトリパスとリスナーポートには独自の値が必要です。
BigMemory Max は競合を解決するための検索を行い、競合を検出した場合は、ユーザーが複数のキ
ャッシュマネージャーに対して別々の構成を使用するよう警告します。
BigMemory Maxのリリースパッケージには、サンプルのehcache.xmlが同梱されています。各構成要
素の設定方法は、このサンプル内のコメントを参照してください。また、このファイル
は http://ehcache.org/ehcache.xmlからもダウンロードできます。
10.2.1 ehcache.xsd Ehcache構成ファイルはEhcache XMLスキーマのehcache.xsd（http://ehcache.org/ehcache.xsdからダ
ウンロード可能）に準拠してください。
ehcache.xsd は、BigMemory Max にも同梱されています。
10.2.2 ehcache-failsafe.xml CacheManager のデフォルトコンストラクタまたはファクトリメソッドを呼び出すと、Ehcache は
クラスパス最上層で ehcache.xml というファイルを探します。ファイルが見つからなかった場合、
Ehcache はクラスパス内から ehcache-failsafe.xml を探します。ehcache-failsafe.xml ファイルは
Ehcache JAR にパッケージされているため、必ず見つかります。
ehcache-failsafe.xml には、最小限の構成情報がデフォルト値として定義されています。このため、
ユーザーが独自の ehcache.xml を作成しなくとも、作業を開始できます。
ただし、ehcache-failsafe.xml を使用すると、Ehcache は、正式なユーザー定義の構成情報を設定す
るよう警告します。各要素と属性の意味は、ehcache.xml のセクションを参照してください。
<ehcache> <diskStore path="java.io.tmpdir"/> <defaultCache maxEntriesLocalHeap="10000" eternal="false" timeToIdleSeconds="120" timeToLiveSeconds="120" maxEntriesLocalDisk="10000000" diskExpiryThreadIntervalSeconds="120"
60
memoryStoreEvictionPolicy="LRU"> <persistence strategy="localTempSwap"/> </defaultCache> </ehcache>
10.2.3 デフォルトキャッシュについて 構成情報が定義されていないキャッシュには、defaultCache の構成情報が適用されます。ehcache-failsafe.xml には、defaultCache のデフォルト値が定義されています。この定義は、BigMemory Maxの構成情報ファイルにも追加できます。
構成情報の defaultCache は必須項目ではありません。ただし、プログラムで名前付きキャッシュを
作成するときに defaultCache を読み込まないと、エラーが発生します。
10.3 キャッシュ構成を動的に変更する
BigMemory Max の構成情報の多くは、一度起動すると変更できません。しかし、一部のキャッシュ
構成パラメーターは、実行時に動的に変更できます。実行時に変更可能なパラメーターは以下のと
おりです。
• 有効期限の設定
– timeToLive：キャッシュが要素を保持し続ける時間の最大値を、「秒」単位で指定しま
す。要素に対するアクセスの状況（回数や頻度）は問いません。指定時間が経過する
と要素は期限切れになり、キャッシュはこの要素を返さなくなります。デフォルト値
は 0 です。これは TTL エビクションが発生しない（有効期限なし）という意味です。
– timeToIdle：キャッシュが要素を保持し続ける時間の最大値を、「秒」単位で指定しま
す。アクセスされていない要素が対象です。指定した時間が経過すると要素は期限切
れとなり、キャッシュはこの要素を返さなくなくなります。デフォルト値は 0 です。
これは TTI エビクションが発生しない（有効期限なし）という意味です。
eternal 属性を「true」に設定すると、期限切れが発生しません。timeToLive と timeToIdle の
値は無視されます。
• ローカルでのサイズ指定属性
– maxEntriesLocalHeap
– maxBytesLocalHeap
– maxEntriesLocalDisk
– maxBytesLocalDisk.
• メモリストアにおけるエビクションのポリシー
61
• CacheEventListeners の動的な追加と削除
以下の例で、実行中のキャッシュの構成情報を動的に変更する方法を紹介します。
Cache cache = manager.getCache("sampleCache"); CacheConfiguration config = cache.getCacheConfiguration(); config.setTimeToIdleSeconds(60); config.setTimeToLiveSeconds(120); config.setmaxEntriesLocalHeap(10000); config.setmaxEntriesLocalDisk(1000000);
キャッシュの構成情報をそれ以上変更したくない場合は、動的な変更を禁止します。
Cache cache = manager.getCache("sampleCache"); cache.disableDynamicFeatures();
ehcache.xml で、<ehcache>要素の dynamicConfig 属性を「false」に設定すると、動的な構成情報の
変更を無効にできます。
10.3.1 分散BigMemory Max構成を動的に変更する スタンドアロンの BigMemory 同様、分散 BigMemory 構成の変更には、
cache.getCacheConfiguration()で設定したメソッドへのアクセスが必要です。
Terracotta クラスタの一般的な構成オプションの動的変更について、以下の表に示します。表にあ
るスコープ列は構成設定が影響する場所を示します。以下の値の一つを入力します。
• Client：キャッシュマネージャーを実行する Terracotta クライアントです。
• TSA：クラスタの Terracotta サーバアレイです。
• BOTH： TSA とクライアント両方を意味します。
スコープが「BOTH」を含む構成オプションは分散されるため、すべてのクライアントのキャッシ
ュに影響を与えます。
構成オプション 動的 スコープ 説明
Cache name 不可 TSA
Nonstop 不可 Client 高可用性を有効化します。
Timeout 可能 Client ノンストップ機能用です。
Timeout Behavior 可能 Client ノンストップ機能用です。
Immediate Timeout When Disconnected
可能 Client ノンストップ機能用です。
62
Time to Idle 可能 BOTH
Time to Live 可能 BOTH
Maximum Entries or Bytes in Local Stores
可能 Client 「ARC」の一部であるこれらのサイズ指定属性はキャ
ッシュマネージャーによってプールされることがあり
ます。したがって変更には制限が伴います。
Maximum Entries in Cache
可能 TSA
Persistence Strategy 対象
外 対象外
Disk Expiry Thread Interval
対象
外 対象外
Disk Spool Buffer Size
対象
外 対象外
Maximum Off-heap 対象
外 対象外 TSA に割り当てられるオフヒープメモリの最大サイ
ズ。
Eternal 可能 BOTH
Clear on Flush 不可 Client
Copy on Read 不可 Client
Copy on Write 不可 Client
Memory Store Eviction Policy
不可 Client
Statistics 可能 Client キャッシュ統計情報。cache.setStatistics(boolean)メソ
ッドで動的に変更します。
Logging 不可 Client Ehcache と Terracotta におけるログの記録は構成情報
で指定します。「クラスタイベント」は動的に設定す
ることができます。
Consistency 不可 Client 「一括モード」への切り替えが可能です。
Synchronous Writes 不可 Client
動的でない「L1」の変更を適用する場合、これら既存のキャッシュを削除し、それから削除したキ
ャッシュと同じ名前の新しいキャッシュを(同じキャッシュマネージャーに）追加します。追加す
るキャッシュには新しい構成情報が含まれています。すべてのキャッシュ名が以前の構成情報と同
じである更新済み構成情報を使ってキャッシュマネージャーを再起動しても、同様に動的でない
「L1」の変更を適用できます。
63
10.4 参照渡しと値渡し
通常、ストア内のデータに対して get()を行うと、「データへの参照」が戻り値になります。した
がって、取得したデータの値を変更すると、ストアの内容も同時に変わります。「データへの参照」
ではなく「値のコピー」をアプリケーションに返したい場合は、構成情報を変更します。これによ
り、データへの参照ではなく値のコピーが戻り値になります。戻り値を「値のコピー」にすれば、
取得した値を変更しても、データストア内の値は影響を受けません。
この設定は、構成情報ファイル内の<cache>要素と<defaultCache>要素の、copyOnRead 属性と
copyOnWrite 属性で変更します。あるいは、以下のプログラムでも変更できます。
CacheConfiguration config = new CacheConfiguration("copyCache", 1000).copyOnRead(true).copyOnWrite(true); Cache copyCache = new Cache(config);
これらの構成情報のデフォルト値は「false」です。
put()あるいは get()のような処理で、一連の要素への参照ではなく、要素の値のコピーを利用する
場合は、copyStrategy（コピーストラテジー）を使用します。デフォルト実装では、シリアル化に
より要素をコピーします。独自の処理を実装した net.sf.ehcache.store.compound.CopyStrategy を使
用する場合は、<copyStrategy>要素を以下のように設定します。
<cache name="copyCache" maxEntriesLocalHeap="10" eternal="false" timeToIdleSeconds="5" timeToLiveSeconds="10" copyOnRead="true" copyOnWrite="true"> <copyStrategy class="com.company.ehcache.MyCopyStrategy"/> </cache>
各キャッシュは、それぞれ 1 つの CopyStrategy インスタンスを使用します。したがって、
CopyStrategy.copy(T)の実装では、「T」がスレッドセーフであることを保証してください。
プログラムからコピーストラテジーを追加する方法の例を以下に示します。
CacheConfiguration cacheConfiguration = new CacheConfiguration("copyCache", 10); CopyStrategyConfiguration copyStrategyConfiguration = new CopyStrategyConfiguration(); copyStrategyConfiguration.setClass("com.company.ehcache.MyCopyStrategy"); cacheConfiguration.addCopyStrategy(copyStrategyConfiguration);
64
10.5 特殊なシステムプロパティ
10.5.1 net.sf.ehcache.disabled このシステムプロパティを true に設定（Java コマンドラインから、java -Dnet.sf.ehcache.disabled=true を実行）すると、ehcache のキャッシュを無効にできます。無効にす
ると、キャッシュに要素は追加されません。put()などを実行しても、データは破棄されます。メッ
セージなどの通知はありません。
10.5.2 net.sf.ehcache.use.classic.lru エビクション・ポリシーに LRU を選択した場合、このシステムプロパティに true を設定し、古い
バージョンの LruMemoryStore の実装を利用してください。プロパティを設定するには、Java コマ
ンドラインから、java -Dnet.sf.ehcache.use.classic.lru=true を実行します。これにより、移行しやす
くなります。
10.6 構成設定の詳細情報
項目 内容
「Terracotta を使っ
たクラスタ化」 BigMemory Max を使用することで、単一のスタンドアロンノードまたは
Terracotta サーバのインメモリデータを管理できます。このページでは、
Terracotta クラスタまたはサーバアレイで分散 BigMemory を使うのに必要
な構成について説明します。
「ストレージ層のサ
イズ指定」 BigMemory Max のチューニングでは、ストレージ層に対する適切なサイズ
の見積もりが不可欠です。BigMemory Max は、ストレージ層のサイズを簡
単に定義できるよう、キャッシュ構成情報でサイズを定義するための属性を
数多く提供しています。このページでは、メモリの動的割り当てと自動負荷
分散による、ストレージ層のサイズのチューニング方法を紹介します。
「有効期限切れ、ピ
ンニング、エビクシ
ョン」
インメモリデータを管理するには、各ストレージ層におけるデータの有効期
限の管理が非常に重要です。このページでは、BigMemory Max と Terracottaサーバアレイにおけるデータの有効期限の管理を説明します。また、ARC（Automatic Resource Control）のピンニング機能も合わせて説明します。
「高速再起動」 このページでは、ローカルディスクをストレージ層として使用する方法、そ
の永続化、および高速再起動について説明します。高速再起動は、エンター
プライズレベルの障害回復を提供する機能です。システム障害からの高速回
復機能、アプリケーションノードのデータセットをディスクにミラー化する
ホットミラー機能、そして読み取り／書き込みでインメモリのスピードを確
保する保存処理機能が含まれます。
65
11 ストレージ層
11.1 はじめに
BigMemory Max には、以下の 3 種類のストレージ層があります。
• メモリストア：ヒープメモリ上に確保される領域です。オフヒープよりもアクセス頻度の高い
データを記録します。Java による GC（ガーベジコレクション）の対象です。注意: ディスク層
を利用できるのは、BigMemory Max のローカル（つまりスタンドアロン）インスタンスのみ
です。BigMemory Max を分散構成にした場合は、Terracotta サーバまたはサーバアレイが、こ
のストレージ層を提供します。(詳細は「BigMemory Max 分散構成設定ガイド」を参照してく
ださい。)
• オフヒープストア：ヒープ外のメモリ上に確保される領域です。搭載 RAM（メモリ）に合わ
せて容量を拡張できます。Java による GC の対象外です。シリアル化されたデータだけを記録
できます。メモリストアでオーバーフローが発生した場合の領域として確保されています。
• ディスクストア：インメモリデータをバックアップし、他のストレージ層へのオーバーフロー
を可能にします。シリアル化されたデータだけを記録できます。
このドキュメントでは、スタンドアローンのストレージ層の定義と、各ストレージ層に適した要素
の種類と構成情報の詳細を詳しく解説します。
本番稼働の前に、BigMemory Max のデータ量のテストをすることを強く推奨します。テストでは、
実際の業務で使用されるデータ量を見積もり、各ストレージ階層にその量のデータを投入します。
階層のサイズ指定の詳細は、「ストレージ階層のサイズ指定」を参照してください。
11.2 メモリストア
メモリストアはヒープメモリ上の領域で、常に利用可能です。最大のパフォーマンスを得るには、
GC（ガーベジコレクション）によるパフォーマンス低下が生じない範囲で最大の領域を割り当てま
す。そして、ヒープに格納できないデータは、GC の影響を受けない「オフヒープストア」に格納
します。
メモリストアには以下の特徴があります。
• シリアル化可能かどうかを問わず、すべてのデータの記録が可能です
• すべてのストレージ階層の中で最も高速です
• 多重スレッドの使用時にもスレッドセーフを保証できます
• JDK LinkedHashMap によってサポートされています
66
11.3 メモリストアの構成設定
メモリストアは、最上位に位置する最も高速なデータ層です。BigMemory Max は、アクセス頻度の
高いデータを、この階層に記録します。このストレージ層は、特別な設定をしなくとも有効化され
ています。サイズは、Java のヒープサイズによって決まります。ヒープ領域に位置するため、Javaによる GC（ガーベジコレクション）の対象となります。
11.3.1 メモリアストアにおけるメモリ使用、スプール、有効期限の指定 キャッシュの構成情報を設定する際は、インメモリのサイズの最大値を要素（Element）の数で指
定します。
キャッシュ要素の追加によって最大サイズを超過した場合、オーバーフローが無効であれば、既存
の要素の 1 つを削除します。オーバーフローが有効であれば、各要素を評価し、既存の要素の 1 つ
を別のストレージ層に移動します（これをスプールと呼びます）。オーバーフローは
overflowToOffHeap で設定します。ディスクストアの場合は<persistence>で設定します。
オーバーフローを有効化すると、有効期限が確認されるようになります。要素が期限切れの場合、
その要素は削除されます。期限切れでない場合に限り、その要素がスプールされます。キャッシュ
要素のエビクションの仕組みは、構成情報ファイルの MemoryStoreEvictionPolicy 属性の値によっ
て決まります。指定できる値は、LRU（デフォルト）、LFU、FIFO の 3 種類です。
• LRU（Least Recently Used)：デフォルト値です。put によるキャッシュ要素の登録や、get によるキャッシュ要素の取得が発生すると、その要素の最終利用日時を示すタイムスタンプが更
新されます。
• LFU（Least Frequently Used）： get によるキャッシュ要素へのアクセスが発生すると、ヒッ
トした要素にアクセス回数が記録されます。put による新しいキャッシュ要素の登録によって
メモリストアの上限に達すると、ヒット回数の少ないキャッシュ要素の 1 つがエビクションに
よって破棄されます。
• FIFO（First In First Out）：キャッシュ要素が登録された順番で破棄されます。put による新
しいキャッシュ要素の登録によってメモリストアの上限に達すると、「最初に登録された要素
（First-In）」が、「エビクションによる破棄の最初の項目（First-Out）」になります。
なお、putQuiet メソッドと getQuiet メソッドは、最終利用日時のタイムスタンプを更新せずにキャ
ッシュ要素を登録・取得します。
キャッシュ要素に対して get または getQuiet を実行すると、有効期限の確認が行われます。期限切
れの場合、要素は破棄され、Null が返ります。なお、キャッシュ内には常に期限切れの要素が残存
します。アプリケーションのメモリサイズを指定するときは、各キャッシュの最大サイズを常に考
慮してください。
67
calculateInMemorySize()メソッドは、メモリストアのサイズを見積もりに利用できます。戻り値
は、シリアル化済みキャッシュのサイズ（単位はバイト）です。大まかなサイズの見積もりに役立
ちます。ただし、このメソッドはパフォーマンスに悪影響を与えます。本番業務では使用しないで
ください。
ヒント：キャッシュサイズの計算
ほかに、有効期限を処理するスレッドを利用する方法もあります。メモリの節約と、ロック時間の
短縮や CPU 負荷の低減は、両立の難しい問題です。このスレッドは、ロック時間の短縮と CPU 負
荷の低減を優先させています。メモリの使用量に不安がある場合は、インメモリのキャッシュサイ
ズを縮小します。詳細は「ストレージ層のサイズ指定」を参照してください。
11.4 オフヒープストア
オフヒープストアは、オブジェクトヒープの外側まで拡張したメモリ上のストア領域です。この領
域は、Java による GC の影響を受けません。オフヒープストアのサイズは、利用可能な RAM の領
域の上限まで拡張できます。
オフヒープのデータはバイト単位で記録されます。したがって、オフヒープストアに記録できるの
は Serializable の（つまりシリアル化できる）データだけです。シリアル化できないデータがオー
バーフローによって OffHeapMemoryStore に届くと、それらのデータは削除され、警告レベルのロ
グメッセージが記録されます。
オフヒープの領域に対する put や get を実行すると、シリアル化または非シリアル化が発生します。
このため、論理的なアクセス速度はメモリストアよりも遅くなります。しかし、ヒープに大きな領
域を確保することで発生する GC に比べれば、このアクセス速度の差は無視できる程度の差です。
11.4.1 JVMへのダイレクトメモリの割り当て オフヒープストアは、JVM のダイレクトメモリ領域を使用します。JVM プロパティの
MaxDirectMemorySize を使い、オフヒープストアに十分なダイレクトメモリを割り当ててください。
例えば、JVM に 2GB のダイレクトメモリを割り当てるには、以下を行ないます。
java -XX:MaxDirectMemorySize=2G ...
ダイレクトメモリは他のプロセスと共有される可能性があります。したがって、ダイレクトメモリ
にはオフヒープストアに割り当てるサイズに、少なくとも 256MB（できれば 1GB）以上を加えた
サイズを割り当ててください。
ダイレクトメモリの割り当てる際は、以下の注意が必要です。
• オフヒープ設定時に「-XX:MaxDirectMemorySize」でダイレクトメモリスペースを割り当てな
かった場合、ダイレクトメモリスペースのサイズには使用中の JVM のデフォルト値が適用さ
68
れます。Oracle HotSpot のデフォルト値は、最大ヒープ容量（-Xmx 値）と同じサイズです。
しかし、以前のバージョンでは、異なる値が設定されている可能性があります。
• MaxDirectMemorySize は、ローカルノードの起動環境に追加してください。
• ダイレクトメモリは Java プロセスのヒープの一部です。「-Xmx」により割り当てられるオブ
ジェクトヒープとは別のものです。MaxDirectMemorySize には、物理 RAM サイズ以上の値を
指定できません。ほかのメモリ要件も考慮し、利用可能なメモリサイズよりも小さな値を指定
してください。
• 利用可能なシステムメモリと割り当てたオフヒープメモリに収まるサイズを、ダイレクトメモ
リとして割り当ててください。
• 使用できるダイレクトメモリの最大サイズは、プロセスデータモデル（32 ビットまたは 64 ビ
ット）、関連する OS の制約、システム上の利用可能な仮想メモリ、および物理メモリ量に左
右されます。
32-bit 版 JVM におけるオフヒープストアの使用
確保できるオフヒープの量は、アドレス空間のサイズに制限されます。64-bit システムではハード
ウェアや OS が取り扱える分だけメモリを使用できます。しかし、32-bit システムでは効率的に管
理できるメモリ量は厳しく制限されます。
32-bit のプロセスモデルの場合、32-bitOS の多くに 2GB の制限がありますが、プロセスの仮想アド
レスの最大容量は通常 4GB です。Java で利用可能なヒープの最大容量は、さらに小さくなります。
これは、OS 制限、マシン上の他の処理（特定 API が使用する mmap 操作など）、共有ライブラリ
や他のコードを読み込むための JVM 要件などの影響です。-Xmx の設定後に残存する容量より大き
なオフヒープメモリを割り当てない、というルールを憶えておくと役に立ちます。例えば、-Xmx3G という設定を行なった場合、オフヒープは 1GB より小さくします。このルールに従わなか
ったとしても、起動時に OutOfMemoryError が発生するとは限りません。しかし、JVM 使用中に
OutOfMemoryError が発生する可能性は十分にあります。
Java の GC による問題が 32-bit 版 JVM に影響を与えている場合は、オフヒープストアが役に立ちま
す。しかし、以下の点に注意が必要です。
• 4GB のアドレス空間に、すべてを格納する必要があります。ヒープに 2GB を割り当てた（つ
まり-Xmx2g を指定した）場合、オフヒープの最大サイズは 2GB になります。
• 4GB のアドレス空間の一部は、JVM プロセスのコードや共有ライブラリ、さらには OS のオー
バーヘッドによって占有されます。
• 「-Xmx」で 3GB のヒープを割り当て、さらに 2047MB をオフヒープメモリに割り当てても、
起動時にエラーが発生するとは限りません。しかし、ヒープの拡張時に OutOfMemoryError が
発生する可能性が高くなります。
69
• 2047MB のオフヒープメモリで「-Xms3G」と「-Xmx3G」の両方を使用しても仮想マシンは起
動します。しかしオフヒープストアがオフヒープバッファーを割り当てる処理で問題が発生し
ます。
• Sun 1.5 JVM の java.util.zip.ZipFile のような API は、「mmap」でファイルをメモリに展開する
可能性があります。この場合も、プロセス領域が枯渇して OutOfMemoryError が発生する可能
性があります。
11.5 オフヒープストアの構成設定
オフヒープストアの構成情報を設定すると、メモリストアに入りきらない項目がオフヒープストア
へ記録されるようになります。オフヒープストアの構成情報は、XML ファイルまたはプログラムか
ら設定します。いずれの方法の場合も、オフヒープストアはキャッシュごとに設定する必要があり
ます。
11.5.1 構成情報を利用する定義 以下に示す XML は、10,000（maxEntriesLocalHeap）のインヒープのキャッシュ要素に加え、オー
バーフローに備えて 1GB のオフヒープ領域のキャッシュを作成するための構成情報の例です。
<ehcache updateCheck="false" monitoring="off" dynamicConfig="false"> <defaultCache maxEntriesLocalHeap="10000" eternal="true" memoryStoreEvictionPolicy="LRU" statistics="false" /> <cache name="sample-offheap-cache" maxEntriesLocalHeap="10000" eternal="true" memoryStoreEvictionPolicy="LRU" overflowToOffHeap="true" maxBytesLocalOffHeap="1G"/> </ehcache>
ここで設定されている構成情報オプションは以下のとおりです。
overflowToOffHeap
値には「true」か「false」を指定します。「true」を指定すると、キャッシュはオフヒープのメモ
リ領域を活用してパフォーマンスの向上を図ります。オフヒープ領域は、Java による GC（ガーベ
ジコレクション）の対象外です。領域の最大サイズは Java のプロパティ「MaxDirectMemorySize」で設定します。デフォルト値は「false」です。
maxBytesLocalOffHeap
70
利用可能なオフヒープ領域のサイズを指定します。overflowToOffHeap が「true」の場合のみ有効
です。割り当て可能な最小サイズは 1MB です。サイズの上限はありません。
データストアのサイズ指定方法の詳細は、「ストレージ層のサイズ指定」を参照してください。
パフォーマンス低下を避けるため、オフヒープストア使用時は、maxEntriesLocalHeap に 100 また
はそれ以上の値（要素数）を設定してください。これより小さい値を maxEntriesLocalHeap に設定
すると、警告がログに記録されます。
注意：オフヒープストア使用時のヒープの構成設定
11.5.2 プログラムによる構成設定 前述の構成情報による設定と同等のキャッシュをプログラムで作成する場合は、以下のように処理
します。
public Cache createOffHeapCache() { CacheConfiguration config = new CacheConfiguration("sample-offheap-cache", 10000) .overflowToOffHeap(true).maxBytesLocalOffHeap("1G"); Cache cache = new Cache(config); manager.addCache(cache); return cache; }
11.6 ディスクストア
ディスクストアは、スレッドセーフなディスクへのスプールを提供します。記録できる容量が増加
するほか、システム再起動の際にデータを永続化します。
注意: ディスク層を利用できるのは、BigMemory Max のローカル（つまりスタンドアロン）インス
タンスのみです。BigMemory Max を分散構成にした場合、ディスク層ではなく、Terracotta サーバ
またはサーバアレイを使用します。(詳細は「BigMemory Max 分散構成設定ガイド」を参照してく
ださい。)
このセクションでは、ローカルディスクの利用について説明します。追加の情報は、「高速再起動」
のページも参照してください。
11.6.1 シリアライズ ディスクストアに記録できるのは、シリアル化可能（Serializable）なデータだけです。ディスクの
書き込みと読み取りでは、ObjectInputStreamと、Javaのシリアル化の仕組みを使用します。オーバ
71
ーフローによるディスクへの書き込みが発生した場合、シリアル化できないデータは破棄され、
NotSerializableExceptionがスローされます。
シリアル化の処理速度は、シリアル化の対象となるオブジェクトのサイズとタイプによって異なり
ます。以下が確認されています。
• 文字列の配列によるマッピングで構成された Java オブジェクトをシリアル化するテストでは、
シリアル化済みデータのサイズが 349,225 バイト、シリアル化に要した時間が 126ms でした。
• バイト配列（byte[]）をシリアル化するテストでは、シリアル化済みデータのサイズが
310,232 バイト、シリアル化に要した時間が 7ms でした。
このテスト結果によれば、バイト配列のシリアル化のほうが、ディスクストアのパフォーマンスは
高い（約 20 倍）ことがわかります。
11.7 ディスクストアの構成設定
ディスクストアの構成設定は各キャッシュマネージャーに対して行ないます。ディスクストアがキ
ャッシュに必要であるにもかかわらず設定されていない場合は、デフォルトのディレクトリが使用
されます。また、ディスクストアのパスを明示的に設定するよう促す警告メッセージがログに記録
されます。
ただし、ディスクストアの構成設定は省略可能です。例えば、キャッシュがメモリとオフヒープス
トアのみ使用する場合、ディスクストアの構成設定は必要ありません。構成設定が簡易化され、よ
り少ないスレッドが使用されることになります。また、複数のキャッシュマネージャーを使用して
いる場合、複数のディスクストアのパスを設定する必要もありません。
11.7.1 ディスクのストレージオプション ディスクストアには、以下の 2 種類のオプションを利用できます。
• テンポラリーストア（"localTempSwap"）
• 永続ストア（"localRestartable"）
これらのオプションの詳細については、下のセクションを参照してください。
localTempSwap
"localTempSwap"永続化方式を使うと、BigMemory 運用中にローカルディスクの使用が可能となり
ます。つまり、余分なストレージ層を利用できることになります。この場合のディスク領域は一時
的な領域です。再起動時にクリアされます。
ディスクストアのパスを省略すると、デフォルトパスが使用されます。このデフォルトパス名は、
他のキャッシュマネージャーとの競合を避けるため、自動的に作成されます。
72
"localTempSwap"のディスクストアは、起動時に各キャッシュに"<cache_name>.data"というデータ
ファイルを作成します。
localRestartable
このオプションは、すべてのインメモリデータのためのリスタータブルストアを実装します。再起
動後、データセットは、自動的にディスクからインメモリストアに読み込まれます。
必要なディスクファイルを作成するディレクトリのパスは、Ehcache の構成情報の<diskStore>子要
素で設定します。リスタータブルストアの使用には、一意かつ明示的に指定したパスが必要です。
11.7.2 ディスクストアの構成情報 ファイルは、<diskStore>構成要素で指定したディレクトリで作成されます。<diskStore>には pathという一つの属性があります。
<diskStore path="/path/to/store/data"/>
「path」属性の有効な値には、有効なファイルシステムのパスを指定します。例えば、UNIX では、
以下のように指定します。
/home/application/cache
また、以下のシステムプロパティも有効です。
• user.home：ユーザーのホームディレクトリです。
• user.dir：ユーザーの現在の作業ディレクトリです。
• java.io.tmpdir：デフォルトの一時ファイルのパスです。
• ehcache.disk.store.dir：通常、コマンドラインで指定するシステムプロパティです。例：java -Dehcache.disk.store.dir=/u01/myapp/diskdir
以下のように、サブディレクトリをディレクトリの下に指定することもできます。
user.dir/one
ディスクストアのパスをプログラムを使って指定する場合は、以下のように指定します。
DiskStoreConfiguration diskStoreConfiguration = new DiskStoreConfiguration(); diskStoreConfiguration.setPath("/my/path/dir"); // Already created a configuration object ... configuration.addDiskStore(diskStoreConfiguration);
73
CacheManager mgr = new CacheManager(configuration);
注意：キャッシュマネージャーのディスクストアのパスは、一度構成設定すると変更できなくなり
ます。変更した場合、新しいパスを有効にするには、そのキャッシュマネージャーをリサイクルす
る必要があります。
11.7.3 ディスクストアの有効期限とエビクション ディスク領域を確保するため、期限切れ要素はエビクションによって破棄されます。また、期限切
れ要素はインメモリのインデックスからも削除されます。
期限切れ要素の削除には、各キャッシュのスレッドを使用します。有効期限スレッドの実行インタ
ーバルは、diskExpiryThreadIntervalSeconds 属性で設定します。この属性は省略可能です。
警告：diskExpiryThreadIntervalSeconds に小さな値を指定すると、ディスクストアは過度にロック
され、CPU 使用率が高くなります。デフォルト値は 120 秒です。
キャッシュのディスクストア容量を制限している場合は、その上限を超えると要素がディスクスト
アから破棄されます。このようなエビクションには LFU アルゴリズムを使用します。LFU アルゴリ
ズムの設定や変更はできません。
注意：永続化方式"localTempSwap"では、ディスク層のサイズを指定できます。サイズを指定する
には、Cache または CacheManager のレベルに maxEntriesLocalDisk または maxBytesLocalDisk を設
定します。
11.7.4 ディスクストアの無効化 ディスクストアのパスの作成を無効化するには、「ehcache.xml」で diskStore 要素をコメントアウ
トします。
デフォルトの Ehcache 構成情報ファイルの「ehcache-failsafe.xml」ではディスクストアを使用する
設定になっています。ディスクストアの使用を無効化するには、「ehcache.xml」で diskStore 要素
をコメントアウトしてカスタマイズしてください。
11.8 構成情報のサンプル
ここでは、8GB のマシンメモリを複数のストレージ領域に割り当てる方法を紹介します。このサン
プルでは、700 万個のアイテム（各アイテムのサイズは 1kb）のキャッシュに対し、7GB のデータ
セットがあると仮定します。
アプリケーションの応答時間の差（または GC の影響で生じる遅延時間の差）を最小に抑えたい場
合は、すべてのキャッシュをオフヒープにするという選択肢もあります。ここでは、アプリケーシ
ョンのキャッシュ以外の用途に 1GB のヒープ領域が必要だと仮定します。この場合、Java の構成
は以下のように設定します。
74
java -Xms1G -Xmx1G -XX:maxDirectMemorySize=7G
さらに、Ehcache の構成情報を以下のように設定します。
<cache maxEntriesLocalHeap=100 overflowToOffHeap="true" maxBytesLocalOffHeap="6G" ... />
サーバのコミュニケーションレイヤーの要件を満たすため、maxDirectMemorySize の値には、
maxBytesLocalOffHeap よりも大きな値を指定してください。どれくら大きな値を指定すべきかは、
maxBytesLocalOffHeap の値によって決まります。最低でも maxBytesLocalOffHeap より 256MB 以
上大きな値を maxDirectMemorySize に指定してください。1GB 以上大きい値を指定すれば、間違
いなく十分なサイズになります。サーバは、サーバ自身が必要なメモリサイズだけを使用します。
残りは空き領域になります。
注意：ダイレクトメモリとオフヒープメモリの割り当て
データによるアプリケーション応答時間の差異を抑え、アクセス頻度の高いデータのレスポンス速
度も最大限に上げたい場合は、オンヒープとオフヒープを組み合わせて利用すると良いでしょう。
アクセス頻度の高いデータはオンヒープに記録し、残りのデータはオフヒープに記録します。例え
ば、合計 7GB の項目のうち、アクセス頻度の高い項目の数が 100 万（1M）で、それらの合計サイ
ズが 1GB だったとします。この場合、Java の構成は以下のように設定します。
java -Xms2G -Xmx2G -XX:maxDirectMemorySize=6G
さらに、Ehcache の構成情報を以下のように設定します。
<cache maxEntriesLocalHeap=1M overflowToOffHeap="true" maxBytesLocalOffHeap="5G" ...>
このように、アクセス頻度の低いデータをオフヒープに記録しておけば、ローカルディスクに用意
したキャッシュ領域から取り出す方法に比べて 20 倍、データベースから取り出す方法に比べて
100 倍も高速です。
データ全体のサイズが小さい場合や GC による応答遅延の心配がない場合は、以下のように設定す
れば、データ全体がオンヒープに記録されます。
75
<cache maxEntriesLocalHeap=1M overflowToOffHeap="false" ...>
高速な応答が不要な場合、以下のように設定すれば、ディスクが利用できます。
<cache maxEntriesLocalHeap=1M <persistence strategy="localTempSwap"/> ...>
12 ストレージ層のサイズ指定
12.1 はじめに
BigMemory Max のチューニングでは、ストレージ層に対する適切なサイズの見積もりが不可欠です。
BigMemory Max は、各ストレージ階層のサイズを属性で簡単に定義できるよう、さまざまな方法を
提供します。メモリやディスクといったリソースの利用をチューニングするには、これらのサイズ
属性を使用します。
12.2 属性によるサイズ指定
BigMemory Max の Ehcache API で使用するサイズ指定属性について、以下の表で説明します。
ストレー
ジ層 属性 キャッシュマネージャ
ーレベルのプール可否 内容
メモリス
トア（ヒ
ープ）
maxEntriesLocalHeap maxBytesLocalHeap
maxBytesLocalHeap の
み ローカルヒープのメモリに記録する
データの合計エントリー数、または
データの合計サイズ。キャッシュマ
ネージャーに対して設定する場合
（maxBytesLocalHeap のみ）は、そ
のキャッシュマネージャーのデータ
プールのサイズ。この値は、キャッ
シュマネージャーに対して、あるい
は個々のキャッシュに対して設定し
ます。
オフヒー
プストア maxBytesLocalOffHeap 可能 オフヒープのメモリに記録するデー
タの合計サイズ。キャッシュマネー
ジャーに対して設定する場合は、そ
のキャッシュマネージャーのデータ
プールのサイズ。
ディスク maxEntriesLocalDisk maxBytesLocalDisk の ローカルディスクに記録できるデー
76
ストア maxBytesLocalDisk み タの合計エントリー数、またはデー
タの合計サイズ。キャッシュマネー
ジャーに対して設定する場合
（maxBytesLocalDisk only）は、そ
のキャッシュマネージャーのデータ
プールのサイズ。この値は、一時的
なディスクの利用
（"localTempSwap"）に対して適用
されます。永続化データには適用さ
れません。
（Terracotta サーバまたはサーバアレイを使用する）分散した BigMemory Max のサイズ指定属性
について、以下の表で説明します。
データ層 属性 キャッシュマネージャ
ーレベルのプール可否 内容
ヒープ maxEntriesLocalHeap maxBytesLocalHeap
maxBytesLocalHeap の
み ローカルヒープのメモリに記録する
合計キャッシュエントリー数、また
はキャッシュの合計サイズ。キャッ
シュマネージャーに対して設定する
場合（maxBytesLocalHeap のみ）
は、そのキャッシュマネージャーの
ローカルプールのサイズ。この設定
は、キャッシュマネージャーレベル
内またはその下のすべてのキャッシ
ュに必要です。
オフヒー
プ maxBytesLocalOffHeap 可能 オフヒープのメモリに記録するキャ
ッシュの合計サイズ。キャッシュマ
ネージャーに対して設定する場合
は、そのキャッシュマネージャー下
のキャッシュのプールサイズ。この
設定には BigMemory が必要です。
ローカル
ディスク 対象外 対象外 分散キャッシュはローカルディスク
を使用できません。
Terracottaサーバア
レイ
maxEntriesInCache 不可 Terracotta サーバアレイが分散キャ
ッシュ用に格納するキャッシュの要
素数。この値はサーバアレイのすべ
てのクライアント上のエントリー数
以上の値でなければなりません。個
別の分散キャッシュに対する設定の
みとなります。デフォルトは無制限
です。
データエントリーや Element の数を設定する属性には、整数を指定します。メモリサイズ（バイト）
を設定するための属性には、Java の-Xmx オプションに指定する値（例： "500k", "200m", "2g"）、
77
または割合（例："20%"）を指定します。ただし、割合を使用できるのは、キャッシュマネージャ
ーのプールを利用する場合だけです。
以下の図に、各データ層と、それに対応する属性を示します。
12.3 各データセットのサイズ指定とプール利用との比較
各ストレージ層のデータセットのサイズを制限するには、構成情報を設定します。キャッシュマネ
ージャーに対する構成情報を利用すれば、キャッシュマネージャーが取り扱うデータのサイズを、
ストレージ層ごとに制限することも可能です。
キャッシュマネージャーのプールをストレージ層に設定しなかった場合、そのストレージ層では、
個々のデータセットに設定された制限サイズが適用されます。一方、キャッシュマネージャーのプ
ールをストレージ層に設定すると、そのストレージ層では個々のデータセットに対してプールの制
限サイズが適用されます。後者の場合、明示的にサイズを指定したデータセットの領域が先に確保
されます。その後、プール内の残りの領域が、そのストレージ層に対するサイズ指定をしなかった
データセットの領域になります。
例えば、8 セットのデータを持ち、ヒープ領域に 1GB のプール領域を持つキャッシュマネージャー
があったとします。2 つのデータセットには、それぞれ 200MB のヒープ領域が指定されています。
残りのデータセットにはサイズ指定がありません。このため、残った 6 つのデータセットが
600MB のヒープ領域を共有します。なお、キャッシュマネージャーのプールを使用する際は、デ
ータセットのサイズをバイト数で指定します。要素数を指定する属性（maxEntriesLocal で始まる
属性）では指定できません。
起動時には、個々のデータセットのサイズ指定が確認されます。これは、キャッシュマネージャー
のプールの領域不足を防止するためです。キャッシュマネージャーのプール領域が不足する場合は、
InvalidConfigurationException がスローされます。サイズを割合（パーセント）で指定する場合は、
合計が 100%を超えないようにしてください。
78
あるストレージ層のキャッシュマネージャーのプールに指定したサイズと、同じストレージ層の特
定データセットに指定したサイズが同じだった場合、警告がログに記録されます。この場合、この
データセットがそのストレージ層のプールを占有します。したがって、ほかのデータセットは、そ
のストレージ層のプールを利用できません。
12.3.1 メモリストア（ヒープ） ヒープ領域のサイズは、キャッシュマネージャー（maxBytesLocalHeap のみ）に指定するか、ある
いは個別のキャッシュ（maxBytesLocalHeap または maxEntriesLocalHeap)）に指定します。両方を
省略すると InvalidConfigurationException が発生します。
プールを設定した場合は、個々のキャッシュのヒープ設定とも組み合わせて利用できます。つまり、
プールとして確保したヒープ領域の一部を、特定のキャッシュに割り当てることが可能です。この
とき、キャッシュ側は、キャッシュマネージャーと同じ maxBytesLocalHeap で設定してください。
キャッシュマネージャーのプールを使用する場合も使用しない場合も、すべてのキャッシュにはヒ
ープの設定が必要です。
12.3.2 オフヒープストア オフヒープ領域のサイズはバイト数で指定します。エントリー数では指定できません。
オフヒープ領域にキャッシュマネージャーのプールを設定した場合、オフヒープの構成設定を持つ
キャッシュは、アプリケーションからの動的な追加ができません。動的な追加を行うとエラーが発
生します。また、プールを使用したキャッシュをプログラムまたは TMC（Terracotta 管理コンソー
ル）から削除しても、他のキャッシュはプール内の未使用の領域を使用できません。オフヒープ領
域のプールを他のキャッシュへ割り当てるには、不要なキャッシュをすべて Ehcache 構成から削除
し、構成情報を再び読み込んでください
オフヒープ領域をストレージ層として使用するには、キャッシュの overflowToOffHeap に「true」を設定してください。キャッシュマネージャーがオフヒープ領域をプールとして利用するよう設定
した場合、自動的に全キャッシュの overflowToOffHeap 属性が「true」になります。なお、特定キ
ャッシュの overflowToOffHeap 属性を明示的に「false」としておけば、そのキャッシュがオーバー
フローを起こした場合のオフヒープ領域の使用を禁止できます。
オフヒープ層を利用しているキャッシュが新しい項目を記録（put）するとき、それによってオフ
ヒープ層に割り当てられている領域サイズを越えてしまう場合は、例外がスローされます。この例
外によって表示されるメッセージの例は以下のとおりです。
The element '[ key = 25274, value=[B@3ebb2a91, version=1, hitCount=0, CreationTime = 1367966069431, LastAccessTime = 1367966069431 ]' is too large to be stored in this offheap store.
79
12.3.3 ローカルディスクストア ローカルディスクもデータ層に使用できます。ローカルディスクは、一時的なストレージとして使
用する方法と、データの永続化のために使用する方法があります。両方の使用方法の混在はできま
せん。
ディスクを BigMemory 運用中の一時的な層として使用するには、persistenceStrategy を
「localTempSwap」（「テンポラリ―ディスクストレージ」を参照）に設定し、maxBytesLocalDiskでサイズを設定します。
データ永続化のためにディスクを使用する方法の詳細は、「ディスクを永続化する実装」を参照し
てください。
Terracotta サーバアレイに分散した BigMemory Max はローカルディスクを使用できません。詳し
い情報は、「分散した BigMemory Max の構成設定ガイド」を参照してください。
12.4 サイズ指定のサンプル
ここでは、プールを使用するキャッシュのサイズ指定と、個々のキャッシュに対するサイズ指定の
サンプルを紹介します。
12.4.1 各ストレージ層のプールを使用する方法 以下は、キャッシュマネージャーの全キャッシュがプールを使用する場合の例です。
<ehcache xmlns... Name="CM1" maxBytesLocalHeap="100M" maxBytesLocalOffHeap="10G" maxBytesLocalDisk="50G"> ... <cache name="Cache1" ... </cache> <cache name="Cache2" ... </cache> <cache name="Cache3" ... </cache> </ehcache>
この場合、キャッシュマネージャーの CM1 は、3 つのキャッシュに対してプールの領域を均等に
割り当てます。つまり、各キャッシュは、ヒープ領域、オフヒープ領域、ディスク領域のそれぞれ
を 1/3 ずつ確保します。なお、キャッシュマネージャー利用してストレージ層を割り当てる場合、
サイズはバイト単位で指定します。
12.4.2 データセットのサイズを明示的に指定する方法 以下は、個々のキャッシュに対して明示的にストレージ層を割り当てる場合の例です。
80
<ehcache xmlns... Name="CM1" maxBytesLocalHeap="100M" maxBytesLocalOffHeap="10G" maxBytesLocalDisk="60G"> ... <cache name="Cache1" ... maxBytesLocalHeap="50M" ... </cache> <cache name="Cache2" ... maxBytesLocalOffHeap="5G" ... </cache> <cache name="Cache3" ... </cache> </ehcache>
上の例では、ローカルヒープ領域に 100MB のプールが用意されます。このうち 50MB を Cache1が確保します。残ったヒープ領域は、他のキャッシュが均等に分割して確保します。Cache2 は、
ローカルのオフヒープ領域に用意されたプールの半分を確保します。残ったオフヒープ領域は、他
のキャッシュが均等に分割して確保します。Cache3 は、ローカルヒープ領域の 25MB、オフヒープ
領域の 2.5GB、そしてローカルディスク領域の 20GB を確保します。
キャッシュがプールの一部を確保したからといって、その領域すべてを使用するわけではありませ
ん。例えば Cache1 はローカルヒープに 50MB の領域を確保していますが、それは、ヒープ領域に
記録できるデータの最大サイズが 50MB である、という意味です。
なお、キャッシュのサイズ属性には、プールの作成と同じサイズ属性を使用してください。例えば
Cache1 にプールの一部を割り当てるとき、maxEntriesLocalHeap は使用できません。
12.4.3 複数のサイズ指定方法を混在させる方法 キャッシュマネージャーが特定のストレージ層に対するプールを作成しない場合でも、各キャッシ
ュはそのストレージ層を使用できます。以下は、この場合の例です。
<ehcache xmlns... Name="CM2" maxBytesLocalHeap="100M"> ...
81
<cache name="Cache4" ... maxBytesLocalHeap="50M" maxEntriesLocalDisk="100000" ... </cache> <cache name="Cache5" ... maxBytesLocalOffHeap="10G" ... </cache> <cache name="Cache6" ... </cache> </ehcache>
上の例でキャッシュマネージャーの CM2 がプールを作成しているのは、ローカルヒープだけです。
CM2 のキャッシュは、プールの構成情報に従ってローカルヒープを使用します。それ以外のストレ
ージ層を利用するには、キャッシュごとに構成情報を設定します。上の例では、Cache4 がディス
ク領域を、Cache5 がオフヒープ領域を使用します。しかし、Cache6 は 25MB のローカルヒープだ
けを使用します。
12.4.4 割合で指定する方法 以下は、各ストレージ層にプールを作成する場合の例です。
<ehcache xmlns... Name="CM1" maxBytesLocalHeap="1G" maxBytesLocalOffHeap="10G" maxBytesLocalDisk="50G"> ... <!-- Cache1 gets 400Mb of heap, 2.5Gb of off-heap, and 5Gb of disk. --> <cache name="Cache1" ... maxBytesLocalHeap="40%"> </cache> <!-- Cache2 gets 300Mb of heap, 5Gb of off-heap, and 5Gb of disk. --> <cache name="Cache2" ... maxBytesLocalOffHeap="50%"> </cache>
82
<!-- Cache2 gets 300Mb of heap, 2.5Gb of off-heap, and 40Gb of disk. --> <cache name="Cache3" ... maxBytesLocalDisk="80%"> </cache> </ehcache>
「maxBytesLocalHeap」では、JVM の全ヒープ領域のうちキャッシュマネージャーが利用する領域
を、割合（パーセント）で指定できます。一方、キャッシュ（<cache>）で指定する割合は、キャ
ッシュマネージャーに割り当てた領域を 100%とし、そのうち何パーセントをキャッシュが使用す
るのか、という意味です。
注意：割合を利用したキャッシュサイズの設定
12.4.5 プールを使用せずにデータセットのサイズを指定する方法 以下は、キャッシュマネージャーのプールを作成しない場合の例です。
<ehcache xmlns... Name="CM3" ... > ... <cache name="Cache7" ... maxBytesLocalHeap="50M" maxEntriesLocalDisk="100000" ... </cache> <cache name="Cache8" ... maxEntriesLocalHeap="1000" maxBytesLocalOffHeap="10G" ... </cache> <cache name="Cache9" ... maxBytesLocalHeap="50M" ... </cache> </ehcache>
83
この場合でも、必要なストレージ層は、キャッシュごとに設定できます。上の例では、すべてのキ
ャッシュがローカルヒープ領域を使用するよう明示的に定義しています。これは、ローカルヒープ
領域にプールが用意されていないからです。ストレージ層を使用するには、暗黙の定義（キャッシ
ュマネージャーによる構成設定）または明示的な定義（各キャッシュの構成設定）が必要です。
12.5 分散キャッシュのサイズ指定
上述のように、Terracotta の分散キャッシュのサイズは指定することができます。ただし、これら
の分散キャッシュはローカルディスクを使用しないため、サイズ指定属性「*LocalDisk」を使った
構成情報の設定はできません。分散キャッシュは Terracotta サーバアレイのストレージリソース
（BigMemory Max と高速再起動ストア）を利用します。詳細は「TSA 高速再起動」を参照してくだ
さい。
キャッシュの構成情報にあるサイズ指定属性は、ローカルの構成情報として動作します。つまり、
同一のキャッシュに対してすべてのノードがそれぞれのサイズ指定属性を読み込むことができます。
要素と属性はクラスタで最初に読み込んだ Ehcache の構成情報で固定されるものもありますが、同
一キャッシュに対するキャッシュ構成のサイズ指定属性はノードによって異なります。
例えば、あるノードのキャッシュの構成情報が以下だとします。
<cache name="myCache" maxEntriesOnHeap="10000" maxBytesLocalOffHeap="8g" eternal="false" timeToIdleSeconds="3600" timeToLiveSeconds="1800"> <persistence strategy="distributed"/> <terracotta/> </cache>
同じキャッシュが別のノードに対して以下のサイズ指定の構成情報を含んでいたとします。
<cache name="myCache" maxEntriesOnHeap="10000" maxBytesLocalOffHeap="10g" eternal="false" timeToIdleSeconds="3600" timeToLiveSeconds="1800"> <persistence strategy="distributed"/> <terracotta/> </cache>
84
この構成設定の場合、あるノードでキャッシュのサイズ指定制限を超えると、Terracotta サーバア
レイは myCache に無制限のスピルオーバー／バックアップ用スペースを提供します。上限を設け
るには、maxEntriesInCache にゼロ以外の正の値を設定してください。
<cache name="myCache" maxEntriesOnHeap="10000" maxBytesLocalOffHeap="10g" eternal="false" timeToIdleSeconds="3600" timeToLiveSeconds="1800" maxEntriesInCache="1000000"> <persistence strategy="distributed"/> <terracotta/> </cache>
これにより Terracotta サーバアレイは、maxEntriesInCache で設定した上限を超えないように、
myCache のエントリーをエビクションによって破棄します。ただし、いかなるキャッシュについて
も、Terracotta サーバアレイ上のエビクションは、そのキャッシュに対して設定した最大サイズに
基づいて行なわれます。また、Terracotta サーバアレイは、maxEntriesInCache で上限が設定され
ているかどうかにかぎらず、少なくとも 1 つのクライアントノードに存在するキャッシュのエント
リーは破棄しません。
注意：maxEntriesInCache の設定を省略すると、デフォルト値の「0」が指定されます。これは、キ
ャッシュへのエントリー格納が無制限となり、容量に基づくエビクションが行われないことを意味
します（ただし、定期的なエビクションとリソースに基づくエビクションは行なわれます）。詳細
は「エビクション」を参照してください。
Terracotta サーバアレイによるデータ管理の詳細は、「自動リソース管理」を参照してください。
12.5.1 Terracottaサーバアレイのサイズ指定 maxEntriesInCache はエントリー数（項目数）で指定するパラメータです。したがって、Terracottaサーバアレイのサイズを決める際は、各項目の平均サイズを考慮してサイズを設定する必要があり
ます。サイズの見積り方法の 1 つに、TMC（Terracotta 管理コンソール）を利用する方法がありま
す。まず、予測されるデータセットを持つテスト用クラスタを作成し、それを TMC に接続します。
そして、TMC の「Application data > Sizing Panel」を開き、Tier セクションの Relative Cache Size を
確認します。
なお、TMCが示すキャッシュエントリーの平均サイズも見積もり値です。詳細は、Terracotta管理
コンソールを参照してください。(http://www.terracotta.org/documentation/tms/tmc-using).
85
12.6 サイズ制限のオーバーライド
キャッシュのピンニングを行うと、キャッシュ構成情報で定義したサイズ制限の対象から外れます。
このため、OutOfMemory エラーの原因になることがあります。これは、ピンニングを行ったキャ
ッシュには、別のデータ層への移動（フラッシュ）が発生しないからです。ピンニングの詳細は、
「ピンニング、エビクション、有効期限」を参照してください。
12.7 サイズ制限と、ビルトインのサイズ計算
BigMemory は、各データ要素を追跡し、キャッシュマネージャーが用意するプールのサイズの制限
に収めるための仕組みを持っています。
12.7.1 データセットのサイズ計算 Ehcache は、メモリサイズが制限された領域にあるキャッシュの Element のサイズを、常に計算し
ています。計算対象になるのは、キャッシュ内の個々の Element インスタンス全体のメモリ占有量
です。サイズの計算では、key、value のほか、そのインスタンスを内部データ構造へ追加すること
で生じるオーバーヘッドなども対象になります。key と value はオブジェクトグラフとして計算し
ます。参照がある場合は、参照先も計算に入れます。オブジェクト参照も計算対象です。参照は再
帰的に追跡して計算します。
参照が共有されている場合、それを参照しているすべてのクラスのサイズも計算に入ります。この
ため、サイズの計算結果は、本来の結果よりも大きくなります。したがって、共有参照は無視する
必要があります。
サイズ計算の無視
サイズ計算で参照のサイズを無視するには@IgnoreSizeOf アノーテーションを使います。このアノ
ーテーションは、クラス、フィールド、またはパッケージに付加します。また、ファイルの完全修
飾名に付加することで、そのファイル内のクラス、フィールド、またはパッケージを無視するよう
指定できます。
このアノーテーションは継承されません。サブクラスをサイズ計算の対象外にするときは、それら
のサブクラスにも付加してください。
以下は、Dog クラスを無視する場合の例です。
@IgnoreSizeOf public class Dog { private Gender gender; private String name; }
以下は、sharedInstance フィールドを無視する場合の例です。
86
public class MyCacheEntry { @IgnoreSizeOf private final SharedClass sharedInstance; ... }
「@IgnoreSizeOf」アノーテーションを「package-info.java」に付加すれば、そのパッケージを無視
できます。以下は、「com.pany.ignore package」の「package-info.java」の例です。
@IgnoreSizeOf package com.pany.ignore; import net.sf.ehcache.pool.sizeof.filter.IgnoreSizeOf;
ほかに、無視するクラスやフィールドを宣言するファイルを作成し、そのファイルをシステムプロ
パティの net.sf.ehcache.sizeof.filter で指定する方法もあります。
# That field references a common graph between all cached entries com.pany.domain.cache.MyCacheEntry.sharedInstance # This will ignore all instances of that type com.pany.domain.SharedState # This ignores a package com.pany.example
なお、これまでに説明したサイズの計算方法と、これらの構成情報は、オンヒープのストレージ層
だけが対象です。Element がオフヒープ層やディスク層へ移動する際は、シリアル化によってバイ
ト配列に変換されます。変換後のサイズ計算には、シリアル化済みバイト配列のサイズが使用され
ます。
オブジェクトグラフ間の横断を制限する構成設定
既に述べたとおり、キャッシュのサイズ計算では、オブジェクトグラフをまたがる場合があります。
このような場合のサイズ計算は、アノーテーションで制限できます。このサイズ計算は、キャッシ
ュマネージャー単位およびキャッシュ単位で制御できます。
キャッシュマネージャーに対する SizeOf ポリシー
SizeOf エンジンは、ヒープ領域の Element の参照関係を追跡してサイズを計算します。追跡の深さ
は、キャッシュマネージャーに対する構成情報で設定します。
<sizeOfPolicy maxDepth="100" maxDepthExceededBehavior="abort"/>
この要素に指定する属性は以下のとおりです。
87
• maxDepth –：最大の深さを指定します。SizeOf エンジンがサイズを計算する前にたどる、オブ
ジェクトリンクの深さです。この属性は省略できません。
• maxDepthExceededBehavior –：オブジェクトグラフのサイズ計算で経路をたどるとき、指定さ
れた最大の深さまでたどっても計算が完了しない場合があります。その場合の動作を記述しま
す。
– "continue" –： SizeOf エンジンは、警告をログに記録し、サイズの計算を続行します。
デフォルト値です。この属性を省略すると、"continue"を指定したときと同じ動作にな
ります。
– "abort" –： Size-Of エンジンは、警告をログに記録し、サイズの計算を中止します。さ
らに、そのキャッシュのメモリ利用を正しく追跡できなかったことを記録します。こ
の値を設定すると、Ehcache.hasAbortedSizeOf()は「true」を返します。
SizeOf ポリシーは、キャッシュマネージャーのレベル（<ehcache>直下)）と、キャッシュのレベル
（<cache>または<defaultCache>の直下）に設定できます。キャッシュマネージャーとキャッシュの
両方にポリシーを設定した場合、キャッシュ側の設定が利用されます。
キャッシュに対する SizeOf ポリシー
前述のとおり、SizeOf エンジンはヒープ層のキャッシュの Element を追跡してサイズを計算します。
この際の追跡の深さは、各キャッシュにも指定できます。<cache>ブロックに、<sizeOfPolicy>を子
要素として設定してください。SizeOf ポリシーを設定したキャッシュでは、キャッシュマネージャ
ーに設定した SizeOf ポリシーが無視されます。
SizeOf に関連するエラーのデバッグ
SizeOf エンジンがサイズ計算のためにオブジェクトグラフを追跡しているとき、警告やエラーが発
生する場合もあります。サイズ計算に関連する警告やエラーが発生した場合は、以下の手順で詳細
なログを収集してください。
• net.sf.ehcache.sizeof.verboseDebugLogging システムプロパティを「true」に設定します。
• SLF4J から実装を選択し、net.sf.ehcache.pool.sizeof のデバッグログを有効化します。
12.7.2 キャッシュマネージャーによるプール使用時のエビクション キャッシュマネージャーが用意したプールが一杯になると、キャッシュ要素がエビクションによっ
て破棄されます。こうしてプールの空き領域が確保されます。キャッシュのエビクションは、キャ
ッシュに対して設定したエビクションアルゴリズム（LRU、LFU など）に従って実行されます。エ
ビクション対象のキャッシュ要素は、以下の「最小エビクションコスト」のアルゴリズムを使用し
て選択されます。
eviction-cost = mean-entry-size * drop-in-hit-rate
88
エビクションコストは、報源となる SOR（System of Record：データベースなど）から取得するバ
イト数の増加を、必要なバイト数をキャッシュから破棄するために要した時間で割った値です。
ヒットの分布を単純にべき乗則で表すと以下の式になります。
P(hit n'th element) ~ 1/n^{alpha}
連続限界では、総ヒット率がキャッシュ内の要素に対する分布関数の積分と比例することを意味し
ます。エビクションにより生じるヒット率の変化は、初期サイズから最終サイズにおける分布関数
の積分として表現できます。キャッシュ全体のサイズよりもエビクションのサイズが小さいと仮定
した場合、以下の式で表現できます。
drop ~ access * 1/x^{alpha} * Delta(x)
「access」はアクセス率全体（ヒット＋ミス）を、「x」はキャッシュの「占有度」の非単位的測量
を示します。占有度の近似値をヒット率とアクセス率の割合として表し、エビクションコストの式
に当てはめると、以下の式になります。
eviction-cost = mean-entry-size * access * 1/(hits/access)^{alpha} * (eviction / (byteSize / (hits/access)))
この式は、以下のように単純化できます。:
eviction-cost = (byteSize / countSize) * access * 1/(h/A)^{alpha} * (eviction * hits)/(access * byteSize) eviction-cost = (eviction * hits) / (countSize * (hits/access)^{alpha})
すべてのキャッシュで同値な「eviction」の公約数を削除すると、キャッシュからのエビクション
に伴う最小値は、以下のようになります。
eviction-cost = (hits / countSize) / (hits/access)^{alpha}
キャッシュのヒット率がゼロの場合（つまり、最初の読み込み時）は、このアルゴリズムを無視で
きます。したがって、キャッシュはプール領域の 1/ｎを占有できます（n はプールを使用している
キャッシュの数）。キャッシュに対するアクセスが始まってから、実際のキャッシュ利用の傾向に
合わた調整が行われます。
13 ピンニング、有効期限、エビクション
13.1 はじめに
このページでは、BigMemory の各ストレージ層に記録されたデータに対する有効期限の管理を説明
します。また、ARC（Automatic Resource Control）のピンニング機能も合わせて説明します。
BigMemory の各ストレージ層で利用できるデータの有効期限は以下のとおりです。
89
• Flush：より遅いストレージ層にデータを移動します。Flush（フラッシュ）とは、BigMemory内にデータを保持しつつ、現在使用されているリソースを解放するための処理です。
• Fault：遅いストレージ層から高速なストレージ層へデータをコピーします。Fault（フォルト）
とは、一時的に高速なストレージ層が必要になるものの、そこへデータを維持し続ける必要が
ない場合に使用する処理です。Fault では、コピー元となる低速なストレージ層のエントリー
を削除しません。
• Eviction： BigMemory から、そのデータのエントリーを破棄します。エントリーは完全に削除
されます。再び必要になった場合には、外部のソースから再ロードする必要があります。エン
トリーのエビクションは、リソースを解放するために発生します。
• Expiration：「TTL（Time To Live）」および「TTI（Time To Idle）」の設定に基づくステータ
スです。パフォーマンス維持のため、ステータスが Expiration になったエントリーに対し、直
ちにフラッシュ（データの移動）やエビクション（データの破棄）が発生するわけではありま
せん。
• Pinning：無期限にメモリ上でデータを維持し続けます。
90
13.2 有効期限の設定
BigMemory のデータエントリーの有効期限は、構成情報のパラメーターで決まります。エビクショ
ンが発生すると、有効期限に達している要素が先に破棄されます。ヒープなどのリソースの利用効
率を高め、全体のパフォーマンスを維持するには、構成情報を利用して効果的な有効期限を設定す
ることが重要です。
有効期限を設定するには、以下の<cache>属性を編集します。パフォーマンステストを実施し、適
切な値を算出してチューニングしてください。
• timeToIdleSeconds： BigMemory のデータストアにデータを維持する時間の最大値を指定しま
す。まったくアクセスされていないデータだけが対象です。単位は「秒」です。この時間を過
91
ぎると、データ要素は有効期限切れとなり、BigMemory はその要素を返しません。デフォル
ト値は 0 です。これは TTI エビクションが発生しない（有効期限なし）という意味です。
• timeToLiveSeconds：データを BigMemory のデータストアに維持する時間の最大値を指定しま
す。データへのアクセス状況を問わず、すべてのデータが対象です。単位は「秒」です。この
時間を過ぎると、データ要素は有効期限切れとなり、BigMemory はその要素を返しません。
デフォルト値は 0 です。これは TTL エビクションが発生しない（有効期限なし）という意味
です。
• maxEntriesInCache：すべての Terracotta クライアントにおける要素（キャッシュエントリー）
の最大合計数を指定します。この値を超えると、合計数を許容範囲内に抑えるためのエビクシ
ョンが実行されます。デフォルト値は「0」です。これは、キャッシュが容量に基づくエビク
ションを行なわないことを意味します（ただし、定期的なエビクションとリソースに基づくエ
ビクションは行なわれます）。maxEntriesInCache は TSA に割り当てられたストレージを反映
します。
• eternal：キャッシュに eternal フラグを設定すると、キャッシュの有効期限は無制限になりま
す。TTI および TTL の有効期限は無視されます。個別のキャッシュ要素の有効期限も無制限に
設定できます。無制限に設定された要素やキャッシュに有効期限はありませんが、エビクショ
ンによって破棄されることはあります。
エビクションに対する構成情報の効果の詳細は「構成設定による Element のフラッシュとエビクシ
ョンの仕組み」を参照してください。
13.3 データのピンニング
ピンニングを設定していないキャッシュ要素は、期限切れになると flush によって移動し、最終的
にはエビクションによって破棄されます。リソースの上限に達した場合、期限切れとなっていない
要素も flush やエビクションの対象になります。ピンニングは、BigMemory によるエビクション発
生の可否をキャッシュ単位で制御する機能です。
データにピンニングを設定することで、メモリからの移動や破棄を防止できます。なお、ピンニン
グは 1 つのキャッシュ全体に対して設定します。個々のキャッシュ要素には設定できません。ピン
ニングには 2 種類の構成があります。1 つはリソースの制約よりも優先する構成で、もう 1 つはリ
ソースの制約のほうが優先する構成です。詳細は、以下のセクションを参照してください。
13.3.1 ピンニングの設定 特定のキャッシュ全体にピンニングを行うには、Ehcache 構成情報の pinning 要素を使用します。
この要素の必須属性（store）に、ピンニングをどのように実現するかを指定します。
store 属性に指定できる値は以下のいずれかです。
92
• inCache：データを、キャッシュデータが格納された任意の層のキャッシュ内にピンニングし
ます。その層は、パフォーマンス効率向上のアルゴリズムに基づいて決定されます。期限切れ
のエントリーはエビクションされません。
• localMemory：データを、メモリストアまたはオフヒープストアにピンニングします。エント
リーは、ストアの設定サイズを超過するイベントによってのみエビクションされます。
エントリーをピンニングするキャッシュの例は以下のとおりです。
<cache name="Cache1" ... > <pinning store="inCache" /> </cache>
ヒープまたはオフヒープにエントリーをピンニングするキャッシュの例は以下のとおりです。
<cache name="Cache2" ... > <pinning store="localMemory" /> </cache>
13.3.2 ピンニングとキャッシュのサイズ指定 ピンニングの構成とキャッシュサイズの構成との関係は、ピンニングの構成オプションで設定しま
す。
inCache を指定した場合は、キャッシュサイズの設定値よりもピンニング設定のほうが優先します。
ピンニングによってキャッシュ内に維持されている要素は、期限切れにならない限り、エビクショ
ンで破棄されることはありません。ピンニングが設定されたキャッシュはエビクションの対象にな
りません。また、maxEntriesInCache も設定できません。
ピンニングが指定されたキャッシュのサイズは、無制限に大きくなる可能性があります。限られた
量のデータ（データ参照など）を保持するようにデザインされたキャッシュ以外には、できるだけ
ピンニングを適用しないでください。それ以外の場合は、キャッシュの有効期限の性質を正確に把
握し、問題が発生しない確証を得られた場合のみピンニングを設定してください。
inCache のピンニングに関する注意
localMemory を指定した場合は、ピンニング設定よりもキャッシュサイズの設定値のほうが優先し
ます。localMemory のピンニングは、キャッシュ運用の最適化のために使用します。このピンニン
グを設定したキャッシュのデータは、リソースが枯渇しない限り、ヒープまたはオフヒープ領域に
保持されます。あらかじめ設定されたサイズ（エントリー数）を越えた場合はエビクションによる
破棄が発生します。以下の例に示すキャッシュでは、maxEntriesOnHeap と maxBytesLocalOffHeapの設定がピンニング設定よりも優先します。
93
<cache name="myCache" maxEntriesOnHeap="10000" maxBytesLocalOffHeap="8g" ... > <pinning store="localMemory" /> </cache>
13.3.3 ピンニングのスコープ ピンニング設定されたキャッシュは、ローカルの Ehcache クライアント（L1）のメモリに保持され
ます。クラスタへの分散は発生しません。ピンニングが設定されたキャッシュを「一括ロード」す
ると、ピンニング対象のデータは L1 から削除され、TSA から Fault によって再ロードされます。
プログラムによって設定したピンニングは永続的ではありません。再起動すると、それまでのピン
ニングは解除されます。L1 が「rejoin」によってクラスタへ再接続したときも、ピンニングは解除
されます。構成情報ファイルで設定したキャッシュのピンニングは、再起動時に再設定されます。
13.4 データの明示的な削除
キャッシュのすべてのエントリーのピンニングを解除するには、キャッシュをクリアします。
Cache.remove()を使うことで、キャッシュから特定のエントリーを削除できます。キャッシュを空
にするには Cache.removeAll()を使います。キャッシュそのものを削除（Cache.dispose()または
CacheManager.removeCache()）すると、キャッシュ内に残っていたデータもローカルからは削除さ
れます。ただし、TSA またはディスク（再起動可能な場合）からは削除されません。
13.5 構成設定によるElementのフラッシュとエビクションの仕組み
以下は、有効期限を設定したキャッシュの例です。
<cache name="myCache" eternal="false" timeToIdleSeconds="3600" timeToLiveSeconds="0" memoryStoreEvictionPolicy="LFU"> </cache>
この「myCache」の構成情報によって、以下の状況が発生します。
• timeToIdleSeconds で指定された時間（この例では 1 時間）以上アクセスのなかった myCacheのエントリーには、エビクションが発生します。
• エントリーのエビクションが発生しても、リソースに余裕があれば、そのエントリーは、定期
的なエビクションによって破棄されるまで、その位置に記録されたままになります。
• timeToLiveSeconds で指定された時間（この例では 1 時間）よりも短い間隔で myCache のエ
ントリーに対する定期的なアクセスがあれば、そのエントリーが破棄されることはありません。
94
しかしながら、ほかの制約によってエントリーの移動（Flush）が発生する場合があります
（「ストレージ層のサイズ指定」を参照）。
13.6 データの鮮度と有効期限
通常、データベースなど外部キャッシュに適応していない SOR（記録システム）は、外部プロセス
にデータの更新や追加を通知するための仕組みを標準装備していません。
BigMemory をキャッシュシステムとして使用した場合、以下のような方法を採用することで、キャ
ッシュ内のデータの鮮度を保ちやすくなります。
• データの有効期限：Ehcache が提供するエビクションアルゴリズムに加え、timeToIdleSecondsと timetoLiveSeconds の設定を利用することで、キャッシュ内の各要素の最大有効期限を設定
します。そしてデータベースや SOR からのデータの再ロードを強制的に実行します。
• メッセージバス：すべてのデータベース更新を一任するアプリケーションを使用します。デー
タベースに対する更新があった場合、このアプリケーションが、更新のあったキーを含むメッ
セージをキューにポストします。すべてのアプリケーションインスタンスが、このメッセージ
バスをアクセスするよう設定すれば、データ更新のメッセージを取得できます。更新されたデ
ータを持つエントリーを無効化するなどしてキャッシュを期限切れにすれば、データのローカ
ルコピーを強制的に同期できます。
• トリガーデータベースのトリガーを利用すれば、データバスを利用する方法と同じような効果
を得ることができます。データベーストリガーを利用して、メッセージバスにメッセージを送
信するコードを実行します。この方法の利点は、データベースの更新のためにわざわざ特殊な
アプリケーションを実行する必要がないことです。しかし、この方法には問題点もあります。
まず、こうした処理を実行するための環境を備えていないデータベーストリガーもあります。
また、データベーストリガーで重い処理を実行するのは推奨されません。メッセージの送信も、
重い処理の部類に入ります。
以上の中では、データの有効期限を利用する仕組みが最も単純で簡単です。この方法でも、ほとん
どのデータの同期を制御できます。外部システムとの連携も不要です。データの有効期限に関する
方針を決め、Ehcache にキャッシュデータの期限切れ処理を一任します。そうすれば、データは再
ロードされるため、キャッシュの内容も自動的に同期されます。
データの有効期限を利用する方法を採用する場合は、「キャッシュエビクションアルゴリズム」を
参照し、構成情報の「timeToIdle と timeToLive」を設定してください。有効期限を利用する方法で
最も大切なことは、データの鮮度と、データベースの負荷のバランスを考慮することです。有効期
限を短く設定する、つまりデータの鮮度を高めれば、データベースの負荷も高くなります。
有効期限の値を何種類か試し、アプリケーションの負荷がどれくらいになるのかを比較してくださ
い。300 秒や 600 秒など、値をほんの少し大きくするだけで、アプリケーションの負荷を大幅に低
減できる場合があります。
95
14 高速再起動
14.1 はじめに
BigMemory の高速再起動は、インメモリデータをリアルタイムに記録し、完全な整合性を保証しま
す。提供される障害回復能力は、エンタープライズレベルの業務でも利用可能です。シャットダウ
ン（計画的シャットダウンと障害によるシャットダウンを含む）後にアプリケーションを再起動す
ると、それまでの BigMemory 内のデータはそのまま残り、素早くアプリケーションからアクセス
できます。
高速再起動機能の利点は以下のとおりです。
• 障害が発生してもインメモリのデータが消えません。直ちに業務を再開できます。わざわざ遠
隔地のデータソースからインメモリのデータを再ロードする必要がないため、アプリケーショ
ンは再起動の直後から最大のパフォーマンスを発揮できます。
• インメモリのデータをリアルタイムに記録することで、高い耐障害性を提供します。メモリ内
にテラバイト（TB）規模のデータを保有可能な BigMemory でも、高速再起同機能はローカル
の「ホットミラー」に相当するデータの完全整合性を保証します。
• インメモリと整合性のあるデータ記録を持つことにより、ビジネス革新の可能性が大きく広が
ります。刻々と変化するニーズに合わせてデータセットを手配し、必要な場所へ直ちにデータ
セットを配置できます。高速再起動のストアは、高速な読み取りパフォーマンスを備えたシン
プルな「key-value」を永続化するメカニズムから、読み書きにインメモリのスピードが要求
されるオペレーションストアまで、幅広く活用できます。
14.2 データの永続性の実装
BigMemory の高速再起動機能は、ローカルディスクの高速再起動ストアで永続化したインメモリの
データのリアルタイム記録を作成します。再起動後、それまでインメモリ（ヒープ領域とオフヒー
プ領域の両方）にあったデータを、自動的に高速再起動ストアから復旧します。
データの永続化を有効化するには、キャッシュ構成情報の子要素に<persistence>を追加します。子
要素の<persistence>には、2 つの属性を記述します。strategy と synchronousWrites です。
<cache> <persistence strategy=”localRestartable|localTempSwap|none|distributed” synchronousWrites=”false|true”/> </cache>
14.2.1 永続化方式の指定（strategy属性） strategy 属性には、以下のオプションの 1 つを設定します。
96
• "localRestartable"：高速再起動機能を有効化します。すべての BigMemory データが自動的に
ログに記録されます。永続化により、データの耐障害性は高まり、高速再起動も可能になりま
す。
• "localTempSwap"：一時的なローカルディスクの利用を可能にします。システム運用で使用で
きるデータ記憶領域は増加します。しかし、この領域のデータは永続化されません。再起動を
行うと、この領域の BigMemory データはすべてクリアされます。
• "none"：ストレージ層としてディスクを使用しません。このオプションを指定すると、すべ
てのデータがインメモリを使用して記録されます。このモードがデフォルト値です。
• "distributed"：構成情報の<terracotta>を使用して、永続化の設定を行います。詳細は、
「Terracotta クラスタ構成の要素」を参照してください。
14.2.2 同期方式の指定（synchronousWrites属性） strategy 属性に"localRestartable"を指定した場合は、synchronousWrites 属性も設定できます。
synchronousWrites には、以下のオプションの 1 つを設定します。
• "false"：非同期のデータ記録を常にディスクに保存する設定です。キャッシュは、ディスクへ
の書き込みを待たずに処理を継続します。メモリとディスクとの同期は、システムの負荷が低
いときに実行されます。システムを再起動すると、最後に同期処理を行った時点のデータが復
元されます。synchronousWrites="true"よりも高速ですが、障害発生時には、最後の 2-3 秒間
に書き込まれたデータを失う可能性があります。
この設定が、このオプションを省略した場合のデフォルト値です。
• "true"：同期のデータ記録を常にディスクに保存する設定です。データセットへの変更は、デ
ィスク上に同期されます。呼び出した処理に制御が戻る前に、ディスクへの書き込みを行いま
す。再起動後、シャットダウン前と全く同じ内容にデータが復元されます。このオプションは
データの完全な整合性を提供しますが、synchronousWrites="false"よりもパフォーマンスは低
下します。
synchronousWrites 使用時のトランザクションは、ソフトロックを使用してアクセスを保護します。
トランザクション実行中に障害による再起動が発生した場合、このソフトロックは、システム回復
後の該当データに対する次のアクセス時に解除されます。
注意: synchronousWrites 属性は、子要素<terracotta>でも使用できます。この属性を両方の子要素
に指定するときは、全く同じ値を使用してください。
14.2.3 ディスクストアのパス ディスク上に作成する必要なファイルの保存先を指定するため、ディレクトリのパス名を
Ehchache の構成情報の子要素<diskStore>で設定します。
• "localRestartable"属性に、一意のパスを明記してください。
97
• "localTempSwap"でディスクストアのパスを省略すると、ディスク層にはデフォルトパスが使
用されます。このデフォルトパス名は、他のキャッシュマネージャーとの競合を避けるため、
自動的に作成されます。
注意：高速再起動機能は、ディスクを利用した通常の永続化とは異なる方法でディスク層を使いま
す。そのため、"localRestartable"を設定した場合、「Cache.getDiskStoreSize()」または
「Cache.calculateOnDiskSize()」といった「diskStore」のサイズ測定は適用されず、「0」が返され
ます。逆に、"localTempSwap"を設定した場合は、こういったサイズ測定により正しいサイズ値が
返されます。
14.3 構成情報のサンプル
このセクションでは、スタンドアローンの Ehcache 2.6 で使用できるディスク用の構成情報を説明
します。
14.3.1 障害復旧に備えた設定 以下の構成情報は、データの同期永続化と、高速再起動を提供する例です。
<ehcache> <diskStore path="/path/to/store/data"/> <cache> <persistence strategy="localRestartable" synchronousWrites="true"/> </cache> </ehcache>
以下の構成情報は、データの非同期永続化と、高速再起動を提供する場合の例です。
<ehcache> <diskStore path="/path/to/store/data"/> <cache> <persistence strategy="localRestartable" synchronousWrites="false"/> </cache> </ehcache>
14.3.2 クラスタ化したキャッシュ BigMemory Max を Terracotta サーバアレイ（TSA）に分散するには、構成情報で「ehcache.xml」の永続化方式を"distributed"に設定します。また、<terracotta>子要素が構成情報に含まれているこ
とが必須です。
<cache> maxEntriesInCache="100000"> <persistence strategy="distributed"/>
98
<terracotta clustered="true" consistency="eventual" synchronousWrites="false"/> </cache>
maxEntriesInCache 属性は分散キャッシュ内の最大エントリー数を指定します。
（maxEntriesInCache は必須ではありませんが、省略するとデフォルトは無制限になります。）
注意：クライアントも高速再起動の対象にする場合は、TSA で高速再起動を有効にしてください。
14.3.3 テンポラリーディスクストレージを使用する設定 永続化方式（strategy 属性）に"localTempSwap"を指定すると、BigMemory 運用中にインメモリの
データのためにローカルディスク層を生成します。この場合のディスク領域は一時的な領域です。
再起動時にクリアされます。
<ehcache> <diskStore path="/auto/default/path"/> <cache> <persistence strategy="localTempSwap"/> </cache> </ehcache>
注意: 永続化方式"localTempSwap"では、キャッシュまたはキャッシュマネージャーのディスク層の
サイズを指定できます。サイズを指定するには、Cache または CacheManager のレベルに
maxEntriesLocalDisk または maxBytesLocalDisk を設定します。
14.3.4 インメモリ領域だけを使用するキャッシュ 永続化方式（strategy 属性）に"none"を指定すると、すべてのキャッシュがメモリ上に乗ります
（ディスクを利用するオーバーフローや永続化は利用できません）。
<cache> <persistence strategy="none"/> </cache>
14.3.5 プログラムによる構成設定のサンプル 以下は、ディスク上でのキャッシュの永続化をプログラムから構成するための例です。
Configuration cacheManagerConfig = new Configuration() .diskStore(new DiskStoreConfiguration() .path("/path/to/store/data")); CacheConfiguration cacheConfig = new CacheConfiguration() .name("my-cache") .maxBytesLocalHeap(16, MemoryUnit.MEGABYTES) .maxBytesLocalOffHeap(256, MemoryUnit.MEGABYTES)
99
.persistence(new PersistenceConfiguration().strategy(Strategy.LOCALRESTARTABLE)); cacheManagerConfig.addCache(cacheConfig); CacheManager cacheManager = new CacheManager(cacheManagerConfig); Ehcache myCache = cacheManager.getEhcache("my-cache");
14.4 高速再起動のパフォーマンス
構成情報に高速再起動（永続化方式"localRestartable"）を設定すると、再起動時にすべてのインメ
モリデータが読み込まれてから、BigMemory が利用可能になります。BigMemory が利用可能にな
るまでの時間は、インメモリデータ量と基礎インフラ（システムが稼働しているコンピュータ）の
スピードによって異なります。一般的に、回復のスピードはディスクのスピードに比例します。例
えば、読み取りスループットが 1GB/秒の SSD の場合、回復時の読み込み速度も同様になります。
14.5 高速再起動の制限
BigMemory の高速再起動を構成設定する際は、以下の推奨事項を参照してください。
• シャットダウン時に、オンヒープストアとオフヒープストアのサイズを変更しないでください。
割り当てられたメモリ量が減ると、再起動時にエビクションが発生し、キャッシュデータの一
部が破棄されます。
• シャットダウン時に、キャッシュマネージャーからリスタータブルキャッシュを削除しないで
ください。
• リスタータブルキャッシュを削除すると、キャッシュへの参照だけ削除されます。キャッシュ
のコンテンツはメモリとディスクに残ります。この状態で再起動すると、キャッシュのコンテ
ンツが回復し、再びメモリとディスクを消費します。不要なリスタータブルキャッシュを安全
に破棄するには、キャッシュで「clear」を呼び出します。これで、ディスクとメモリの領域を
占有しなくなります。
15 BigMemory Max分散構成設定ガイド
15.1 はじめに
BigMemory Max の構成情報ファイル（デフォルトでは ehcache.xml）には、CacheManager（定義さ
れたキャッシュを管理する Ehcache のクラス）の 1 つのインスタンスの構成情報が記録されていま
す。この構成情報ファイルは、利用するアプリケーションのクラスパスに保存します。WAR ファ
イルを使用する際には、ehcache.xml を WEB-INF/classes にコピーしておく必要があります。
Terracotta クラスタの ehcache.xml は、以下の点に注意して取り扱ってください。
100
• クラスタへの追加では、最初の Terracotta クライアント（アプリケーションサーバまたはノー
ド）のディスクに記録された ehcache.xml がメモリにロードされます。
• XML のロードが完了すると、クラスタ内の Terracotta サーバによって構成情報がメモリ上で
永続化されます。ロード元となったクライアントを再起動しても、ロード済みの構成情報は消
えません。
• メモリ上の構成情報は、Terracotta 管理コンソールから編集します。変更した構成情報の内容
は直ちに適用されます。しかし、コピー元となったディスク上の ehcache.xml は更新されませ
ん。
• サーバが非永続化モード（デフォルト値の<restartable enabled="false">）の場合、サーバを再
起動するとメモリ上のキャッシュ構成情報は削除されます。そして、元の（ディスク上の）
ehcache.xml が再ロードされます。
• サーバが永続化モード（<restartable enabled="true">）の場合、サーバを再起動してもメモリ
上のキャッシュ構成情報は消えません。永続化モードで稼働している Terracotta サーバで、オ
リジナルの ehcache.xml をディスクから再ロードするには、サーバの server-data ディレクト
リからサーバ情報のデータファイルを削除する必要があります。このディレクトリは、
Terracotta 構成情報ファイルに指定されています（デフォルトでは tc-config.xml）。ただし、
サーバ情報のデータベースを削除すると、永続化されたすべての共有データも削除されます。
分散キャッシュを利用するための最小限の構成情報は以下のとおりです。
• 「CacheManager」
• 「Clustering 要素」（各キャッシュ構成情報に必要）
• 「Terracotta クライアント構成情報」のソース
15.2 CacheManagerの構成設定
キットに同梱された参照用の ehcache.xml には、CacheManager 構成情報の要素と属性に関する全
情報が記載されています。
15.2.1 ehcache.xmlによる構成設定 <ehcache>に設定できる属性は以下のとおりです。
• name： CacheManager の名前を指定します。省略可能です。name は、単なる説明の一種です。
Terracotta のキャッシュがクラスタ化されていることを簡単に判断できる名前を指定してくだ
さい。Terracotta クラスタ化キャッシュでは、CacheManager の名前とキャッシュの名前を組
み合わせることで、Terracotta クラスタ化メモリのキャッシュストアを一意に識別できます。
name で指定した名前はデベロッパーコンソールに表示されます。
101
<ehcache>要素の name 属性は、複数の Ehcache 構成情報ファイルを使用する環境で、クラスタ内
の CacheManager を識別するために使用します。Terracotta デベロッパーコンソールには、
CacheManager の名前のリストを表示するメニューがあります。このメニューを利用して、表示し
たい CacheManager を選択できます。
ヒント：CacheManager の命名について
• updateCheck： CacheManager に最新版 Ehcache のチェックを行うかどうかを、ブール型の値
で指定します。最新版のチェックはインターネット経由で行います。この属性は省略可能です。
デフォルト値は「updateCheck="true"」です。
• monitoring：システムの MBean サーバを使用して SampledCacheMBean を CacheManager が自
動登録するかどうかを指定します。この属性は省略可能です。現在のところ、この属性が使用
されるのは、Terracotta クラスタ環境を使用している場合のみです。値に"autodetect"を指定
すると、Terracotta クラスタ環境の存在を確認したうえで、MBean を登録します。値には、ほ
かに"on"または"off"を指定できます。デフォルト値は"autodetect"です。
<Ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="true" monitoring="autodetect">
15.2.2 プログラムによる構成設定 CacheManager の構成情報は、プログラムからも設定できます。そのための専用 API が用意されて
います。以下に、サンプルコードを紹介します。このコードでは、URL を指定して、そこに
CacheManager を作成します。コードは、Terracotta 構成情報を指定します。さらに、「example」という名前の defaultCache を作成します。
Configuration configuration = new Configuration() .terracotta(new TerracottaClientConfiguration().url("localhost:9510")) .defaultCache(new CacheConfiguration("defaultCache", 100)) .cache(new CacheConfiguration("example", 100) .timeToIdleSeconds(5) .timeToLiveSeconds(120) .terracotta(new TerracottaConfiguration())); CacheManager manager = new CacheManager(configuration);
15.3 Terracottaクラスタ構成の要素
Ehcache 構成情報には、Terracotta を利用したキャッシュのクラスタ化を制御する機能を持つ要素
があります。
102
15.3.1 terracotta <cache>要素には、<terracotta>という、省略可能な子要素があります。ehcache.xml ファイルには、
複数の<cache>を定義し、それぞれに異なる構成情報を設定できます。
<terracotta>は、<nonstop>という子要素を 1 つだけ持ちます。詳細は「ノンストップオペレーショ
ン」を参照してください。
<terracotta>には、分散キャッシュのデータの整合性を保証するための属性が用意されています。
該当する属性は以下のとおりです。
• consistency：キャッシュ整合性の保証モードを指定します。デフォルト値の"eventual"は、キ
ャッシュレベルのロックを行わず、パフォーマンスを優先したいときに指定します。キャッシ
ュレベルのロックを行うことで整合性を保証する場合は"strong"を指定します。"eventual"に設
定すると、キャッシュの読み取り時にロックを行いません。このため、パフォーマンスは向上
します。しかし、他の処理がキャッシュを更新できるため、内容が一時的に古くなる場合があ
ります。"strong"に設定すると、他の処理がキャッシュの更新を終えるまで、読み取り処理は
ブロックされます。このため、常に最新の情報を取得できます。しかし、クライアントとサー
バのヒープ領域にロック情報が多数記録されるため、パフォーマンスが大幅に低下する可能性
もあります。
運用開始後は、これらのモード設定を変更できません。変更する場合は、構成情報ファイルを
変更し、ファイルを再ロードする必要があります。プログラムからは、この設定を変更できま
せん。詳細は、パフォーマンスとキャッシュ整合性 を参照してください。
特殊な場合を除き、以下の<terracotta>属性はデフォルト値を変更しないでください。
• clustered： Terracotta が指定したキャッシュをクラスタ化するかどうかを指定します。デフォ
ルト値は"true"（クラスタ化する）です。つまり、この属性を指定しなかった場合、キャッシ
ュはクラスタ化されます。"false"を指定してクラスタ化を無効にすると、他の属性の指定地も
無効になります。
• localCacheEnabled：分散キャッシュデータをローカルキャッシュにコピーするかどうかを指定
します。デフォルト値は"true"（コピーする）です。"true"を指定すると、すべてのキャッシ
ュデータが Terracotta サーバアレイ上に常駐します。ローカルキャッシュを無効にすると、書
き込み処理の多い分散キャッシュのパフォーマンスが向上する場合があります。
• synchronousWrites： Terracotta クライアント（アプリケーションサーバ）からの同期書き込
みを有効にするかどうかを指定します。デフォルト値は"false"（無効にする）です。非同期書
き込み（synchronousWrites="false"）に設定すると、サーバから「トランザクション完了」の
通知を待たずに次の処理へ進みます。このため、パフォーマンスは向上します。ほとんどの場
合、この通知を待つ必要はありません。同期書き込み（synchronousWrites="true"）に設定す
ると、データの整合性は保証されます。しかし、サーバからのトランザクションの通知を待っ
てからクライアントが次の処理を始めることになるため、パフォーマンスは低下します。キャ
103
ッシュの整合性モードが"eventual"の場合や、一括ロード API を使用して一括ロードモードに
なっている場合は、常に非同期書き込みとなります（synchronousWrites="true"を設定しても
無視されます）。
• concurrency： Terracottaサーバアレイによって管理されているサーバストアが利用するマッピ
ングのセグメント数を設定します。値を省略した場合や"0"を指定した場合は、システムが最
適な値を自動的に設定します。この値のチューニングの詳細は処理多重度のチューニングを
参照してください。
Hibernate 利用時は、以下の属性を使用します。
• localKeyCache：ローカルキーを有効化（"true"）または無効化（"false"）します。デフォルト
値は"false"です。BigMemory Max は、アクセス頻度の高いキーを持つキャッシュをクライアン
ト上に配置し、ローカル環境内で参照できるようにします。この機能は読み取りアクセスで使
用されます。利用可能なメモリよりも大きなサイズのキーは、ローカルに配置できません。注
意してください。
• localKeyCacheSize：ローカルに配置するキャッシュの、キーのサイズ（Element 数）を指定し
ます。正の整数を指定してください。「localKeyCache="true"」でない場合、この属性は無視
されます。デフォルト値は"300000"（300,000）です。アプリケーションが必要とする値と環
境の制限を考慮してチューニングしてください。
• orphanEviction：孤立したキャッシュ要素（Element インスタンス）のエビクションを有効化
（"true"）または無効化（"false"）します。デフォルト値は"true"です。「孤立したキャッシュ
要素」とは、Hibernate の 2 次キャッシュから既に破棄されているのに、クラスタの
Terracotta サーバインスタンスに残っている要素を指します。
• orphanEvictionPeriod： Hibernate によるローカル要素エビクションのサイクル数を指定しま
す。Hibernate によるエビクションの回数が指定値に達したら、孤立したキャッシュ要素のエ
ビクションを実行します。デフォルト値は"4"です。値を大きくすると、孤立要素のエビクシ
ョン頻度は減少するため、Terracotta サーバへのデータ再読み込み（fault による移動）の頻度
も減少します。Terracotta サーバ上に残った不要データを積極的に削除したい場合は、逆に値
を小さくします。
デフォルトの動作
<cache>ブロックに<terracotta/>要素（属性を何も指定しない空のタグ）を追加した場合は、以下
を指定したときと同じ動作になります。
<cache name="sampleTerracottaCache" maxEntriesLocalHeap="1000" eternal="false" timeToIdleSeconds="3600"
104
timeToLiveSeconds="1800""> <persistence strategy="distributed"/> <terracotta clustered="true" consistency="eventual" /> </cache>
15.3.2 terracottaConfig <terracottaConfig>要素には、分散キャッシュクライアントが使用するTerracotta構成情報のソース
を指定します。クライアントがクラスタから切断されてTerracottaサーバによるタイムアウトが発
生した場合、クライアントはこの構成情報を使用してクラスタに再接続（rejoin）します。rejoinの詳細は、Terracottaクライアントへの自動再接続（rejoin）を参照してください。
クライアントは、ファイルまたは Terracotta サーバから構成情報をロードします。url 属性には、
「ファイルへのパス」、「システムプロパティ」、または「サーバのアドレスとポート（デフォル
ト値は 9510）」のいずれかを指定します。
Terracotta クラスタ内では、アプリケーションサーバもクライアントの 1 つです。
ヒント：Terracotta のクライアントとサーバ
クライアントの構成情報設定の詳細は、Terracotta構成情報リファレンスの「clients構成情報セク
ション」を参照してください。
url 属性の追加
以下の例に従って<terracottaConfig>に url 属性を追加します。
<terracottaConfig url="<source>" />
<source>には、以下のいずれか 1 つを設定します。
• パス（例：url="/path/to/tc-config.xml"）
• URL（例：url="http://www.mydomain.com/path/to/tc-config.xml）
• システムプロパティ（例：url="${terracotta.config.location}")。システムプロパティは以下のよ
うに定義します。
System.setProperty("terracotta.config.location","10.x.x.x:9510"");
• Terracotta ホストアドレスは<host>:<tsa-port>の形式で記述します（例：url="host1:9510"）。
<host>:<tsa-port>にサーバのアドレスを指定する際は、次の点に注意してください。
– ポート番号のデフォルト値は「9510」です。
105
– 複数サーバによるクラスタの場合は、これらの値をカンマで区切って指定します
（例：url="host1:9510,host2:9510,host3:9510"）。
– Terracotta 構成情報のソースを変更した場合は、既にロードされている構成情報にも変
更を反映させる必要があります。
Terracotta 構成情報の埋め込み
Terracotta 構成情報ファイルの内容を ehcache.xml に登録することも可能です。この場合の例は以
下のとおりです。
<terracottaConfig> <tc-config> <servers> <server host="server1" name="s1"/> <server host="server2" name="s2"/> </servers> <clients> <logs>app/logs-%i</logs> </clients> </tc-config> </terracottaConfig>
15.4 キャッシュサイズの制御
Ehcache のキャッシュ構成情報で指定する属性の一部は、Terracotta によってクラス化されたキャ
ッシュの動作にも影響を与えいます。
構成情報による効果の詳細は、エビクションに関する構成情報の設定を参照してください。
エビクションの詳細は「データの有効期限」を、キャッシュサイズの制御方法は「ストレージ層の
サイズ指定」を参照してください。
15.5 キャッシュエビクションの設定
キャッシュのエビクションとは、構成情報のパラメーターとして設定された条件に従って、キャッ
シュ内の要素をキャッシュから破棄することです。キャッシュのパフォーマンス向上には、適切な
エビクションを設定しておくことが大切です。
エビクションの詳細は「データの有効期限」を、キャッシュサイズの制御方法は「ストレージ層の
サイズ指定」を参照してください。
作成した ehcache.xml は、アプリケーションのクラスパスに保存してください。WAR ファイルを使
用する際は、ehcache.xml を WEB-INF/classes に保存する必要があります。
106
構成情報による効果の詳細は、エビクションに関する構成情報の設定を参照してください。その他
の構成プロパティは、「Terracottaクラスタ構成の要素」を参照してください。
15.6 キャッシュ構成情報ファイル内のプロパティ
詳細は「Terracotta クラスタ構成の要素」を参照してください。
15.7 キャッシュイベントの構成情報
<cache>の子要素の<cacheEventListenerFactory>は、put や update といったキャッシュイベントを
検出するリスナーです。リスナーの検出対象となるイベントは、listenFor 属性で指定します。この
属性には、以下の値の 1 つを指定します。
• local：ローカルノードで発生したイベントを検出します。リモートノード（他のノード）で発
生したイベントは検出しません。
• remote：リモートノードで発生したイベントを検出します。ローカルノードで発生したイベン
トは検出しません。
• all：デフォルト値です。ローカルノードで発生したイベントと、リモートノードで発生したイ
ベントの両方を検出します。
なお、Terracotta クラスタのリモートノードで発生したイベントであっても、イベントリスナーの
スコープ外で発生したイベントは検出できません。以下に、イベントリスナーを登録する構成情報
の例を示します。この例では、リモートとローカルの両方で発生したイベントを検出する
MyCacheListener を登録します。
<cache name="myCache" ... > <!-- Not defining the listenFor attribute for <cacheEventListenerFactory> is by default equivalent to listenFor="all". --> <cacheEventListenerFactory class="net.sf.ehcache.event.TerracottaCacheEventReplicationFactory" /> <terracotta /> </cache>
Terracotta クラスタ全体に通知するキャッシュイベントを使用する場合は、ファクトリとして
net.sf.ehcache.event.TerracottaCacheEventReplicationFactory を使用してください。
Terracottaクラスタのキャッシュイベントの詳細は、Terracottaクラスタのキャッシュイベントを参
照してください。
107
15.8 読み取り時のコピー処理
copyOnRead の効果は、この機能を有効化しなかったときに発生する問題を考えたほうが簡単に理
解できます。copyOnRead を有効化していないキャッシュの場合、以下の比較式（if ステートメン
ト）の結果は常に true となります。
Object obj1 = c.get("key").getValue(); // Assume no other thread changes the cache mapping between these get() operations .... Object obj2 = c.get("key").getValue(); if (obj1 == obj2) { System.err.println("Same value objects!"); }
複数の get()オペレーションが同一オブジェクトへの参照を返すのは、キャッシュがその値に対す
る直接参照を保存しているからです。通常は、デフォルト（copyOnRead=false）の動作でも問題は
起きません。しかし、以下の 2 つのシナリオに該当する場合は問題が起こります。
(1) 複数のクラスローダーがキャッシュを共有している
かつ
(2) オブジェクトの内容が変化する
例えば 2 つの Web アプリケーションがあり、それらが同一の Cache インスタンスにアクセスする
とします（つまり、Ehcache コアのクラスが、共通クラスローダーを利用している状態です）。そ
して、キャッシュ内の値の型に対応するクラスの複製を、各 Web アプリケーションがそれぞれ作
成します（つまり、共通クラスローダーに、複製されたクラスが存在しない状態です）。この状態
のとき、一方の Web アプリケーションがロードしたキャッシュの値に、もう一方の Web アプリケ
ーションがアクセスすると、ClassCastException が発生します。
この問題を解決する方法の 1 つは、複製したクラスを共通クラスローダーにも移植することです。
もう 1 つの方法は、copyOnRead を有効化することです。copyOnRead を有効化しておけば、get()を実行するたびに、一意のオブジェクト参照が作成されます。一意のオブジェクト参照を使用すれ
ば、get()ステートメントは、呼び出し側のスレッドコンテキストローダーを利用して、キャッシュ
の値を取得します。複数のバンドルが共通キャッシュサービスを使用する OSGi 環境でも、この機
能を利用できます。
ほかにも、分散キャッシュで可変オブジェクトを扱うことによって生じる問題があります。以下に、
簡単な例を紹介します。この例では、可変オブジェクト（Foo）がキャッシュに記録されます。
class Foo { int field; }
108
Foo foo = (Foo) c.get("key").getValue(); foo.field++; // foo instance is never re-put() to the cache // ...
Foo インスタンスをキャッシュに再格納しなければ、ローカルキャッシュとクラスタキャッシュは
整合性を失います（ローカルキャッシュだけが変更されます）。キャッシュに影響を与えるのは、
キャッシュを変更するメソッドだけです。したがって、この問題は copyOnRead を有効化すること
で解決します。
なお、copyOnRead を有効化すると、パフォーマンスに悪影響を与えます。これは、get()を実行す
るたびに非シリアル化が実行されるからです。
15.9 インメモリのデータセットに対する堅牢性の設定
BigMemory Max のインメモリのデータの堅ろう性を高めるには、Terracotta の構成情報とアーキテ
クチャー、そして Ehcache 構成情報を合わせて設定します。詳細は、以下のドキュメントを参照し
てください。
• 「ノンストップキャッシュ」： Ehcache ノードがクラスタから切断されたときの、キャッシュ
の動作を設定するための構成情報を解説します。
• 「クラスタへの再接続（rejoin）」：クラスタから切断された Ehcache ノードを、新しいクラ
イアントとしてクラスタに再接続するための構成情報を解説します。
• 「Terracotta の可用性を高めるための構成設定」：ネットワーク障害や Java の GC（ガーベジ
コレクション）に対処するための構成情報と、Terracotta のバックアップサーバに接続する機
能を利用するための構成情報などを解説します。
• 「アーキテクチャー」：フェイルオーバーの機能を備えたクラスタ環境のデザイン方法を解説
します。
15.10 両立しない構成情報
キャッシュをクラスタ化する場合、ehcache.xml ファイルを編集して、Terracotta のクラスタ化技
術と互換性のない機能を無効化する必要があります。キャッシュをクラスタ化するには、そのキャ
ッシュの構成情報の要素に「<terracotta>」または「<terracotta clustered="true">」を記述します。
以下に示す Ehcache 構成情報の要素や属性は、削除または無効化する必要があります。
• レプリケーションに関連する属性（replicateAsynchronously や replicatePuts など）。
109
• MemoryStoreEvictionPolicy 属性には、"LFU"または"LRU"を指定する必要があります。
MemoryStoreEvictionPolicy に"FIFO"を設定すると、IllegalArgumentException 例外が発生しま
す。
15.11 Terracotta管理コンソールからの構成情報の抽出
現在稼働中のクラスタのキャッシュ構成情報を作成または編集する方法は、Editing Cache Configurationを参照してください。
キャッシュ構成情報の編集済みの値を永続化するには、Terracotta 管理コンソールで永続化対象の
構成情報を開いてキャッシュ構成情報ファイルを作成するか、必要な情報をすべて記載したファイ
ルを手動で作成します。そして、クラスタを最後に起動したときに使用した構成情報ファイルを、
この新しいファイルに置き換えます。
16 ノンストップオペレーション
16.1 はじめに
ノンストップ機能は、クラスタから切断された Terracotta クライアントが処理を続行するため、あ
るいはノンストップのタイムアウト値に指定された時間を過ぎたオペレーションを続行するための
機能です。ノード障害に対応することで堅牢性と高い可用性をクラスタにもたらします。これは
SLA（サービス品質保証契約）の達成に役立ちます。
BigMemory Max がノンストップモードに切り替わるトリガの 1 つに、「クラスタオフライン」イ
ベントがあります。なお、クライアントが切断されていなくても、ノンストップインスタンスがノ
ンストップモードに切り替わる場合があります。ノンストップ構成情報のタイムアウトで指定され
た時間内にオペレーションを完了できなかった場合が該当します。また、クライアント上のノンス
トップインスタンスが起動時に TSA（Terracotta サーバアレイ）を検出できなかった場合も、クラ
イアントが切断された場合と同様に、ノンストップモードに切り替わります。
ノンストップ機能は、rejoinと組み合わせて利用できます。
以下のようなシナリオが考えられます。
• オペレーションにタイムアウトを設定するシナリオ。
例えば、次のような状況が発生したとします。まず、メインフレーム上ではなく、BigMemory Max 上のデータを使用しています。SLA では、応答時間が 3 秒以内と定められています。一
時的なネットワークの切断が発生し、キャッシュからの読み取りで遅延が発生しました。タイ
ムアウトを発生させることで、3 秒で復帰します。この結果、メインフレームからデータを参
照します。このシナリオは、ライトスルー、ディスクへの書き込み、同期書き込みなどでも利
用できます。
110
• クラスタのイベントに応答する処理をあらかじめ設定しておき、自動応答するシナリオ。
• ネットワーク障害が発生した際、整合性よりも可用性を優先させるシナリオ。CAP の定理
（「整合性、可用性、ネットワーク障害耐性」は同時に 2 つしか保証できないという定理）に
基づき、整合性よりも可用性を優先させます。
• BigMemory Max の分散キャッシュが利用できなくなった場合でも、ユーザーアプリケーショ
ンに悪影響を与えないシナリオ。
16.2 ノンストップオペレーションの構成設定
ノンストップキャッシュの構成情報は、<cache>ブロックの子要素である<terracotta>に記述します。
以下は、myCache にノンストップの構成情報を設定する例です。
<cache name="myCache" maxEntriesLocalHeap="10000" eternal="false"> <terracotta> <nonstop immediateTimeout="false" timeoutMillis="30000"> <timeoutBehavior type="noop" /> </nonstop> </terracotta> </cache>
キャッシュの<terracotta>ブロックに<nonstop>と記述するだけで、デフォルトの構成情報を設定し
たノンストップキャッシュとして機能するようになります。
16.3 ノンストップのタイムアウトと動作
ノンストップキャッシュの動作は、以下の属性で設定します。
• enabled： Terracotta クライアントがクラスタから切断されたときにノンストップキャッシュ
として機能する（"true"）か、何もしない（"false"）かを設定します。デフォルト値は"true"です。ノンストップ機能を使用する場合は、省略してかまいません。
• immediateTimeout： Terracotta クライアントがネットワーク切断（つまり、クラスタからの
切断）を検出した時点で、直ちにタイムアウトの対応を行う（"true"）か、行わない（"false"）かを指定します。デフォルト値は"false"です。有効化すると、timeoutMillis の値は無視されま
す。したがって、timeoutBehavior で指定した動作が直ちに起動します。
• timeoutMillis：キャッシュオペレーションがタイムアウトになるまでの待機時間を指定します。
単位はミリ秒です。この時間が経過すると、アプリケーションはキャッシュオペレーションで
タイムアウトが発生したと判断します。デフォルト値は 30000（30 秒）です。タイムアウト
が発生したときの動作は timeoutBehavior で設定します。
111
• searchTimeoutMillis：「サーチオペレーション」の待ち時間を指定します。単位はミリ秒です。
この時間が経過しても値を取得できなかった場合はタイムアウトになります。デフォルト値は
30000（30 秒）です。タイムアウトが発生したときの動作は timeoutBehavior で設定します。
<nonstop>>には、<timeoutBehavior>という自己完結型の子要素を指定します。この要素では、タ
イムアウト発生時（直ちにタイムアウト処理を行う設定のときや、timeoutMillis が経過したとき）
の動作を定義します。この動作は、<timeoutBehavior>内の属性 type で設定します。設定できる値
は、以下の 1 つです。
値 動作
exception NonStopCacheException をスローします。デフォルト値です。こ
の例外の詳細は「NonStopCacheException が発生する状況」を参
照してください。
noop get()などの値を取得する処理に対し、null を返します。他のキ
ャッシュ処理は、すべて無視します。Hibernate を利用している
場合は、キャッシュ以外のデータソースを利用できます。このよ
うな場合には"noop"を設定するとよいでしょう。
localReads Terracotta クラスタのキャッシュに対し、キャッシュデータの整
合性を保証せずに読み取り処理を行います。他のキャッシュ処理
は、すべて無視します。Terracotta クラスタ以外のキャッシュに
対するアクセスがあった場合は例外をスローします。
localReadsAndExceptionOnWrite Terracotta クラスタのキャッシュに対し、キャッシュデータの整
合性を保証せずに読み取り処理を行い、書き込み処理では
NonStopCacheException をスローします。他のキャッシュ処理
は、すべて無視します。Terracotta クラスタ以外のキャッシュに
対するアクセスがあった場合は例外をスローします。
16.3.1 ノンストップキャッシュのタイムアウトと動作のチューニング ノンストップキャッシュのタイムアウト値とタイムアウト発生時の動作は、環境に合わせて変更で
きます。
ネットワーク切断への対応
ネットワーク切断が頻繁に発生するような環境では、immediateTimeout を無効化して
timeoutMillis の値を大きくすることで、ネットワーク切断によるタイムアウトを回避します。
短時間のネットワーク切断が頻繁に発生するクラスタで、さらに Terracotta でクラスタ化したキャ
ッシュに対するアクセスの大部分が読み取り処理の場合や、キャッシュ内のデータが古くてもかま
わない場合は、timeoutBehavior に localReads を設定するとよいでしょう。
パフォーマンスの低いキャッシュへの対応
キャッシュのレスポンスが悪い環境でキャッシュの同期書き込み（ライトスルー）が必要な場合は、
timeoutMillis の値を増やすことでタイムアウトの発生を防止してください。アプリケーションに対
112
し、別のデータソースからのデータ取得や exception のスローを強制する場合は、timeoutBehaviorに noop を設定します。
例えば、cache.acquireWriteLockOnKey(key)でロックを設定しているときに、nonstop のタイムアウ
ト値の設定時間を超えたとします。この処理は、単にロックを設定しているだけですが、それでも
キャッシュはノンストップモードに切り替わります。このようなタイムアウトを防止するには、
cache.tryWriteLockOnKey(key, timeout)を使用します。そして、メソッド引数の timeout に、
nonstop のタイムアウト値よりも小さい値を指定します。
一括ロード
一括ロードAPIのnet.sf.ehcache.Ehcache.setNodeBulkLoadEnabled(boolean)を使用してノンストップ
キャッシュの一括ロードを実行した場合は、「nonstopに指定したタイムアウト値」と「一括ロー
ド係数」との乗算結果がタイムアウト値になります（nonstopのタイムアウト値 × 一括ロードの係
数＝一括ロードのタイムアウト値）。この係数のデフォルト値は"10"です。この係数は、以下のよ
うにシステムプロパティのbulkOpsTimeoutMultiplyFactorで変更します。
-Dnet.sf.ehcache.nonstop.bulkOpsTimeoutMultiplyFactor=10
なお、ノンストップ機能を有効化した場合、TMC は乗算係数 bulkOpsTimeoutMultiplyFactor を利用
して計算した値を表示します。クライアント側でこの係数の値を大きくすると、より正確なサイズ
のレポートを取得できるようになります。
この係数を変更すると、メソッド net.sf.ehcache.Ehcache.getAll()、net.sf.ehcache.Ehcache.removeAll()、net.sf.ehcache.Ehcache.removeAll(boolean)、および
net.sf.ehcache.Ehcache.removeAll(boolean)の結果も変わります。
16.4 ノンストップ機能で発生する例外
アプリケーションによるキャッシュへのアクセスは、さまざまな状況で、頻繁に発生します。した
がって、ノンストップキャッシュ使用時は、NonStopCacheException の発生を予測するのが非常に
困難です。以下のセクションでは、NonStopCacheException が発生する状況と、発生した例外の取
り扱い方法に関するガイダンスを紹介します。
16.4.1 NonStopCacheExceptionが発生する状況 クラスタから切断されたクライアントにノンストップキャッシュの構成情報が定義されている場合
は、NonStopCacheException がスローされることがあります。以下の例では、クライアント切断の
発生 30 秒後（あるいは"クラスタオフライン"イベントの検出時）に、この例外が発生します。
<nonstop immediateTimeout="false" timeoutMillis="30000"> <timeoutBehavior type="exception" /> </nonstop>
113
以上の例では、NonStopCache例外のスローを明示的に定義しています。しかし、このような定義で
ないときにも、この例外が発生する場合があります。該当するのは、ロックの設定または解除を実
行しているときにキャッシュがノンストップモードになった場合です。BlockingCache、SelfPopulatingCache、UpdatingSelfPopulatingCacheといった特定のキャッシュ種別や、明示的ロッ
クといった特定のロックAPIは、こうしたロック処理による例外に関係しています。
また、get()処理によってキャッシュ内容の移動（fault による移動）が必要になったときも、
NonStopCacheException が発生します。nonstop 要素のタイムアウトで指定した時間内に
Terracotta サーバアレイがレスポンスを返信できなかった場合も、この例外が発生します。
関連する例外にInvalidLockAfterRejoinExceptionがあります。rejoinによってクライアントが再接続
しているとき、あるいは再接続のあとに発生する例外です（詳細は Terracottaクライアントへの自
動再接続（rejoin）)を参照してください）。この例外は、rejoinによる再接続処理が完了する前に
設定したキャッシュのロックを解放するときに発生します。
確実にロックを解放するため、Ehcache のロック API を使用するアプリケーションのコードでは、
ロックの設定と解除（lock-unlock）操作を try-finally ブロックにカプセル化してください。
myLock.acquireLock();
try { // Do some work.
} finally {
myLock.unlock();
}
ヒント：try-finally ブロックの使用
16.4.2 ノンストップ機能で発生する例外の取り扱い アプリケーションでは、ノンストップ機能の例外を、ほかの例外と同様に処理できます。ノンスト
ップキャッシュの場合、ハンドルされない例外のハンドラ（unhandledException handler）とは、
例えば、効率的な問題の管理のために用意された別スレッドなどを指します。
ノンストップ機能の例外を取り扱う場合は、アプリケーションフレームワークの外側で発生した例
外に特化した Ehcache 用 Decorator を使用します。以下に、Decorator による処理の例を示します。
try { cache.put(element); } catch(NonStopCacheException e) { handler.handleException(cache, element, e); }
114
17 Terracotta分散キャッシュ（BigMemory）のデフォルト設定
17.1 はじめに
Terracotta クラスタ上で動作する Terracotta サーバアレイやクライアントの動作は、プロパティを
利用して制御します。これらのプロパティには、Terracotta 構成情報ファイル（tc-config.xml)）に
定義するものと、BigMemory の構成情報ファイル（ehcache.xml）に定義するものがあります。プ
ログラムを使って設定するプロパティもあります。
このページでは、重要なプロパティの詳細と、それらのデフォルト値を紹介します。なお、最新版
の Terracotta ソフトウェアのデフォルト値は、Terracotta キットに同梱されている XSD（XML Schema Definition）を参照してください。
17.2 Terracottaサーバアレイ
Terracotta クラスタはクライアントとサーバによって構成されます。通常、Terracotta のプロパテ
ィでは、クライアントを「l1」、サーバを「l2」と省略して記述します。
このプロパティは tc-config.xml の先頭に記述します。以下に、プロパティの記述例を示します。
<tc-properties> <property name="l2.nha.tcgroupcomm.reconnect.enabled" value="true" /> <!-- More properties here. --> </tc-properties>
Terracotta サーバアレイの詳細は「Terracotta サーバアレイ」を参照してください。
17.2.1 再接続とログのプロパティ 以下に、再接続のプロパティと、そのデフォルト値を紹介します。これらのプロパティは、
Terracotta の構成情報（tc-config.xml ファイルの<tc-properties>/<property>)要素）で変更します。
プロパティ デフォルト値 説明
l2.nha.tcgroupcomm.reconnect.enabled
true 「l2-l2」（サーバからサーバへ）の再接続を有
効化します。
l2.nha.tcgroupcomm.reconnect.timeout
5000ms 「l2」－「l2」間の接続のタイムアウト値です。
l2.l1reconnect.enabled true 「l1」からサーバへの再接続を有効化します。
l2.l1reconnect.timeout.millis 5000ms 接続のタイムアウトです。この時間が経過する
と、「l1」は切断されます。
l1.max.connect.retries -1 「l1」から「l2」への再接続の最大試行回数で
す。初回および次回以降の再接続の試行に適用
115
されます。「-1」を指定すると、試行回数は無制
限になります。
tc.config.getFromSource.timeout
30000ms ソースからの構成情報の取得で利用するタイム
アウト値です。サーバ上の構成情報にクライア
ントがアクセスするような場合に、この値が利
用されます。アクセスに失敗すると、そのクラ
イアントはクラスタに接続できません。
logging.maxBackups 20 Terracotta ログのバックアップファイル数の上限
値です。
logging.maxLogFileSize 512MB Terracotta ログファイルの最大サイズです。この
値を超えると、別のファイルにログを出力しま
す。
17.2.2 ヘルスチェッカーの許容値 Terracotta サーバ間の切断の耐性（l2 <-> l2）、Terracotta サーバと Terracotta クライアント間の切
断の耐性（l2 -> l1）、Terracotta クライアントと Terracotta サーバ間の切断の耐性（l1 -> l2）を対
象とする、サーバやクライアントを接続するネットワーク障害の耐性は、以下のプロパティに許容
値を定義することで設定します。
「l2」と「l2」間の GC 耐性： 40 秒、ケーブル抜け/ネットワークダウンの耐性： 10 秒
l2.healthcheck.l2.ping.enabled = true l2.healthcheck.l2.ping.idletime = 5000 l2.healthcheck.l2.ping.interval = 1000 l2.healthcheck.l2.ping.probes = 3 l2.healthcheck.l2.socketConnect = true l2.healthcheck.l2.socketConnectTimeout = 5 l2.healthcheck.l2.socketConnectCount = 10
「l2」から「l1」への GC 耐性： 40 秒、ケーブル抜け/ネットワークダウンの耐性： 10 秒
l2.healthcheck.l1.ping.enabled = true l2.healthcheck.l1.ping.idletime = 5000 l2.healthcheck.l1.ping.interval = 1000 l2.healthcheck.l1.ping.probes = 3 l2.healthcheck.l1.socketConnect = true l2.healthcheck.l1.socketConnectTimeout = 5 l2.healthcheck.l1.socketConnectCount = 10
「l1」から「l1」への GC 耐性： 50 秒、ケーブル抜け/ネットワークダウンの耐性： 10 秒
l1.healthcheck.l2.ping.enabled = true l1.healthcheck.l2.ping.idletime = 5000
116
l1.healthcheck.l2.ping.interval = 1000 l1.healthcheck.l2.ping.probes = 3 l1.healthcheck.l2.socketConnect = true l1.healthcheck.l2.socketConnectTimeout = 5 l1.healthcheck.l2.socketConnectCount = 13
17.3 Terracottaクライアント
インメモリデータストアの動作、サイズ、機能は、クライアントの構成情報プロパティで設定しま
す。ここに紹介されていないプロパティは、キャッシュの一括操作などで使用するプロパティです。
特に記載されている場合を除き、プロパティは ehcache.xml で設定します。
17.3.1 一般的な設定値 インメモリデータ内容に影響を与えるプロパティと、それらのデフォルト値を、以下に、紹介しま
す。これらの設定の詳細は「BigMemory Max のドキュメント」を参照してください。
プロパティ デフォルト値 説明
value mode SERIALIZATION
consistency EVENTUAL
XA false
orphan eviction true
local key cache false
synchronous writes false
memory store eviction policy
LRU
ttl 0 0 は無期限という意味です。
tti 0 0 は無期限という意味です。
transactional mode off
persistence strategy none
maxEntriesInCache 0 0 は容量に基づくエビクションが行われないことを意
味します（ただし、定期的なエビクションとリソース
に基づくエビクションは行なわれます）
maxBytesLocalHeap 0
maxBytesLocalOffHeap 0
maxEntriesLocalHeap 0 0 は無制限という意味です。
117
17.3.2 ノンストップキャッシュ クライアントがクラスタから切断されたときのキャッシュの動作を設定するプロパティと、そのデ
フォルト値を以下に紹介します。これらの設定の詳細は「ノンストップキャッシュ」を参照してく
ださい。
プロパティ デフォルト値 説明
enable false
timeout behavior exception
timeout 30000ms
net.sf.ehcache.nonstop.bulkOpsTimeoutMultiplyFactor
10 タイムアウト値の計算に使用する係数です。
removeAll()や getAll()といった一括オペレーションの
タイムアウトの計算に使用します。ノンストップキャ
ッシュ用タイムアウトのデフォルト値は 30 秒です。
したがって、一括オペレーションのタイムアウトは
300 秒になります。デフォルト値はプログラムからも
変更できます。
cache.getTerracottaConfiguration() .getNonstopConfiguration() .setBulkOpsTimeoutMultiplyFactor(10)
17.3.3 一括オペレーション プロパティには、以下に示すデフォルト値を指定します。「Terracotta の構成情報のプロパティ」
を使えば、カスタム値を指定することも可能です。
バッチサイズを大きくすることでスループットを向上できるかもしれません。しかし、より大きな
データのブロックを処理することでリソースの負荷は増え、待機時間が延びる可能性もあります。
プロパティ デフォルト値 説明
ehcache.bulkOps.maxKBSize 1MB putAll や removeAll などの一括オペレーションの
バッチサイズです。
ehcache.getAll.batchSize 1000 getAll オペレーションが一度に読み込む要素の数
です。
ehcache.incoherent.putsBatchByteSize
5MB 一括ロード用のプロパティです。一括ロードオ
ペレーションで一度に読み込むデータの最小サ
イズです。バッチサイズを大きくすると、スル
ープットの向上が期待できます。しかし、処理
するデータブロックが大きくなることでリソー
スの負荷が増し、待機時間が長くなってしまう
可能性もあります。
ehcache.incoherent.putsBatchTimeInMillis
600 ms 一括ロード用のプロパティです。一括ロードオ
ペレーションにおける一括 put 処理の、所要時
間の最大値です。この時間を過ぎると、
Terracotta サーバアレイへの移動（flush）が始
118
まります。
18 BigMemory Max構成情報のリファレンス BigMemory Max は、Ehcache の標準構成情報ファイルを使用して、クラスタ化と整合性の動作、キ
ャッシュデータの最適化、JTA と OSGi のサポートなど、さまざまな設定を行います。
18.1 ノンストップキャッシュ
ノンストップキャッシュは、クラスタから切断されたクライアントがキャッシュ処理を続行するた
め、あるいはノンストップのタイムアウト値に指定された時間を過ぎたキャッシュオペレーション
を続行するための機能です。クライアントがノンストップモードに切り替わるトリガの 1 つに、
「クラスタオフライン」イベントがあります。なお、ノードが切断されていなくても、ノンストッ
プキャッシュがノンストップモードに切り替わる場合があります。ノンストップ構成情報のタイム
アウトで指定された時間内にオペレーションを完了できなかった場合が該当します。
18.1.1 ノンストップキャッシュの構成設定 ノンストップキャッシュの構成情報は、<cache>ブロックの子要素である<terracotta>に記述します。
以下は、myCache にノンストップの構成情報を設定する例です。
<cache name="myCache" maxEntriesLocalHeap="10000" eternal="false"> <persistence strategy="distributed"/> <terracotta> <nonstop immediateTimeout="false" timeoutMillis="30000"> <timeoutBehavior type="noop" /> </nonstop> </terracotta> </cache>
キャッシュの<terracotta>ブロックに<nonstop>と記述するだけで、デフォルトの構成情報を設定し
たノンストップキャッシュとして機能するようになります。
18.1.2 ノンストップのタイムアウトと動作 ノンストップキャッシュの動作は、以下の属性で設定します。
• enabled： Terracotta クライアントがクラスタから切断されたときにノンストップキャッシュ
として機能する（"true"）か、何もしない（"false"）かを設定します。デフォルト値は"true"です。ノンストップ機能を使用する場合は、省略してかまいません。
• immediateTimeout： Terracotta クライアントがネットワーク切断（つまり、クラスタからの
切断）を検出した時点で、直ちにタイムアウトの対応を行う（"true"）か、行わない（"false"）かを指定します。デフォルト値は"false"です。"true"（直ちにタイムアウト処理を実行）を設
119
定すると、timeoutMillis に設定した時間が経過した時点で、クライアントのリクエストがタイ
ムアウトになったと判断されるようになります。
• timeoutMillis：キャッシュオペレーションがタイムアウトになるまでの待機時間を指定します。
この時間が経過すると、アプリケーションはキャッシュオペレーションでタイムアウトが発生
したと判断します。単位はミリ秒です。デフォルト値は 30000（30 秒）です。タイムアウト
が発生したときの動作は timeoutBehavior で設定します。
<nonstop>には、<timeoutBehavior>という自己完結型の子要素を指定します。この要素では、タイ
ムアウト発生時（直ちにタイムアウト処理を行う設定のときや、timeoutMillis が経過したとき）の
動作を定義します。この動作は、<timeoutBehavior>内の属性 type で設定します。設定できる値は、
以下の 1 つです。
値 動作
exception NonStopCacheException をスローします。デフォルト値です。この例外の詳細は
「NonStopCacheException が発生する状況」を参照してください。
noop get()などの値を取得する処理に対し、null を返します。他のキャッシュ処理は、すべ
て無視します。Hibernate を利用している場合は、キャッシュ以外のデータソースを利
用できます。このような場合には"noop"を設定するとよいでしょう。
localReads Terracotta クラスタのキャッシュに対し、キャッシュデータの整合性を保証せずに読
み取り処理を行います。他のキャッシュ処理は、すべて無視します。Terracotta クラ
スタ以外のキャッシュに対するアクセスがあった場合は例外をスローします。
ノンストップキャッシュのタイムアウトと動作のチューニング
ノンストップキャッシュのタイムアウト値とタイムアウト発生時の動作は、環境に合わせて変更で
きます。
ネットワーク切断への対応
ネットワーク切断が頻繁に発生するような環境では、immediateTimeout を無効化して
timeoutMillis の値を大きくすることで、ネットワーク切断によるタイムアウトを回避します。
短時間のネットワーク切断が頻繁に発生するクラスタで、さらに Terracotta でクラスタ化したキャ
ッシュに対するアクセスの大部分が読み取り処理の場合や、キャッシュ内のデータが古くてもかま
わない場合は、timeoutBehavior に localReads を設定するとよいでしょう。
パフォーマンスの低いキャッシュへの対応
キャッシュのレスポンスが悪い環境でキャッシュの同期書き込み（ライトスルー）が必要な場合は、
timeoutMillis の値を増やすことでタイムアウトの発生を防止してください。アプリケーションに対
し、別のデータソースからのデータ取得や exception のスローを強制する場合は、timeoutBehaviorに noop を設定します。
120
例えば、cache.acquireWriteLockOnKey(key)でロックを設定しているときに、nonstop のタイムアウ
ト値の設定時間を超えたとします。この処理は、単にロックを設定しているだけですが、それでも
キャッシュはノンストップモードに切り替わります。このようなタイムアウトを防止するには、
cache.tryWriteLockOnKey(key, timeout)を使用します。そして、メソッド引数の timeout に、
nonstop のタイムアウト値よりも小さい値を指定します。
一括ロードへの対応
「一括ロード API」の net.sf.ehcache.Ehcache.setNodeBulkLoadEnabled(boolean)を使用してノンスト
ップキャッシュの一括ロードを実行した場合は、「nonstop に指定したタイムアウト値」と「一括
ロード係数」との乗算結果がタイムアウト値になります（nonstop のタイムアウト値 × 一括ロード
の係数＝一括ロードのタイムアウト値）。この係数のデフォルト値は"10"です。この係数は、以下
のようにシステムプロパティの bulkOpsTimeoutMultiplyFactor で変更します。
-Dnet.sf.ehcache.nonstop.bulkOpsTimeoutMultiplyFactor=10
なお、ノンストップ機能を有効化した場合、TMC は乗算係数 bulkOpsTimeoutMultiplyFactor を利用
して計算した値を表示します。クライアント側でこの係数の値を大きくすると、より正確なサイズ
のレポートを取得できるようになります。
net.sf.ehcache.Ehcache.getAll()メソッド、net.sf.ehcache.Ehcache.removeAll()メソッドまたは
net.sf.ehcache.Ehcache.removeAll(boolean)メソッドを実行した場合にも、この係数が使用されます。
NonStopCacheException が発生する状況
クラスタから切断されたクライアントにノンストップキャッシュの構成情報が定義されている場合
は、NonStopCacheException がスローされることがあります。以下の例では、クライアント切断の
発生 30 秒後（あるいは「クラスタオフライン」イベントの検出時）に、この例外が発生します。
<nonstop immediateTimeout="false" timeoutMillis="30000"> <timeoutBehavior type="exception" /> </nonstop>
以上の例では、NonStopCache 例外のスローを明示的に定義しています。しかし、このような定義
でないときにも、この例外が発生する場合があります。該当するのは、ロックの設定または解除を
実行しているときにキャッシュがノンストップモードになった場合です。BlockingCache、SelfPopulatingCache、UpdatingSelfPopulatingCache といった特定のキャッシュ種別や、「明示的ロ
ック」といった特定のロック API は、こうしたロック処理による例外に関係しています。
また、get()処理によってキャッシュ内容の移動（fault による移動）が必要になったときも、
NonStopCacheException が発生します。nonstop 要素のタイムアウトで指定した時間内に
Terracotta サーバアレイがレスポンスを返信できなかった場合も、この例外が発生します。
121
関連する例外に InvalidLockAfterRejoinException があります。rejoin によってクライアントが再接
続しているとき、あるいは再接続のあとに発生する例外です（詳細は「Terracotta クライアントへ
の自動再接続（rejoin）」)を参照してください）。この例外は、rejoin による再接続処理が完了す
る前に設定したキャッシュのロックを解放するときに発生します。
確実にロックを解放するため、Ehcache のロック API を使用するアプリケーションのコードでは、
ロックの設定と解除（lock-unlock）操作を try-finally ブロックにカプセル化してください。
myLock.acquireLock();
try { // Do some work.
} finally {
myLock.unlock();
}
ヒント：try-finally ブロックの使用
18.2 エビクションに関する構成情報の設定
クラスタのリソースを効率よく運用するには、キャッシュ要素のエビクションを正しく設定するこ
とが肝心です。キャッシュ要素のエビクションと有効期限は密接に関係しています。ただし、有効
期限を迎えた要素が、直ちにエビクションで破棄されるとは限りません。また、エビクションで破
棄された要素が、常に有効期限切れの要素であるとも限りません。キャッシュ要素のエビクション
は、リソースと構成情報の制約によって発生します。なお、Terracotta クライアントで有効期限の
切れたキャッシュ要素に対して put()や get()などのオペレーションを実行すると、この要素はエビ
クションによって破棄されます（これを「インラインエビクション」と呼ぶ場合があります）。
Terracotta サーバアレイは、完全なキーのリスト（および完全な値のリスト）を保持しています。
その一方でクライアントは、サーバアレイから fault によって移動したキーと値のサブセットだけ
を保持しています。
一般的に、有効期限の切れたキャッシュ要素はエビクションによって破棄されます。正確にいうと、
その要素に対する get()や put()などのオペレーションが実行された時点で、低速なデバイスへの移
動（flush による移動）が発生します。また、クライアントの特定のストレージ層が一杯になった
場合や、クライアントのメモリが不足してきた場合にも、flush による移動が発生します。この場
合の flush では、有効期限の切れた要素を最初に移動し、それから有効期限の切れていない要素を
移動します。このように、構成情報の設定に従ってエビクションが発生し、実メモリが解放されま
す。
122
エビクションの詳細は「データの有効期限」を、キャッシュサイズの制御方法は「ストレージ層の
サイズ指定」を参照してください。
クライアントで flush による移動が発生しても、そのキャッシュ要素がサーバアレイからエビクシ
ョンで破棄されるわけではありません。サーバは、有効期限の切れた要素に対し、エビクションを
実行します。これらの要素が実際に破棄されるのは、BigMemory 用に割り当てられているサーバメ
モリの容量が減ってきたときです。以下の条件があてはまる場合は、有効期限を迎えていない要素
もエビクションの対象になります。
• TTI（Time To Idle）または TTL（Time To Live）を設定していない、あるいは、これらの値を
無期限（0）に設定したキャッシュ要素の場合。なお、キャッシュに eternal フラグを設定し
た場合も、TTI や TTL の有効期限は無期限になります（別の値を指定しても無視されます）。
• キャッシュの要素が、どの Terracotta クライアントにも存在しない場合。このような要素は
「孤立した要素」として扱われます。この要素をエビクションで破棄すると、クライアントか
らのリクエストがあったときは、SOR（System Of Record）から内容を再ロードする必要があ
ります。
Terracotta サーバアレイのエビクションの詳細は、「自動リソース管理」を参照してください。
18.3 パフォーマンスとキャッシュ整合性
キャッシュの整合性モードは、構成情報または API が提供するメソッドで設定します。データ整合
性とアプリケーションパフォーマンスのバランスに配慮して、クラスタ化されたキャッシュの動作
を設定してください。キャッシュの整合性モードに指定できる値は、以下の 1 つです。
• Eventual：「最終的に」キャッシュの整合性を保証するモードです。キャッシュ要素の更新が
発生すると、一時的にキャッシュ内容の整合性が崩れます。しかし、キャッシュ要素へのアク
セスのパフォーマンスは飛躍的に向上します。このモードは Ehcache の構成情報ファイルで設
定します。プログラムからの変更はできません。詳細は「<terracotta>」の"consistency"属性
を参照してください。
• Strong：「常に」クラスタ全体のキャッシュの整合性を保証するモードです。キャッシュ要素
の読み込みは、すべての書き込み処理が完了してから実行されるため、常に最新のデータを取
得できます。複数のキャッシュ書き込み処理が発生した場合は、それぞれが独立したトランザ
クションとして処理されます。このモードを設定すると、トランザクションの整合性は最大限
に保証されます。しかし、パフォーマンスは大きく低下します。このモードは Ehcache の構
成情報ファイルで設定します。プログラムからの変更はできません。詳細は「<terracotta>」の"consistency"属性を参照してください。
• 一括ロード：キャッシュの一括ロード機能に特化したモードです。キャッシュ内容をロードす
る際、ロックや標準のエビクションが発生しないため、パフォーマンスの低下も発生しません。
このモードの動作は「eventual」モードに似ています。しかし、一括処理であり、書き込みの
123
スピードは高く、整合性の保証は低くなっています。このモードは、一括ロード API を使用し
たとき自動的に設定されます（詳細は「一括ロード API」を参照してください）。API の利用
が終了すると、キャッシュの整合性モードは、それまでに設定されていた値（"eventual"また
は"strong"）に戻ります。
キャッシュの整合性モードは、使用するアプリケーションの性質に合わせて設定してください。起
動時など、一括ロードによってキャッシュ内容のリフレッシュを行う際は、自動的に一括ロードモ
ードに切り替わります。
ほかにも、キャッシュの整合性に影響を与える API や構成情報があります。
• 明示的ロック：この API は、キャッシュ内の特定の要素に対し、クラスタ全体（アプリケーシ
ョンレベル）のロックを行うためのメソッドを提供します要素をロックで保護すると、クラス
タ全体における整合性が常に保証されるようになります。キャッシュの整合性モードが
"strong"のときに明示的ロックを使用すると、すべてのキャッシュオペレーションが、独立し
たトランザクションとして扱われます。キャッシュの整合性モードが"eventual"のときに明示
的ロックを使用すると、明示的ロックで保護されたキャッシュオペレーションだけが、独立し
たトランザクションとして扱われます。明示的ロックは、キャッシュ要素を細かい単位でロッ
クします。それでも、処理の競合、スレッドのブロック、クラスタのロック管理で生じるパフ
ォーマンスのオーバーヘッドといった問題が発生する可能性があります。詳細は「明示的ロッ
ク」を参照してください。
• アンロックリード：キャッシュをロックせずに読み取る処理です。Decorator による拡張機能
（UnlockReadsView）によって実現します。キャッシュの整合性モードが"strong"でない場合、
この Decorator 拡張は使用できません。UnlockReadsView を利用すると、読み取りロック要求
をバイパスできるため、パフォーマンスが向上します。詳細は「整合性を保証したキャッシュ
に対するアンロックリード（UnlockedReadsView）」を参照してください。
• 不可分メソッド： put()などの書き込み処理で発生する可能性のある競合を完全に排除し、書
き込み時の整合性を常に保証します。Cache.putIfAbsent(Element element)メソッドと
Cache.replace(Element oldOne, Element newOne)メソッドが該当します。キャッシュの整合性
モードが"eventual"のキャッシュに対してこれらのメソッドを使用すると、競合条件を防止で
きません。このため、これらのメソッドは「UnsupportedOperationException」をスローしま
す。"eventual"のキャッシュから正しい戻り値を取得するには、「キャッシュ Decorator」の
StronglyConsistentCacheAccessor を使用するか、ロック（「明示的ロック」を参照）を使用し
てください。StronglyConsistentCacheAccessor は、Decorator による拡張版の不可分メソッド
を利用してロック処理を行ないます。ただし、ロックを使用するとパフォーマンスは低下しま
す。
• 一括ロードメソッド：「putAll(), getAll(), removeAll()」は、一括ロードモードと同様にキャッ
シュを取り扱う高速なメソッドです。ただし、キャッシュ内容の整合性を保証しない状態が一
124
時的に発生します。これらは、整合性モードが「strong」の場合でも利用できます。これらを
利用できるのであれば、一括ロードモードに頼る必要はありません。
キャッシュの整合性とパフォーマンスのバランスを最適化するには、キャッシュの整合性に
"eventual"を設定しておき、アプリケーションがクラスタ全体のキャッシュの整合性を必要とする
ときだけ適切なロックを利用するとよいでしょう。
18.4 Terracottaクラスタのキャッシュイベント
特定のキャッシュオペレーションを実行すると、キャッシュイベントの通知が発行されます。
• エビクション：クライアント上でエビクションが発生すると、そのクライアントはエビクショ
ンイベントを通知します。Terracotta サーバ上でエビクションが発生した場合、サーバは任意
のクライアントにエビクションを通知します。
• 書き込み：クライアント上で put()が実行されると、そのクライアントは書き込みイベントを
通知します。
• 更新：キャッシュの高速再起動を有効化しているときにクライアントで更新（put）が実行さ
れると、そのクライアントは書き込みイベントを通知します。
• 孤立した要素のエビクション：「孤立した要素」とは、Terracotta サーバアレイ上だけに存在
するキャッシュ要素のことです。孤立した要素のエビクションが発生すると、サーバは任意の
クライアントにエビクションイベントを通知します。
キャッシュイベントのスコープに関する構成設定の詳細は、「キャッシュイベントの構成情報」を
参照してください。
18.4.1 キャッシュ更新イベントの取り扱い キャッシュ要素の書き込みまたは更新を行うと、キャッシュは書き込み(put)イベントの通知を発行
します。書き込み（put）と更新（update）を区別して扱う必要がある場合は、put()オペレーショ
ンを実行する前に、そのキャッシュ要素が存在するかどうかを確認します。
if (cache.containsKey(key)) { cache.put(element); // Action in the event handler on replace. } else { cache.put(element); // Action in the event handler on new puts. }
他の処理との競合を防ぐには、これらの if ブロックを明示的ロックで保護します（方法は「明示的
ロック」を参照してください）。ほかに、不可分メソッドである putIfAbsent()でキャッシュ要素の
存在を確認する方法もあります。
125
if((olde = cache.putIfAbsent(element)) == null) { // Returns null if successful or returns the existing (old) element. // Action in the event handler on new puts. } else { cache.replace(old, newElement); // Returns true if successful. // Action in the event handler on replace. }
以上の方法（または類似する回避策）を利用できないときは、キャッシュ更新で更新イベントが発
生するように設定します。これは、Terracotta 構成情報ファイル（デフォルトでは tc-config.xml）の先頭のプロパティ ehcache.clusteredStore.checkContainsKeyOnPut で設定します。なお、この設定
は、Terracotta サーバアレイを起動する前に実施する必要があります。
<tc-properties> <property name="ehcache.clusteredStore.checkContainsKeyOnPut" value="true" /> </tc-properties>
この設定を行うと、パフォーマンスは大幅に低下するので注意してください。
18.5 高可用性を優先するキャッシュ構成
Enterprise Ehcache のキャッシュは、HA（高可用性）を実現するため、以下の機能を提供していま
す。
• Non-blocking キャッシュ：この機能は「ノンストップキャッシュ」とも呼びます。Terracottaクライアントがクラスタから切断されたこと（clusterOffLine イベント）を検出する機能です。
この機能は、構成情報の属性を使用して有効化します。イベント検出時のアクションも、構成
情報で設定します。詳細は「ノンストップキャッシュ」を参照してください。
• 再接続（rejoin）： Terracotta クライアントがクラスタから切断されたあと、再びクラスタに
再接続する機能です。このために、再接続が可能な状態になったこと（clusterOnLine イベン
ト）を検出します。この機能は、構成情報の rejoin 属性で有効化します。詳細は「Terracottaクライアントへの自動再接続（rejoin）」を参照してください。
Terracotta クラスタの可用性を高める方法の詳細は、「Terracotta クラスタの可用性を高めるため
の構成設定」を参照してください。
18.5.1 Terracottaクライアントへの自動再接続（rejoin） Enterprise Ehcache を利用している Terracotta クライアントがクラスタから強制的に切断されるこ
とを「eject」と呼びます。クラスタの HA（高可用性）関連の構成情報で設定したタイムアウト値
よりも、ネットワーク通信からの切断時間が長くなったときに、この状態が発生します。ほかにも、
クライアントマシン上で長時間の GC（ガーベジコレクション）が発生した場合も、この状態が発
生します。
126
構成情報を設定することで、クライアントが eject で切断したあと、クラスタに自動再接続できる
ようになります。このような再接続を「rejoin」と呼びます。ノンストップキャッシュの構成を設
定しておけば、eject による切断のあとも、クラスタは処理を継続できます。そして、clusterOnlineイベントを検出したら、rejoin による再接続の処理を開始します。
rejoin 機能を使用する際は、以下の注意が必要です。
• ノンストップでないキャッシュを 1 つでも管理している CacheManager では、rejoin の再接続
を利用できません。CacheManager が管理しているキャッシュの中に、ノンストップでないキ
ャッシュが存在すると、rejoin の初期化処理で例外が発生します。プログラムで作成したノン
ストップでないキャッシュを CacheManager が扱っている場合にも例外が発生します。
• クライアントは、新しいメンバーとしてクラスタに再接続します。このとき、クラスタ上のキ
ャッシュとの不整合やキャッシュの無応答を防止するため、キャッシュの内容をすべてクリア
します。
• rejoin の処理が完了する前に開始したノンストップキャッシュの処理が、rejoin 完了前に完了
しない場合があります。ほとんどの場合、該当するノンストップ処理は不要なものです。これ
らは NonStopCacheException を起こします。
• rejoin を有効化していない Terracotta クライアントの JVM で、rejoin を有効化した Enterprise Ehcache クライアントが動作している場合、rejoin を有効化したクライアントだけが再接続の
対象になります。この場合、rejoin を有効化していないクライアント上で動作しているアプリ
ケーションの動作は保証されません。
• rejoin によってクライアントが再接続すると、そのクライアント内で clusterRejoined イベント
の通知が発行されます。
rejoin の構成設定
デフォルト状態では、rejoin 機能が無効化されています。Enterprise Ehcache クライアントの rejoin機能を有効化するには、以下のように操作します。
1. rejoin を有効化する Ehcache 構成情報ファイルを開き、「すべてのキャッシュ情報がノンスト
ップ機能を有効化している」ことを確認します。
2. 「ノンストップ機能を利用しないキャッシュをアプリケーションが生成しない」ことを確認し
てください。
3. クライアントの<terracottaConfig>要素に、rejoin 属性を指定します。
<terracottaConfig url="myHost:9510" rejoin="true" />
<terracottaConfig>の構成設定の詳細は、「configuration reference」を参照してください。
127
18.6 トランザクション型キャッシュの利用方法
トランザクション型キャッシュとは、キャッシュに安全性を組み込み、外部のデータストアとキャ
ッシュ内容との同期を保証する仕組みです。Enterprise Ehcache のキャッシュは、JTA（Java Transaction API）の規格に完全準拠した XA リソースです。したがって、キャッシュ機能の必要な
JTA アプリケーションや、SOR（System Of Record）との整合性を保証する永続キャッシュが必要な
状況でも利用できます。
トランザクション型のキャッシュに対する書き込み処理は、すべてトランザクション化されます。
このためのオーバーヘッドが生じるため、非トランザクション型のキャッシュよりもパフォーマン
スは低下します。トランザクション型キャッシュには、以下の制限があります。
• データへのアクセスは、読み取り専用アクセスを含め、すべてトランザクションになります。
データへのアクセスは、すべて begin()および commit()ステートメントの中に記述する必要が
あります。ただし、ある一定の条件下では、これを省略できます。詳細は、「Ehcache のトラ
ンザクション」を参照してください。
• copyOnRead と copyOnWrite を有効化しておく必要があります。これらは、<cache>の属性で
指定します。デフォルト値は"false"です。"true"を設定してください。
• キャッシュの整合性モードを strong にします。トランザクション型キャッシュとして使用す
るキャッシュの consistency 属性に"strong"を設定してください。
• ノンストップキャッシュをトランザクション型にする場合は、トランザクションモード
（transactionalMode 属性）に"xa_strict"を指定します。それ以外のモードを指定したキャッシ
ュには、子要素<nonstop>を指定できません。
• トランザクション型キャッシュに対し、Decorator による拡張機能の UnlockedReadsView を利
用した場合、取得したデータの整合性は保証できません。UnlockedReadsView を利用しない
put()や get()などのオペレーションは問題ありません。
• トランザクション型キャッシュに記録するオブジェクトの equals()と hashCode()はオーバーラ
イドしてください。equals()と hashCode()をオーバーライドできない場合は、「Element 比較
機能の実装」を参照してください。
トランザクション型キャッシュには、3 種類のモードが用意されています。
• Strict XA： XA トランザクションを完全にサポートするモードです。JTA を完全にサポートし
ていないトランザクションマネージャーとの互換性は保証されません。
• XA：一般的な JTA コンポーネントのほとんどをサポートするモードです。ほとんどのトラン
ザクションマネージャーとも互換性があるはずです。Strict XA モードと違い、リカバリー機能
がありません。したがって、障害発生時はデータベースとの同期が保証されません。ただし、
キャッシュデータそのものの完全性は保証されます。
128
• Local：ローカルストアに記録するローカルトランザクションを提供するモードです。ほかの
トランザクションモードよりも高速です。このモードではトランザクションマネージャーを使
用しません。また、リモートのデータソースとも同期しません。障害発生時のキャッシュの完
全性は保証されています。
XA モードと Local モードのキャッシュでは、土台となるデータソースに対し、悲観的ロックを用
いた同期書き込みを行います。特定の条件が重なるとデッドロックが発生し、処理が止まります。
この結果、トランザクションのタイムアウトが発生し、DeadLockException が発生します。コミッ
トは実行されません。したがって、アプリケーションは、DeadLockException（および
TransactionException）をキャッチし、rollback()を呼び出すようにしてください。デッドロックが
発生すると、パフォーマンスは大きく低下します。デッドロックが頻繁に発生する場合は、アプリ
ケーションのコードを見直してください。そして、複数スレッドからの同一データに対する書き込
みの競合を防止する策を施してください。
注意：デッドロック
以下のセクションでは、これら 3 種類のモードを詳しく紹介します。
18.6.1 Strict XA（JTAの全機能のサポート） Ehcache を XA リソースとして利用する場合は、以下の性質に注意が必要です。
• 分離レベルは ReadCommitted です。
• キャッシュの土台になるデータソースには非同期書き込みを行います。したがって、更新によ
って不整合が生じる可能性があります。ロックの仕組みは楽観的ロックです。commit()で不整
合が見つかると RollbackException が発生します。すると Ehcache は、トランザクションマネ
ージャーに対してロールバックを指示します。
• JDBC や JMS といった、他のリソースと共存できます。
• リソース内のデータと他の XA リソースとの整合性を、常に保証します。
• キャッシュごとに構成情報を設定できます（トランザクション型キャッシュと非トランザクシ
ョンキャッシュの両方を、同時に利用できます）。
• トランザクションに自動参加します。
• スタンドアロンでも使用可能ですが、Hibernate などのフレームワークに統合することも可能
です。
• Atomikos、Bitronix、JBoss、WebLogic など、ほとんどの一般的なトランザクションマネージ
ャーとのテストを実施済みです。
129
Enterprise Echcache for Hibernate が提供するトランザクション型キャッシュとの連携方法は、「ト
ランザクション型キャッシュのセットアップ」を参照してください。
構成
Enterprise Ehcache を JTA トランザクションに参加できる XA リソースとして設定するには、構成
情報<cache>に以下の属性を設定します。
• transactionalMode="xa_strict"
• copyOnRead="true"
• copyOnWrite="true"
さらに、<cache>の子要素である<terracotta>に、以下の属性を設定します。
• valueMode="serialization"
• clustered="true"
以下は、strict XA モードに設定したキャッシュを JTA トランザクションに追加するための例です。
<cache name="com.my.package.Foo" maxEntriesLocalHeap="500" eternal="false" copyOnRead="true" copyOnWrite="true" consistency="strong" transactionalMode="xa_strict"> <persistence strategy="distributed"/> <terracotta clustered="true" valueMode="serialization" /> </cache>
データベースなど、このトランザクションに参加するすべての XA リソースにも、XA に準拠した構
成設定を行う必要があります。
使用方法
トランザクション内では、これらのトランザクション型キャッシュに対し、アプリケーションが直
接アクセスできます。トランザクション型キャッシュにアクセスできるのは、トランザクションマ
ネージャーが新しいトランザクションを開始してから、そのトランザクションを終了させるまでの
間です。
以下に例を示します。
130
... myTransactionMan.begin(); Cache fooCache = cacheManager.getCache("Foo"); fooCache.put("1", "Bar"); myTransactionMan.commit(); ...
複数のトランザクションがキャッシュを更新すると、XA トランザクションに失敗する場合があり
ます。詳細は、「不可分メソッドを利用する XA コミット障害の防止」を参照してください。
18.6.2 XA（基本JTAのサポート） "xa"モードに設定したトランザクション型キャッシュは、基本 JTA オペレーションをサポートしま
す。XA の構成方法と利用方法は、ローカルトランザクションと同じです（「Local（ローカルトラ
ンザクション）」)を参照）。ただし、"xa"モードではトランザクションマネージャーが必要になる
点と、キャッシュが JTA トランザクションに参加できる点が異なります。
XA モードで Atomikos を使用する際は、Atomikos 構成情報に
com.atomikos.icatch.threaded_2pc=false を指定してください。特定の条件が重なると、Atomikos の
バグによって、意図しないロールバックが発生することがあります。前述の構成情報は、このロー
ルバックを防止します。
注意：トランザクションマネージャー「Atomikos」
以下は、XA モードに設定したキャッシュを JTA トランザクションに追加するための例です。
<cache name="com.my.package.Foo" maxEntriesLocalHeap="500" eternal="false" copyOnRead="true" copyOnWrite="true" consistency="strong" transactionalMode="xa"> <persistence strategy="distributed"/> <terracotta clustered="true" valueMode="serialization" /> </cache>
データベースなど、このトランザクションに参加するすべての XA リソースにも、XA に準拠した構
成設定を行う必要があります。
131
18.6.3 Local（ローカルトランザクション） ローカルトランザクションのキャッシュ（transactionalMode="local"属性を設定した"cache")は、
Enterprise Ehcache のコアアプリケーションが提供する API を利用して、ローカルストアへの書き
込みを行います。ローカルトランザクションには、以下の特徴があります。
• リカバリーは、キャッシュ要素へのアクセス時に実行されます。
• キャッシュを更新すると、その土台となるストア領域も直ちに更新されます。
• コミット処理のとき、その土台となるストア領域に対する get()などの読み込みオペレーショ
ンは、ロックによって禁止されます。
ローカルトランザクションを行う場合は、トランザクションマネージャーのインスタンスではなく、
TransactionController のインスタンスを作成してください。
TransactionController txCtrl = myCacheManager.getTransactionController(); ... txCtrl.begin(); Cache fooCache = cacheManager.getCache("Foo"); fooCache.put("1", "Bar"); txCtrl.commit(); ...
現在のトランザクションを実行したスレッドのロールバックを行う場合は、rollback()を呼び出しま
す。
現在のスレッドによって実行中のトランザクションのステータスを確認するには、次のメソッドを
呼び出します。TransactionController.getCurrentTransactionContext()。この戻り値を確認してくだ
さい。null 以外の値は、現行スレッドのトランザクションが既に開始していることを意味します。
ヒント：現行スレッドのトランザクションのステータスを確認する方法
コミットの失敗とタイムアウト
トランザクションでタイムアウトが発生すると、コミットオペレーションは失敗します。タイムア
ウト値をチューニングするには、タイムアウト値を取得してから設定します。
int currentDefaultTransactionTimeout = txCtrl.getDefaultTransactionTimeout(); ... txCtrl.setDefaultTransactionTimeout(30); // in seconds -- must be greater than zero.
タイムアウトそのものを回避するには、以下のバージョンの commit()を使用します。
132
txCtrl.commit(true); // "true" forces the commit to ignore the timeout.
18.6.4 不可分メソッドを利用するXAのコミット障害の防止 複数のトランザクションがキャッシュを更新すると、XA トランザクションに失敗する場合があり
ます。以下のコードを実行したとき、別のトランザクションが同一キー（"1"）に同時に書き込み
を実行して先にコミットを発行してしまうと、このコードの最後のコミット処理は失敗します。
... myTransactionMan.begin(); Cache fooCache = cacheManager.getCache("Foo"); fooCache.put("1", "Bar"); myTransactionMan.commit(); ...
このようなコミット障害を防止する方法の 1 つに、Cache.replace()など、不可分な書き込みメソッ
ドを利用する方法があります。
myTransactionMan.begin(); int val = cache.get(key).getValue(); // "cache" is configured to be transactional. Element olde = new Element (key, val); if (cache.replace(olde, new Element(key, val + 1)) { myTransactionMan.commit(); } else { myTransactionMan.rollback(); }
ほかにも、Cache.putIfAbsent(Element element)という不可分な書き込みメソッドがあります。この
メソッドは、新規書き込み（つまり、既存のキャッシュ要素が存在しない状態での書き込み）が成
功すると null を返します。既存の要素が存在する場合は、その要素を返します（この場合、書き込
みは実行されません）。不可分メソッドでは、キャッシュ要素（Element インスタンス）に null を指定できません。また、キーの値にも null を指定できません。
18.6.5 Element比較機能の実装 すべてのトランザクション型キャッシュで不可分メソッドの Cache.removeElement(Element element)または Cache.replace(Element old, Element element)を完了させるには、element の内容を比
較する必要があります。このためには、キャッシュに記録されている全オブジェクトの equals()とhashCode()をオーバーライドしてください。
アプリケーションでメソッドをオーバーライドすることが難しい場合は、デフォルトの比較メソッ
ドを使用します（net.sf.echache.store.DefaultElementValueComparator）。あるいは、ユーザー定義
の比較メソッドを用意し、それを構成情報の<elementValueComparator>に指定する方法もあります。
<cache name="com.my.package.Foo" maxEntriesLocalHeap="500"
133
eternal="false" copyOnRead="true" copyOnWrite="true" consistency="strong" transactionalMode="xa"> <elementValueComparator class="com.company.xyz.MyElementComparator" /> <persistence strategy="distributed"/> <terracotta clustered="true" valueMode="serialization" /> </cache>
ユーザー定義の比較メソッドは、net.sf.ehcache.store.ElementValueComparator の実装として作成し
てください。
ユーザー定義の比較メソッドを実装した場合は、構成情報ではなくプログラム側で明示的に呼び出
してもかまいません。
18.7 OSGiとの連携
OSGi コンポーネントとして利用する Enterprise Ehcache には、以下の属性を指定します。
<cache ... copyOnRead="true" ... > ... <terracotta ... clustered="true" ... /> ... </cache>
OSGi バンドル使用時は、以下の JAR ファイルが必要です（以下は Terracotta 3.6.2 キットで使用さ
れているバージョンを示しています）。
• ehcache-ee-2.7.0.jar
• terracotta-toolkit-runtime-ee-4.0.0.jar
• slf4j-api-1.6.6.jar
• slf4j-nop-1.6.1.jar
あるいは、適切なログバインディングを使用してください。
ディレクトリ構造は以下のようにします。
-- net.sf.ehcache | | - ehcache.xml |- ehcache-ee-2.7.0.jar
134
| |- terracotta-toolkit-runtime-ee-4.0.0.jar | | - slf4j-api-1.6.6.jar | | - slf4j-nop-1.6.6.jar | | - META-INF/ | - MANIFEST.MF
マニフェストファイルの例は以下のとおりです。
Manifest-Version: 1.0 Export-Package: net.sf.ehcache;version="2.7.0" Bundle-Vendor: Terracotta Bundle-ClassPath: .,ehcache-ee-2.7.0.jar,terracotta-toolkit-runtime-ee-4.0.0.jar,slf4j-api-1.6.6.jar,slf4j-nop-1.6.6.jar Bundle-Version: 2.7.0 Bundle-Name: EHCache bundle Created-By: 1.6.0_15 (Apple Inc.) Bundle-ManifestVersion: 2 Import-Package: org.osgi.framework;version="1.3.0" Bundle-SymbolicName: net.sf.ehcache Bundle-RequiredExecutionEnvironment: J2SE-1.5
利用中の環境と互換性のあるバージョンを使用してください。
バンドルを作成するには、net.sf.ehcache ディレクトリで以下のコマンドを実行します。
jar cvfm net.sf.ehcache.jar MANIFEST.MF *
19 BigMemory APIの主なクラスとメソッド
19.1 はじめに
BigMemory はユーザー向けデータアクセス API に Ehcache を使用しています。Ehcache の中でも、
以下のクラスを主に使用しています。
• CacheManager
• Cache
• Element
135
以上のクラスが、BigMemory API のコアとなっています。このドキュメントでは、これらのクラス
と、BigMemory API の主要なコンポーネントを紹介します。
アプリケーションが Ehcache の API から BigMemory を使用すると、論理的なデータセットを管理
するため、CacheManager がインスタンス化されます。（なお、Ehcache API が扱う Cache オブジェ
クトは、キャッシュデータだけではなく、あらゆるデータの保存に使用されます。）これらのデー
タセットは、「名前-値」のペアで、Element と呼ばれます。
これら主要なコンポーネントの論理的な表現のほとんどは、以下に記載するクラスが実体化します。
プログラムから Ehcache へアクセスする場合は、これらのクラスメソッドを使用します。
19.2 CacheManager CacheManager は、キャッシュを管理するためのクラスです。キャッシュの作成、アクセス、削除
は、すべて CacheManager によって制御します。
19.2.1 CacheManagerの作成モード CacheManagerには 2 つの作成モードがあります。「シングルトン」と「インスタンス」です。1 つ
のJVMの中で、両方のモードの混在が可能です。しかし、1 つのJVMの中には、重複する名前の
CacheManagerを作成できません。シングルトンでないCacheManagerを作成するCacheManager()コンストラクタでこのルールに違反すると、NullPointerExceptionが発生します。使用するコードが同
一JVM内に複数の同名CacheManagerを作成する可能性がある場合は、staticのCacheManager.create()メソッドを使用して、この例外を回避してください。このメソッドは、同名のCacheManagerがJVMに存在する場合、常に名前付き（あるいはデフォルトの名前なし）のCacheManagerを返します。名
前付き（またはデフォルトの名前なし）CacheManagerが存在しない場合は、CacheManager.create()メソッドが作成します。
シングルトンの場合に CacheManager.create(...)を呼び出すと、シングルトン CacheManager が存在
する場合は、それを構成済みの名前と一緒に返します。存在しない場合は構成情報から取得した情
報を使用して CacheManager を作成します。
構成情報を利用する場合は CacheManager.newInstance(...)メソッドを使用します。このメソッドは、
構成情報を解析し、既存の名前付き CacheManager を取得します。存在しない場合は、その
CacheManager を新規に作成します。
CacheManager を作成するメソッドの一覧を以下に記載します。
• CacheManager.newInstance(Configuration configuration)： configuration の内容を使用して
CacheManager を新規作成します。指定された名前の CacheManager が存在する場合は、その
CacheManager を返します。
• CacheManager.create()：デフォルトの構成情報を使用してシングルトンの CacheManager を新
規作成します。あるいは既存のシングルトン CacheManager を返します。この場合の処理内容
は CacheManager.getInstance()と同じです。
136
• CacheManager.create(Configuration configuration)： configuration の内容を使用してシングルト
ンの CacheManager を作成します。存在する場合は既存のシングルトン CacheManager を返し
ます。
• new CacheManager(Configuration configuration)： configuration の内容を使用して
CacheManager を新規作成します。同名の CacheManager が存在する場合、または
configuration が null の場合は例外をスローします。
作成モードがインスタンスモード（非シングルトンモード）の場合、同一の JVM 内に複数の
CacheManager を作成し、それらを同時に利用できます。この場合、個々の CacheManager には、
独自の構成情報が必要です。
管理対象の Cache のうち、ディスクストアを使用する Cache が複数ある場合、CacheManager 構成
情報のディスクストアのパスには一意の値を指定する必要があります。新しい CacheManager を作
成する際、システムは同じディスクストアのパスを使用している CacheManager が存在しないこと
を確認します。永続化の方法に応じて、BigMemory Max はディスクとストア間のパスの競合を自動
的に解決します。また、ディスクとストア間のパスを明示的に設定する必要がある場合は、その旨
を通知します。
メモリストアだけを使用するキャッシュの場合、こうした配慮は不要です。
CacheManager がクラスタの一部の場合は、リスナポートにも一意の値を指定する必要があります。
これらのメソッドと、引数として渡す構成情報の詳細は、APIのドキュメント を参照してください。
サンプルのコードは「サンプルコード集」を参照してください。
19.3 Cache Cache とは、一連のデータ項目の、スレッドセーフな論理構造を指します。通常のキャッシュシス
テムと、ほぼ同じ内容を提供します。Cache に対する何らかの処理を実行する前に、CacheManagerを利用してキャッシュへの参照を取得しておく必要があります。Cache に対する処理の物理的な実
装は「stores」に登録されています。
Caches のインスタンス化には、構成情報を使用する方法と、プログラムから Cache()コンストラク
タの 1 つを使用する方法があります。ARC のサイズやピンニングなど、構成情報を利用しないと設
定できないキャッシュ属性もあります。
キャッシュの属性を取得するには、Cache クラスのメソッドを使用します（例：getCacheManager()、isNodeBulkLoadEnabled()、isSearchable()など）。また、キャッシュ全体に利用できるオペレーシ
ョンもあります（例：flush、load、initialize、dispose など）。
ほかにも Cache クラスは、キャッシュの要素を操作するメソッド（例：get、set、remove、replaceなど）と、それらの情報を取得するメソッド（例：isExpired、isPinned など）を提供します。
137
19.4 Element Element とは、キャッシュの不可分なエントリーを指します。Element はキーと値、そしてアクセ
スの履歴を記録しています。キャッシュへの登録、およびキャッシュからの削除の単位となるのが
Element です。キャッシュを設定することで、Element に有効期限を設定し、自動的に削除するこ
とも可能です。
シリアル化された Element 用の API に加え、Object に対する API も提供されています。シリアル化
されていない Object を記録できるのはヒープ領域だけです。これらに対する永続化の操作は無視さ
れ、DEBUG レベルのログが出力されます。ただし、エラーは発生しません。
戻り値の取得を除くと、API は Element 用と同じです。Element を取得する API は getKey()とgetValue()ですが、Object を取得する API は getKeyValue()と getObjectValue()です。
20 BigMemory Maxの検索API
20.1 はじめに
BigMemory Max の検索 API を利用すると、事前に作成したインデックスで、任意の複合クエリを実
行できます。値の代替インデックスを開発すると、キーだけを使用したデータの参照に加え、複数
の条件を利用した参照も可能になります。
検索可能な属性は、キーと値の両方から抽出できます。キー、値、合計値のすべてが戻り値に利用
できます。簡単なサンプルを紹介します。この例では、32 歳の男性を検索し、そのキャッシュの
値を返します。
Results results = cache.createQuery().includeValues() .addCriteria(age.eq(32).and(gender.eq("male"))).execute();
検索可能な項目
Element、キー、値が検索対象です。いずれの場合も属性として扱う必要があります。Element のキーと値の一部は、検索のインデックスに属性として追加するだけで、直接検索できます。その一
方で、Element のキーや値から抽出して検索可能な型にしないと検索できない場合もあります。属
性として抽出すれば、そのまま検索できます。
20.2 Cacheを検索可能にする方法
キャッシュを検索可能にするには、構成情報ファイルを使用する方法と、プログラムから設定する
方法があります。これらの設定により、キャッシュ単位の検索が可能になります。
構成情報を使用する方法
ehcache.xml に<searchable/>タグを追加することで Cache の検索が可能になります。
138
<cache name="cache2" maxBytesLocalHeap="16M" eternal="true" maxBytesLocalOffHeap="256M"> <persistence strategy="localRestartable"/> <searchable/> </cache>
この構成では、キーと値をスキャンし、検索がサポートされている型であれば、それらを「key」および「value」という名前の属性として追加します。以下のように設定すれば、キーと値を使用し
たインデックスの自動作成を抑制できます。
<cache name="cacheName" ...> <searchable keys="false" values="false"/> ... </searchable> </cache>
キーや値に複数の型が混在している場合は、インデックスの自動作成を抑制してください。複数の
型が混在していると、インデックスの自動作成は例外をスローします。
キーや値を直接検索できないことも頻繁にあります。このような場合は、検索可能な属性を抽出し
てから検索を行います。典型的な例を以下に示します。属性抽出の仕組み（Attribute Extractor）が
明示的に使用されていることに注目してください。
<cache name="cache3" maxEntriesLocalHeap="10000" eternal="true" maxBytesLocalOffHeap="10G"> <persistence strategy="localRestartable"/> <searchable> <searchAttribute name="age" class="net.sf.ehcache.search.TestAttributeExtractor"/> <searchAttribute name="gender" expression="value.getGender()"/> </searchable> </cache>
プログラムを使用する方法
検索属性を持つキャッシュ構成情報をプログラムから作成する場合の例を以下に示します。
Configuration cacheManagerConfig = new Configuration(); CacheConfiguration cacheConfig = new CacheConfiguration("myCache", 0).eternal(true); Searchable searchable = new Searchable(); cacheConfig.addSearchable(searchable); // Create attributes to use in queries. searchable.addSearchAttribute(new SearchAttribute().name("age")); // Use an expression for accessing values. searchable.addSearchAttribute(new SearchAttribute() .name("first_name")
139
.expression("value.getFirstName()")); searchable.addSearchAttribute(new SearchAttribute() .name("last_name") .expression("value.getLastName()")); searchable.addSearchAttribute(new SearchAttribute() .name("zip_code") .expression("value.getZipCode()")); cacheManager = new CacheManager(cacheManagerConfig); cacheManager.addCache(new Cache(cacheConfig)); Ehcache myCache = cacheManager.getEhcache("myCache"); // Now create the attributes and queries, then execute. ...
検索APIの詳細は、本製品の Javadocのnet.sf.ehcache.search*パッケージの説明を参照してください。
Terracotta サーバアレイでは、高速再起動とキャッシュ検索の両方を同時に有効化できます。どち
らの機能も、ディスク層の利用が前提になります。両方の機能を有効化する際は、ディスクに十分
な空き領域があることを確認してください。必要になるディスク容量は、インメモリのデータサイ
ズの約 1.5 倍です（検索可能にする属性の数によって変化します）。
注意：検索と高速再起動の両方を有効化した際のディスク使用について
20.3 属性の定義
キャッシュを検索可能にするには、構成の設定に加え、検索に使用する属性を定義しておく必要が
あります。
属性は、検索時にキーまたは値から抽出されます。この処理を行なうのは AttributeExtractor です。
検索がサポートされている型は以下のとおりです。これらの型の属性を抽出する必要があります。
• Boolean
• Byte
• Character
• Double
• Float
• Integer
• Long
140
• Short
• String
• java.util.Date
• java.sql.Date
• Enum
型の間違いや Not Found などで正しく属性を抽出できない場合、検索の実行時に
AttributeExtractorException がスローされます。
Well-known 属性
Element の一部の属性を Well-known 属性と呼びます。これらは、事前に定義された名前で参照で
きるようになっています。検索機能がサポートする型のキーや値の場合、検索機能は「key」また
は「value」という名前の属性を自動的に追加します。これらは Query クラスが属性名として使用
している定数と同じであるため、クエリでも使用できます。クエリの中では、例えば「key」の属
性を Query.KEY と記述できます。さらに読みやすくするには、静的なインポートを使用してくださ
い。これにより、単に KEY と記述できるようになります。
Well-known 属性の名前 属性の定数
key Query.KEY
value Query.VALUE
ReflectionAttributeExtractor
ReflectionAttributeExtractor は、ビルトインの検索属性抽出機能です。JavaBean の規則を採用し、
簡単な式も使用できます。JavaBean プロパティが有効な環境で検索可能な型を検索する場合は、そ
れを宣言するだけで構いません。
<cache> <searchable> <searchAttribute name="age"/> </searchable> </cache>
ReflectionAttributeExtractor では、メソッドや値をピリオドで区切った式を使用できます。この式
の先頭には、「key」「value」または「element」を記述します。この起点となるオブジェクトのあ
とに、メソッド呼び出しやフィールド名を続けて記述します。1 つの式の中にメソッド呼び出しと
フィールド名の両方を混在させても構いません。以下に例を示します。
<cache> <searchable>
141
<searchAttribute name="age" expression="value.person.getAge()"/> </searchable> </cache> <cache> <searchable> <searchAttribute name="name" expression="element.toString()"/> </searchable> </cache>
注意：ここで指定する式の「メソッド」と「フィールド名」の部分は、大文字と小文字を区別して
扱います。
拡張 AttributeExtractor
AttributeExtractor インターフェースを実装することで、さらに複雑な機能を属性の抽出機能に追加
することが可能です。以下の例に従って、抽出機能を提供するためのクラスを準備してください。
<cache name="cache2" maxEntriesLocalHeap="0" eternal="true"> <persistence strategy="none"/> <searchable> <searchAttribute name="age" class="net.sf.ehcache.search.TestAttributeExtractor"/> </searchable> </cache>
以下に、Employee オブジェクトを受け取ったカスタム属性の抽出機能が、特定の属性だけを抽出
する場合の例を示します。
returnVal = employee.getdept();
カスタム抽出機能にステータスを渡す場合は、プロパティを使用するとよいでしょう。この場合の
例を以下に示します。
<cache> <searchable> <searchAttribute name="age" class="net.sf.ehcache.search.TestAttributeExtractor" properties="foo=this,bar=that,etc=12" /> </searchable> </cache>
プロパティを受け取るためには、1 つの java.util.Properties インスタンスを引数として受け取る
public 属性のコンストラクタを抽出機能に実装しておく必要があります。
142
20.4 クエリの作成
BigMemory Max の検索では、オブジェクト指向のクエリ API を使用します。このクエリ API は、
Java プログラム経験者に馴染みのある DSL の原則に従っています。簡単なサンプルを紹介します。
Query query = cache.createQuery().addCriteria(age.eq(35)).includeKeys().end(); Results results = query.execute();
20.4.1 クエリ内での属性の使用 検索で使用できる型の Well-known 属性が宣言されている場合は、それらの名前を検索に使用でき
ます。以下の例のように、属性を直に使用することも可能です。
Results results = cache.createQuery().addCriteria(Query.KEY.eq(35)).execute(); Results results = cache.createQuery().addCriteria(Query.VALUE.lt(10)).execute();
ほかの属性を構成情報ファイルで定義しておけば、それらも検索に使用できます。以下に例を示し
ます。
Attribute<Integer> age = cache.getSearchAttribute("age"); Attribute<String> gender = cache.getSearchAttribute("gender"); Attribute<String> name = cache.getSearchAttribute("name");
20.4.2 式 クエリは式を使って作成します。式には、「and」や「or」などの論理演算子と、「ge（>=）」
「between」「like」などの比較演算子を使用できます。クエリに条件句を追加するには、構成情報
の addCriteria(...)を使用します。追加の条件句は、「and」条件として追加されます。
query = cache.createQuery().includeKeys() .addCriteria(age.le(65)) .add(gender.eq("male")) .end();
論理演算子と比較演算子は、どちらも Criteria インターフェースの実装です。異なる論理演算子を
使用した条件を追加するには、新しい論理演算子の Criteria オブジェクトへ明示的に追加します。
例えば、条件に「age = 35 or gender = female」を加える場合は、以下を追加します。
query.addCriteria(new Or(age.eq(35), gender.eq(Gender.FEMALE)) );
条件を入れ子にすることで、さらに複雑な条件式を定義できます。条件式で使用できる演算子の一
覧は Expression JavaDocを参照してください。
143
20.4.3 演算子一覧 演算子は、「属性名＋ピリオド＋演算子」という書式で使用できます。例えば「less than（より小
さい）」の意味を持つ演算子の短縮形は「lt」です。age LessThan(10)の代わりに age.lt(10)と記述
できます。演算子の短縮形は以下のとおりです。
短縮形 条件クラス 説明
and And ブール型に使用する AND 演算子
between Between 2 つの値の間にあることを確認する比較演算子
eq EqualTo Java の「等しい（equals to）」と同等の意味を持つ比較演算子
gt GreaterThan 「～より大きい（>）」を意味する比較演算子
ge GreaterThanOrEqual 「～と等しい、または大きい（>=）」を意味する比較演算子
in InCollection 引数に渡されたコレクションに含まれていることを意味する比較
演算子
lt LessThan 「～より小さい（<）」を意味する比較演算子
le LessThanOrEqual 「～と等しい、または小さい（<=）」を意味する比較演算子<
ilike ILike マッチ演算子。「?」と「*」を使用できます。式の前にワイルド
カードを記述すると、テーブル検索を実行します。ILike では、大
文字と小文字を区別しません。
not Not ブール型に使用する NOT 演算子
ne NotEqualTo Java の「等しくない（not equals to）」と同等の意味を持つ比較演
算子
or Or ブール型に使用する OR 演算子
20.4.4 クエリを保存 デフォルト状態では、実行したクエリは編集して再実行できます。ただし、end を呼び出すと、そ
のクエリは変更できなくなります。
20.5 クエリの結果の取得と管理
クエリを実行すると Results オブジェクトを返します。このクラスは Result クラスのリストを含ん
でいます。クエリの実行で検出されたキャッシュ内の各 Element は、それぞれが Result オブジェ
クトに格納されます。つまり、クエリの実行で 350 の Element が見つかった場合は、350 の Resultオブジェクトが作成されます。キーや属性が検出されず、合計値だけが返された場合でも、1 つの
Result オブジェクトが作成されます。
Result オブジェクトの内容は以下のとおりです。
• Element の key：includeKeys()を追加したクエリの場合。
144
• Element の値：includeValues()を追加したクエリの場合。
• Element の値を継承した事前定義の属性：includeAttribute(...)を追加したクエリの場合。Resultから属性にアクセスする場合は、getAttribute(Attribute<T> attribute)を使用してください。
• 集計値：検索を実行すると、検出された対象に対する集計を計算できるようになります。
Result.getAggregatorResults を使用すると Aggregator のリストを取得できます。このリストに
は Query の実行と同じ順番で値が格納されています。
20.5.1 Aggregators query.includeAggregator(\<attribute\>.\<aggregator\>)を追加すると、合計値を計算できるようにな
ります。例えば、年齢の合計を計算する方法は以下のとおりです。
query.includeAggregator(age.sum());
Aggregatorが提供する機能の一覧は、Aggregators JavaDocを参照してください。
20.5.2 結果の並べ替え クエリの結果をソートするには、クエリに addOrderBy 句を追加します。ソートのキーとして使用
する属性と、ソートの順番（昇順または降順）は、この句のパラメーターとして指定します。クエ
リの結果を年齢順（昇順）に並べ替える場合の例は以下のとおりです。
query.addOrderBy(age, Direction.ASCENDING);
20.5.3 結果のグループ化 BigMemory Max のクエリの結果は、SQL GROUP BY 指令のようにグループ化できます。BigMemoryの GroupBy 機能を使用するには、クエリに addGroupBy 句を追加します。グループ化に使用する属
性は、この句のパラメーターとして指定します。クエリの結果を所属組織でグループ化する場合の
例は以下のとおりです。
Query q = cache.createQuery(); Attribute<String> dept = cache.getSearchAttribute("dept"); Attribute<String> loc = cache.getSearchAttribute("location"); q.includeAttribute(dept); q.includeAttribute(loc); q.addCriteria(cache.getSearchAttribute("salary").gt(100000)); q.includeAggregator(Aggregators.count()); q.addGroupBy(dept, loc);
この GroupBy 句は、includeAttribute()の結果をグループ化します。さらに、グループに対して集計
関数を使用すると、属性をグループごとに集計できます。属性の集計結果を取得する方法は、以下
の例を参照してください。
145
String dept = singleResult.getAttribute(dept); String loc = singleResult.getAttribute(loc);
GroupBy の規則
グループ化を行うクエリは、2 段階のクエリとして実行されます。最初は通常のクエリが実行され、
次にグループ化クエリが実行されます。したがって、GroupBy を使用する際は、以下の規則に従う
必要があります。
• GroupBy 句を使用するクエリでは、includeAttribute()で指定した属性を、GroupBy 句にも必ず
指定してください。
• GroupBy 句では、特殊な KEY 属性や VALUE 属性を使用できません。つまり、GroupBy 句を使
用するクエリには、includeKeys()と includeValues()を使用できません。
• GroupBy 句のあるクエリでは、Aggregator の機能が各グループに対して実行されます。
• クエリの中に集計関数が 1 つでもある場合は、各結果の中にグループ属性を指定する必要はあ
りません。ただし、グループ属性を指定したほうが集計結果を利用しやすくなります。
• addCriteria()句は、グループ化を実行する前に適用されます。
• OrderBy と GroupBy を同時に使用した場合、GroupBy 句で使用した属性だけがソートに使用
されます。
20.5.4 クエリ結果のサイズの制限 デフォルト状態では、クエリ結果のサイズに制限はありません。例えば以下のクエリを実行すると、
キャッシュ内の全てのキーを取得できます。
Query query = cache.createQuery(); query.includeKeys(); query.execute();
結果が多すぎると、OutOfMemoryError が発生する場合があります。maxResults`句を使用すると、
結果のサイズを制限できます。前述の例で、クエリの結果を 100 項目に制限する場合は、以下のよ
うに操作します。
Query query = cache.createQuery(); query.includeKeys(); query.maxResults(100); query.execute();
注意：maxResults と GroupBy を同時に使用した場合は、グループの数が制限されます。
146
結果が不要になったら discard()を呼び出し、リソースを解放してください。Terracotta のリリース
版では、ページごとまたは戻り値ごとの結果を保持するためにリソースを使用するようになってい
ます。
20.5.5 問い合わせメソッド クエリの結果を確認するには、Results に対して以下の問い合わせメソッドを実行します。
• hasKeys()
• hasValues()
• hasAttributes()
• hasAggregators()
20.5.6 Null（またはNot Null）の検出 Null 値を持つ各要素の文字列を「NULL」に置き換えることで、Null（または Not Null）の検索が可
能になります。「拡張 AttributeExtractor」で「NULL」文字列を検索すれば、Null 値を持つ値を検
出できます（not-equal 検索を実行すれば、Not Null 値を検索できます）。
文字列を使用できないフィールドが検索対象の場合は、ダミーのフィールドを作成し、そのフィー
ルドに「0（Null）」または「1（Not Null）」を割り当ててください。このダミーフィールドを対
象にクエリを実行すれば、Null または Not-Null を検出できます。
20.6 サンプルアプリケーション
BigMemoryの検索に使用できるスタンドアロンの簡単なサンプルアプリケーションを提供してい
ます。依存関係はほとんどありません。ソースコードは以下から入手できます。
git clone git://github.com/sharrissf/Ehcache-Search-Sample.git
Ehcacheテストソースコードのページには、各種検索機能を使用するためのサンプルが豊富に用意
されています。
20.7 スクリプト環境
BigMemory の検索機能では、スクリプトも利用できます。BeanShell を使用したスクリプトの例を
以下に示します。
Interpreter i = new Interpreter(); //Auto discover the search attributes and add them to the interpreter's context Map<String, SearchAttribute> attributes = cache.getCacheConfiguration().getSearchAttributes(); for (Map.Entry<String, SearchAttribute> entry : attributes.entrySet()) { i.set(entry.getKey(), cache.getSearchAttribute(entry.getKey()));
147
LOG.info("Setting attribute " + entry.getKey()); } //Define the query and results. Add things which would be set in the GUI i.e. //includeKeys and add to context Query query = cache.createQuery().includeKeys(); Results results = null; i.set("query", query); i.set("results", results); //This comes from the freeform text field String userDefinedQuery = "age.eq(35)"; //Add on the things that we need String fullQueryString = "results = query.addCriteria(" + userDefinedQuery + ").execute()"; i.eval(fullQueryString); results = (Results) i.get("results"); assertTrue(2 == results.size()); for (Result result : results.all()) { LOG.info("" + result.getKey()); }
20.8 実装とパフォーマンス
20.8.1 Terracottaサーバアレイ内のBigMemory Max この実装は各 Terracotta サーバ上で保守されるインデックスを使用します。分散 BigMemory Maxでは、データがクラスタ内の複数のアクティブノードに割り当てられます。分散したデータのイン
デックスは、そのデータが存在するサーバで保守されます。この場合、検索はスキャッタ･ギャザ
ー機能を使って行なわれます。クエリは各ノードで実行され、結果は検索を開始した BigMemory Max に集積されます。
検索の発生回数は「O(log n / データ片の数）」です。パフォーマンスはこの時点でも優れています
が、TSA にサーバを追加することでさらなる向上をもたらすことができます。また、検索結果はネ
ットワーク経由で返され、そのデータは非常に大きなサイズになることもあるため、サイズを制限
することを推奨します。詳しくは、「検索を最適化する方法」を参照してください。
20.8.2 スタンドアロンのBigMemory Max BigMemory は、ローカルノードで保守される検索インデックスを使用します。インデックスは
DiskStore のディレクトリに保存されます。persistence モードの設定に関わりなく利用できます。
キャッシュのオンヒープ層でオーバーフローが発生した場合は、オフヒープ層またはディスク層で
インデックスを使用した検索を実行します。
148
検索の発生回数は「O(log(n))」です。パフォーマンス向上のヒントは、「検索を最適化する方法」
を参照してください。
オンヒープ領域だけを使用したキャッシュを検索する際、この実装はインデックスを使用しません。
代わりに、各クエリに対するテーブル検索と同等の高速アクセスを利用して、キャッシュの高速反
復を実行します。キャッシュ内の各要素に、1 回だけアクセスします。属性の事前抽出は実行しま
せん。クエリの実行時に属性を抽出します。
検索の発生階数は「O(n)」回です。オンヒープ領域だけを使用する検索のパフォーマンスは Mavenを利用したパフォーマンステストを参照してください。このテストでは、項目数 10,000 のキャッ
シュでは 4.6 ミリ秒、項目数 1,000,000 のキャッシュでは 427 ミリ秒という結果になっています。
この値は、開発やテストに十分なパフォーマンスであると考えられます。
20.9 検索を最適化する方法
1. 本当に必要なデータだけを検索するには、さまざまな工夫が必要です。
– includeKeys()や includeAttribute()を使用するのは、アプリケーションロジックがそれ
らの戻り値を必要としている場合だけにとどめてください。
– 不要な値や属性を検索するクエリで余計な負荷を与えないでください。例えば、検索
結果に対して result.getValue()を実行しないうちに、元のクエリで includeValues()を呼
び出すような処理が該当します。
– 個々のキャッシュから属性やキーを取得すれば十分ではないか、よく考えてください。
例えば、includeValues()のあとに result.getValue()を実行するクエリの代わりに、クエ
リで取得したキーを使用して cache.get()を実行するような処理が該当します。
注意：includeKeys()と includeValues()は、Lazy な非シリアライズ化を行ないます。Lazy な非
シリアル化とは、result.getKey()または result.getValue()を呼び出したときに、初めてキーや値
の非シリアル化を行なうという意味です。つまり、キーだけが必要な場合には、ある程度のオ
ーバーヘッドが生じます。includeKeys()と includeValues()にはオーバーヘッドが生じることを
十分に考慮してクエリを作成してください。
2. デフォルトでは、検索可能なキーや値に対してインデックスが自動作成されます。クエリでこ
の機能を利用する予定がない場合は、以下のように指定して、インデックスの自動作成を抑制
します。
<cache name="cacheName" ...> <searchable keys="false" values="false"/> ... </searchable> </cache>
149
3. 結果セットのサイズをquery.maxResults(int number_of_results)で制限します。あるいは、ビル
トインのAggregator関数で集計結果だけを返すようにした場合も、結果セットのサイズは小さ
くなります（詳細は、Javadocのnet.sf.ehcache.search.aggregatorパッケージを参照してくださ
い）。
4. 可能な限り、あいまい検索を避けてください。「ILike」条件によるあいまい検索（ワイルド
カード検索）は、そうでない検索よりも時間がかかります。どうしても必要な場合は、文字列
の先頭ではなく最後にワイルドカードを使用するよう努めてください（つまり、"*123"ではな
く"321*"を使用するという意味です。）。文字列の先頭にワイルドカードが必要な場合は、
<searchAttribute>を作成し、そこに反転した文字列（文字を逆順に並べたもの）を保存します。
そうすれば、ワイルドカードは文字列の最後に移動できます。
5. 「LessThan」と「GreaterThan」を組み合わせたクエリや、「LessThanOrEqual」と
「GreaterThanOrEqual」を組み合わせたクエリよりも、「Between」を活用したクエリを使用
してください。例えば、必要な条件が le(startDate)と ge(endDate)の場合は、
not(between(startDate,endDate))を使用してください。
6. インデックスの日付は整数です。整数として検索し、あとから形式を変換したほうが時間を節
約できます。
7. BigMemory Max の非同期のデータセットの検索は、クエリが即実行されるため、ローカルノ
ードで未決のトランザクションがコミットされるのを待たなくてよい分だけ早く行なわれます。
注意：例えば、あるスレッドが要素を非同期キャッシュに追加し、その要素をフェッチするク
エリをすぐに実行しても、更新内容がサーバに公開されるまでその要素は検索結果に表示され
ません。
20.9.1 同時並行性に関する注意 同時並行の制御やトランザクションを選択できるキャッシュ操作と違い、クエリは非同期です。検
索結果はキャッシュの内容と結果的に一貫性を保ちます。
インデックスの更新
インデックスの更新は同期処理ですが、キャッシュよりも一瞬だけ更新が遅れます。ただし、更新
スレッドを実行してから検索を実行した場合は例外です。
同時並行制御が有効なキャッシュの場合、以下に該当するまでインデックスの内容は更新されませ
ん。
• 変更内容がクラスタに適用されている。
• トランザクションを実行するキャッシュで commit が呼び出されている。
クエリの結果
クエリの実行結果が、期待した結果にならない場合もあります。
150
• 検索結果が、既に存在しない Element への参照を含んでいる場合があります。
• ある条件で Element が検出できていたとしても、その Element が更新されると検索条件と一
致しなくなる場合があります。このため、再検索では検出できなくなります。
• Aggregator が提供する sum()などの計算結果が、各キーにアクセスして手動計算した結果と一
致しない場合があります。
• 検索用インデックスの更新は、キャッシュ更新後に行われます。したがって、既に削除された
キャッシュの値に対する参照を検索結果が含む場合もあります。このような場合、値は Nullになりますが、キャッシュのインデックスから取得したキーと属性の値は Not Null になります。
Ehcache の値には Null 値を記録できます。したがって、キャッシュが削除されたことで Null値を取得したのか、本当にキャッシュが Null 値を記録していたのかは判断できません。
推奨事項
キャッシュの内容は刻々と変換するため、検索した時点の結果と一致しない場合があります。した
がって、以下の考慮が必要です。
• Aggregator の機能は、1 つのクエリの中ですべてを実行してください。そうすれば、そのクエ
リで取得したキャッシュの内容と一貫した結果を得られます。
• 検索結果から取得したキャッシュのキーへのアクセス処理では、Null 値をガードする処置を施
してください。
21 一括ロード
21.1 はじめに
BigMemory Max には、TSA（Terracotta サーバアレイ）を利用してキャッシュの一括ロードを実施
するモードが用意されています。この機能により、パフォーマンスが大幅に向上します。一括ロー
ドは以下の目的のために用意されています。
• キャッシュの準備：アプリケーションをオンライン状態にする前に、キャッシュ内のデータの
用意が必要な場合
• 定期的な一括ロード：夜間の一括処理など、データをまとめてアップロードする場合
一括ロード API は、データの一括ロードのため、ロックやトランザクション要求を省略し、最適化
します。また、一括ロード API は、アプリケーションにより、キャッシュが一括ロードモードか、
それ以外のモードか、状態の取得もできます。
151
21.2 API BigMemory Max にデータを記録する場合は、一括ロードモード利用の有無にかかわらず同じ APIを使用します。cache.put(...)、cache.load(...)、または cache.loadAll(...)を使用します。ただし、通常
の分散キャッシュに対する整合性の保証を一時的に保留する点と、TSA の 2 次キャッシュへの移動
（フラッシュ）が最適化されている点が異なります。
キャッシュの整合性モードの初期値は構成情報ファイルで設定します。このモードはプログラムか
ら変更できません（詳細は「BigMemory Max 分散構成設定ガイド」の<terracotta>を参照）。一括
ロードを処理するため一時的に設定済みの整合性モードを保留するには、一括ロード API を使う必
要があります。
注意：一括ロード API と、整合性モードの設定
org.terracotta.modules.ehcache.Cache が提供する一括ロード API のメソッドは以下のとおりです。
• public boolean isClusterBulkLoadEnabled()
クラスタ全体のキャッシュが一括ロードモードの場合（つまり整合性が保証されない場合）は
「true」を返します。クラスタ全体のキャッシュが一括ロードモードでない場合（つまり整合
性が保証される場合）は「false」を返します。
• public boolean isNodeBulkLoadEnabled()
現在のノードのキャッシュが一括ロードモードの場合（つまり整合性が保証されない場合）は
「true」を返します。現在のノードのキャッシュが一括ロードモードでない場合（つまり整合
性が保証される場合）は「false」を返します。
• public void setNodeBulkLoadEnabled(boolean)
キャッシュの整合性モードを変更します。整合性を保証するモードに設定する場合は「false」を、一括ロードモードに設定する場合は「true」を指定します。現在の状態と同じモードを
setNodeBulkLoadEnabled()で指定した場合、処理は発生しません。このメソッドを「ノンスト
ップキャッシュ」で使用すると、そのキャッシュに設定されたタイムアウトの係数
（bulkOpsTimeoutMultiplyFactor）が適用されます。元のタイムアウト値と係数との積が、一
括ロード処理の新しいタイムアウト値になります。この新しいタイムアウト値を過ぎると、キ
ャッシュはあらかじめ設定された動作を行います。ノンストップキャッシュのタイムアウトの
設定の詳細は「ノンストップキャッシュのタイムアウト動作のチューニング」を参照してくだ
さい。
• public void waitUntilBulkLoadComplete()
152
キャッシュの整合性がとれるまで、復帰を保留します。自動的に一括ロードモードになり、ク
ラスタ全体のキャッシュの更新を待ちます。クラスタ全体の整合性がとれたら、直ちに復帰し
ます。
一括ロードモードの使用には、以下の注意が必要です。
• 整合性は保証されません。あるキャッシュに対し、あるノードが isClusterBulkLoadEnabled()で false を返す前に、別のノードが setNodeBulkLoadEnabled(true)を設定する可能性があるか
らです。キャッシュデータの完全性を維持するには、アプリケーションが一括ロード API をど
のように利用しているかを正しく理解することが大切です。
• キャッシュが完全性を保っていないと、ObjectNotFound 例外が発生し、ログに記録されます。
• ObjectNotFound 例外が発生した get()メソッドは null を返します。
• エビクションの動作は、整合性モードの影響を受けません。設定による自動エビクションや、
アプリケーションによる任意のエビクションは、整合性モードとは無関係に動作します。
21.3 一括ロードAPIを利用したサンプル
BigMemory Max を利用したクラスタ対応の分散アプリケーションで一括ロード API を使う例を以
下に示します。
import net.sf.ehcache.Cache; public class MyBulkLoader { CacheManager cacheManager = new CacheManager(); // Assumes local ehcache.xml. Cache cache = cacheManager.getEhcache(\"myCache\"); // myCache defined in ehcache.xml. cache.setNodeBulkLoadEnabled(true); // myCache is now in bulk mode. // Load data into myCache. // Done, now set myCache back to its configured consistency mode. cache.setNodeBulkLoadEnabled(false); }
Ehcacheでは、1 つのJVM内に重複する名前のCacheManagerを作成できません。シングルトンでな
いCacheManagerを作成するCacheManager()コンストラクタでこのルールに違反するとエラーが発生
します。使用するコードが同一JVM内に複数の同名CacheManagerを作成する可能性がある場合
は、staticのCacheManager.create() methodsを使用して、この例外を回避してください。このメソッ
ドは、同名のCacheManagerがJVMに存在する場合、常に名前付き（あるいはデフォルトの名前な
し）のCacheManagerを返します。名前付き（またはデフォルトの名前なし）CacheManagerが存在
しない場合は、CacheManager.create()メソッドで作成します。
注意：シングルトンでない CacheManager の潜在的な問題
153
他のノードのアプリケーションから myCache にアクセスすると、処理が継続する場合と待機状態
になる場合があります。これは、myCache の整合性モードによって決まります。
... if (!cache.isClusterBulkLoadEnabled()) { // Do some work. } else { cache.waitUntilBulkLoadComplete() // Do the work when waitUntilBulkLoadComplete() returns. } ...
古くなった可能性のあるデータを処理できるコードは、待機が不要です。
... if (!cache.isClusterBulkLoadEnabled()) { // Do some work. } else { // Do some work knowing that data in myCache may be stale. } ...
21.4 処理速度の向上
処理速度は、桁違いに向上します。サンプルコードの ehcacheperf（Springペットクリニック）には、
一括ロードのテストが組み込まれています。このサンプルにより、Terracottaクラスタの利用によ
るパフォーマンス向上を確認できます。
21.5 FAQ ピンニングされたキャッシュに対し、一括ロードはどのような影響を与えますか。
キャッシュを一括ロードモードに変更すると、「ピンニング」されていたキャッシュは削除されま
す。そして、データが必要になった時点で、TSA からの fault による移動が発生します。
キャッシュを一括ロードモードにする以外の方法はありますか。
「putAll(), getAll(), removeAll()」は、一括ロードモードと同様にキャッシュを取り扱う高速なメソ
ッドです。ただし、キャッシュ内容の整合性を保証しない状態が一時的に発生します。これらは、
154
整合性モードが「strong」の場合でも利用できます。これらを利用できるのであれば、一括ロード
モードに頼る必要はありません。詳細は APIのドキュメントを参照してください。
Terracotta クラスタだけが一括ロードモードを利用できるのはなぜですか。
スタンドアロンの Ehcache とレプリカの Ehcache は、どちらも非常に高いパフォーマンスを誇って
います。したがって、特別な追加の機能は不要です。
RMI 分散キャッシュの一括ロードはどのように動作しますか。
コアの更新は非常に高速です。RMI は、バッチ処理で 1 秒（デフォルト）ごとに更新されます。し
たがって、一括ロードも効率的に複製されます。
21.6 パフォーマンス向上のヒント
複数の Put スレッドを利用するタイミング
cache.put の呼び出し時は、マルチスレッドが不要です。処理はもともと高速なので、マルチスレ
ッドを利用しても、大幅なパフォーマンスの向上は期待できません。マルチスレッドが必要になる
のは、ソースの動作が遅い場合です。動作の遅いソースに対してマルチスレッドによる読み取り処
理を実行すれば、ある程度のスピード向上が期待できます。例えばデータベースからの読み取り処
理では、マルチスレッドを利用した読み取りのほうが高速になります。
複数ノードでの一括ロード
実装のスケールという観点では、Ehcache による複数マシンの複数 ChacheManager に対するロード
は、分割したほうが優れています。追加ノードに対する一括ロードでは、パフォーマンスが 93 倍
になるというデータもあります。
一括ロードモードを常時利用できるケース
Terracotta クラスタ技術は、整合性、拡張性、耐久性を提供しています。整合性（一貫性）が重要
になるアプリケーションもありますが、参照データなど、それほど整合性が重要でない場合もあり
ます。こうしたデータには、整合性を保証しない一括ロードモードで運用したほうが有利です。
22 事前リフレッシュ
22.1 はじめに
この機能は、キャッシュしたデータの積極的な更新やデータの陳腐化を避けるために使用します。
また、リードスルーにおける「Thundering Herd」問題の解決策にもなります。
155
22.2 インラインの事前リフレッシュ
インラインの事前リフレッシュを使うと、キャッシュはタイマーにしたがってエントリーを自動的
にリフレッシュすることができます。設定した時間制限に達するアクセス済みのエントリーは、
「CacheLoader の実装」によりリロードされます。
22.2.1 インラインの事前リフレッシュの構成情報設定 インラインの事前リフレッシュは、キャッシュのDecoratorを使って各キャッシュで構成設定します。
<cache ... <cacheLoaderFactory class="com.company.my.ConcreteCacheLoaderFactory" properties="some_property=1, some_other_property=2" /> <cacheDecorator class="net.sf.ehcache.constructs.refreshahead.RefreshAheadCacheFactory" properties="name=myCacheRefresher, timeToRefreshSeconds=200, batchSize=10, numberOfThreads=4, maximumBacklogItems=100, evictOnLoadMiss=true" /> </cacheDecorator> ... </cache>
「cache-decorator」クラスは事前リフレッシュの仕組みを実装するうえで必要不可欠です。インラ
インの事前リフレッシュの構成情報のプロパティは、「必須」と明記されていないかぎり省略可能
です。これらのプロパティについては、以下の表で説明します。
プロパティ 定義内容 デフォルト値
name この名前を、キャッシュの Decorator の識別に使用しま
す。「Null」のままにしておくと、キャッシュ名の参照時
に、基盤となるキャッシュではなく、キャッシュの
Decorator がアクセスされます。
N/A
timeToRefreshSeconds 必須。アクセス時にリフレッシュ（リロード）されるま
で、エントリーをキャッシュ内に保持できる秒数。エビ
クションによって破棄されていない期限切れの項目はリ
フレッシュされません。
N/A
maximumBacklogItems 必須。リフレッシュの作業キューに収容可能なリフレッ
シュの最多リクエスト数。この制限値を超えると、リソ
ースの過剰負荷を避けるためにリクエストがキューから
除外されます。リクエストがクリアされる前にキューに
N/A
156
並んだ場合、この制限値を超えることもあります。
batchSize スレッドが一括処理でリフレッシュできるリクエストの
最大数。パフォーマンスよりもリクエストの処理頻度を
優先する場合は、この値を低く設定してください。
100
numberOfThreads Decorator のバックグラウンドでリフレッシュを行なう際
に使うスレッド数。複数のキャッシュローダの構成設定
を行なった場合、リフレッシュ処理は順番に行なわれま
す。
1
evictOnLoadMiss リロード失敗時に即時エビクションを強制（true）した
り、通常のエビクションを実行する前にはエビクション
を行なわない（false）ようにするブーリアン。「true」を
指定した場合、リロードの失敗（すべてのキャッシュロ
ーダが失敗）が理由でリフレッシュしないエントリーは
エビクションによって破棄されます。この場合、たとえ
「time-to-live」または「time-to-idle」で設定した有効期
限が切れていなくとも、これらのエントリーは破棄され
ます。
false
22.2.2 timeToRefreshSecondsと有効期限の連携 timeToRefreshSeconds 値は、この値よりも古いエントリーだけが get オペレーションによる自動リ
フレッシュの対象となるように指定します。リフレッシュとは、エントリーの time-to-live（TTL）のカウントダウンをリセットするリロード処理のことを指します。 time-to-idle（TTI）の設定はア
クセス時にリセットされるため、その値がリフレッシュのタイムリミット（TTR）よりも大きくて
も、アクセスが無ければ何ら問題はありません。
例えば、TTR が 10 秒、TTL が 30 秒、そして TTI が 0（アイドルタイムが無限）のキャッシュに
おいて、 10 秒から 30 秒の間に発生するエントリーへのアクセスは、そのエントリーの自動リフレ
ッシュを誘発します。これによりエントリーはその TTL 期限より早くリロードされたものとしてみ
なされ、TTL タイマーはリセットされます。
22.3 事前リフレッシュのスケジュール設定
Quartzでスケジュールしたジョブを利用すると、事前リフレッシュを定期的に実行するようスケジ
ュール設定することができます。これらのジョブは、新規の値を非対称に読み込むことができます。
これには、設定したキャッシュローダを、CRON式で定義したスケジュールに基づいて利用します。
キャッシュのにあるデータの大部分を定期的に更新する場合は、このタイプの事前リフレッシュオ
ペレーションが役に立ちます。
事前リフレッシュのスケジュール設定を行なうには、キャッシュに少なくとも 1 つの
「CacheLoader」を構成設定してください。
22.3.1 事前リフレッシュのスケジュールの構成情報設定 事前リフレッシュのスケジュール設定は、キャッシュの拡張を使って構成設定します。
157
<cache ... <cacheLoaderFactory class="com.company.my.ConcreteCacheLoaderFactory" properties="some_property=1, some_other_property=2" /> <cacheExtensionFactory class="net.sf.ehcache.constructs.scheduledrefresh.ScheduledRefreshCacheExtensionFactory" properties="batchSize=100; quartzJobCount=2; cronExpression=0 0 12 * * ?" propertySeparator=";"/> ... </cache>
CRON 式には、プロパティに対するデフォルトの区切り文字であるコンマ（「,」）が含まれます。
ただし、propertySeparator 属性を使えば、異なる区切り文字を指定することもできます。
「cache-extension」クラスは事前リフレッシュの仕組みを実装するうえで必要不可欠です。このキ
ャッシュの拡張は、専用のQuartzスケジューラをインスタンス化します。事前リフレッシュのスケ
ジュールに設定した、クラスタ化していない各キャッシュに対して RamJobStoreを使用します。
スケジュール設定した事前リフレッシュの構成情報のプロパティは、「必須」と明記されていない
かぎり省略可能です。これらのプロパティについては、以下の表で説明します。
プロパティ 説明 デフォルト値
cronExpression 必須。CRON形式の文字列式です。事前リフレッシュのジョ
ブをいつ実行するかを管理します。詳細は、Quartzのドキ
ュメントを参照してください。
N/A
batchSize （整数です。）単一のジョブが一度にリフレッシュするキ
ーの数です。 100
keyGenerator Null の場合は、
net.sf.ehcache.constructs.scheduledrefresh.SimpleScheduledRefreshKeyGenerator を使ってキャッシュ内のすべてのキー
を列挙します。リフレッシュするキーをフィルターする場
合は、
net.sf.ehcache.constructs.scheduledrefresh.ScheduledRefreshKeyGenerator インターフェースを実装するクラスを指定
し、generateKeys()メソッドをオーバーライドするようにし
ます。
Null
useBulkLoad 「true」の場合、キーをキャッシュに読み込む際にノード
は一括ロードモードで書き込まれます。 false
quartzJobCount ScheduleRefreshCacheExtension のインスタンスによって作 2
158
成された Quartz のジョブストア内のスレッド数を制御しま
す。ジョブの制御に 1 つ、リフレッシュの一括ジョブを実
行するのに 1 つと、少なくとも 2 つのスレッドが必要で
す。この値のセットについては、常に追加スレッドが作成
されます。そのため、デフォルト値の「2」を指定すると、
（常に作成される）制御ジョブと 2 つのワーカースレッド
が作成され、入ってくるジョブを処理します。
scheduledRefreshName
デフォルトでは、基盤となる Quartz のジョブストアはキャ
ッシュマネージャー名とキャッシュ名の組み合わせを基に
して名付けられます。複数の ScheduledRefreshExtensionsを同じキャッシュに添付する場合は、このプロパティで
別々のインスタンスを名付けます。
Null
evictOnLoadMiss
リロードミス時に即時エビクションを強制（true）した
り、通常のエビクションを実行する前にはエビクションを
行なわない（false）ようにするブーリアン。「true」を指
定した場合、リロードの失敗（すべてのキャッシュローダ
が失敗）が理由でリフレッシュしないエントリーはエビク
ションによって破棄されます。この場合、たとえ「time-to-live」または「time-to-idle」で設定した有効期限が切れてい
なくとも、これらのエントリーは破棄されます。
true
jobStoreFactory デフォルトでは、RAMJobStore は Quartz のインスタンスに
よって使用されます。カスタムのジョブストアを定義する
には、
net.sf.ehcache.constructs.scheduledrefresh.ScheduledRefreshJobStorePropertiesFactory インターフェースを実装してくだ
さい。
net.sf.ehcache.constructs.scheduledrefresh.ScheduledRefreshRAMJobStoreFactory
jobStoreFactory のデフォルト値は、ScheduledRefreshRAMJobStoreFactory です。
22.4 CacheLoaderの実装
事前リフレッシュのオペレーションのエントリーをリロードするには、BigMemory Max の API を使って CacheLoaderFactory を実装する必要があります。構成情報の設定では、
net.sf.ehcache.loader.CacheLoaderFactory を拡張するコンクリートクラスを指定し、
createCacheLoader(myCache, properties)を呼び出してキャッシュのキャッシュローダーを作成しま
す。例えば、コンクリートクラスの構成情報が以下だとします。
<cache name="myCache" ... <cacheLoaderFactory class="com.company.my.ConcreteCacheLoaderFactory" Properties="some_property=1, some_other_property=2" /> <!-- Additional cacheLoaderFactory elements can be added. These form a chain so that if a CacheLoader returns null,
159
the next in line is tried. --> ... </cache>
その場合、以下のようにプログラムで使用することができます。
CacheLoader cacheLoader = ConcreteCacheLoaderFactory.createCacheLoader(myCache, properties); // Custom properties can be passed to the implemented CacheLoader.
リフレッシュしたエントリーを読み込むには、cacheLoader が CacheLoader.loadAll()メソッドを実
装する必要があります。
23 Ehcacheのトランザクション
23.1 はじめに
BigMemory Max は、xa_strict モードと xa モードのグローバルトランザクションと、local モードの
ローカルトランザクションをサポートしています。
23.1.1 全か無かの法則 キャッシュがトランザクション対応の場合、そのトランザクション処理の中ですべての処理が完了
する必要があります。完了できない処理がある場合は TransactionException がスローされます。
23.1.2 変更の可視性 BigMemory の Ehcache に提供されている分離レベルは READ_COMMITTED です。2 相コミットがサ
ポートされている場合、Ehcache は XAResource として動作します。具体的には、以下のとおりで
す。
• put、remove、putWithWriter、removeWithWriter、removeAll など、キャッシュ内容の変更方
法がトランザクション型である場合。
• COMMIT が呼び出されるまで、ローカル JVM やクラスタ内の他のトランザクションは、変更
されたキャッシュの内容を確認できません。
• コミットされる前に他のトランザクションが cache.get(...)などを実行すると、古い内容が使用
されます。読み取りアクセスのブロックは行いません。
23.2 トランザクションモードの選択
トランザクションモードは Ehcache の強力な拡張機能です。キャッシュやその他のデータストアに
対し、不可分なオペレーションを実行できるようになります。
160
• local：複数のキャッシュに対し、不可分な変更処理を提供するモードです。API の処理で一連
のキャッシュを変更する場合など、コミットやロールバックが必要になる場合に使用します。
あるキャッシュが、他のキャッシュのデータから計算した結果を保持している場合に便利です。
• xa： DBMS や JMS など、他のデータソースのデータをキャッシュに記録する場合で、JTA（Java Transaction API）の制御下で不可分の処理として実行したいものの、負荷の高い 2 相コ
ミットは避けたいときに利用するモードです。このモードのキャッシュは、トランザクション
内の他のリソースと同期しません。クラッシュが発生すると、データに不整合が生じる可能性
があります。したがって、古くなっても構わないデータを短時間だけ利用する場合などに使用
してください。
• xa_strict： xa モードと似ていますが、確実な XA 障害回復による保証が必要な場合に使用する
モードです。このモードのキャッシュは、トランザクション内の他のリソースと確実に同期し
ます。クラッシュが発生した場合も安全です。しかし、安全性と引き替えにパフォーマンスは
低下します。
23.3 必要事項
トランザクション対応のキャッシュに記録するオブジェクトは、以下の条件を満たしている必要が
あります。
• java.io.Serializable の実装： Terracotta のクラスタでキャッシュオブジェクトを保存するとき
に必要です。また、分離性を提供するための「copy on read」と「copy on write」の仕組みで
も、この実装が必要になります。
• equals と hashcode のオーバーライド：これらは、要素の値の比較結果に応じてトランザクシ
ョンを記録するよう、オーバーライドする必要があります。詳細は ElementValueComparatorと elementValueComparator の構成情報の設定を参照してください。
23.4 構成
トランザクションモードは、キャッシュ属性の transactionalMode を使用して、キャッシュごとに
設定します。指定できる値は次のとおりです。
• xa_strict
• xa
• local
• off
デフォルト値は「off」です。トランザクションモードに xa_strict を設定する例を以下に示します。
161
<cache name="xaCache" maxEntriesLocalHeap="500" eternal="false" timeToIdleSeconds="300" timeToLiveSeconds="600" diskExpiryThreadIntervalSeconds="1" transactionalMode="xa_strict"> </cache>
23.4.1 Spring使用時のトランザクション対応キャッシュ Spring を利用する場合は、以下の点に注意してください。
• Spring の@Transactional アノーテーション付きのメソッドからキャッシュにアクセスする場
合、begin/commit/rollback ステートメントは Spring が実行します。アプリケーションのコー
ドからこれらのステートメントを実行する必要はありません。
• Spring と Ehcache は、内部的にトランザクションマネージャーへアクセスします。このため、
Spring の PlatformTransactionManager で、使用するトランザクションマネージャーを指定し、
適切な方法で Ehcache を参照する必要があります。<
• Ehcache に対するデフォルトの参照方法では、使用するトランザクションマネージャーを特定
できません。例えば、WebSphere のトランザクションマネージャーなども検出できません
（詳細は[Transactions Managers]を参照してください）。
• 構成情報の<tx:method>に「read-only=true」を指定すると、WebSphere など、一部のトラン
ザクションマネージャーの利用で問題が発生する場合があります。
23.5 グローバルトランザクション
Ehcache はグローバルトランザクションをサポートしています。Ehcache は{XAResource}として動
作し、トランザクションマネージャーによる制御を受けながら JTA のトランザクションに参加しま
す。通常、トランザクションマネージャーはアプリケーションサーバが提供しますが、Bitronix な
どサードパーティの製品も利用できます。グローバルトランザクションを使用する場合は、トラン
ザクションモードに xa_strict または xa を指定してください。これらのモードの違いは、このペー
ジの前のほうのセクションを参照してください。
23.5.1 実装 グローバルトランザクションは、Store レベルに XATransactionStore と JtaLocalTransactionStore を
実装することでサポートされるようになります。XATransactionStore は、MemoryStore の実装を
Decorator で拡張しています。この拡張により、<XAResource>を通じて、トランザクションの分離
性を確保し、2 相コミットをサポートします。JtaLocalTransactionStore は、LocalTransactionStore Decorator でキャッシュを拡張します。これにより、TransactionController が提供する API ではな
162
く、標準 JTA で制御できます。初期化の際、Cache は TransactionManagerLookup の実装を利用し
て TransactionManager を参照します。その後、TransactionManagerLookup.register(XAResource)を使用して、新規作成した XAResource を登録します。保存動作は、すべての Element をキャッシュ
から読み込む、あるいはキャッシュへ書き込むよう、自動的に構成されます。Cache は「copy-on-read」および「copy-on-write」です。
23.6 障害回復
JTA の仕様に定義されているとおり、prepared トランザクションのデータだけが回復可能です。回
復準備のため、データはクラスタ上に永続化され、メモリもロックされます。つまり、非クラスタ
キャッシュは、トランザクションデータを永続化しません。クラッシュが発生した場合は、トラン
ザクションマネージャーがこれらのデータを報告します。
23.6.1 回復処理 何らかの問題が発生した場合は、XAResource の回復処理が必要になります。回復処理では、回復
準備が施されたデータのコミットまたはロールバックを行います。XA の仕様に従い、prepared が
設定されていないデータは破棄されます。回復の保証は xa モードによって異なります。
xa モード
xa モードの場合は、トランザクションマネージャーにキャッシュを{XAResource}として登録しませ
ん。しかし、JTA {Synchronization}を登録することで、JTA トランザクションの流れに従った処理
が可能になります。変更ノードの JVM にクラッシュが発生した場合、キャッシュの内容は不整合な
状態になります。このモードでクラッシュが発生した場合、キャッシュと、その他の XA リソース
（データベースなど）との間に不整合が発生する可能性があります。しかし、キャッシュ単体での
データの整合性は保たれます。これは、トランザクションが不可分な処理だからです。
xa_strict Mode
xa_strict モードの場合、TransactionManager は障害の発生したトランザクションの回復準備に用意
された XID を使用して、回復の呼び出しを行います。キャッシュは、この呼び出しに応答します。
こうして、トランザクションマネージャーは、各トランザクションに対し、コミットまたはロール
バックを実行します。これは、JTA 仕様のサポートによって標準 XA が提供する仕組みです。
23.7 サンプルアプリケーション
ここでは、さまざまなテクノロジーを駆使して XA を利用する 3 種類のサンプルアプリケーション
を紹介します。
23.7.1 XAサンプルアプリケーション このサンプルアプリケーションは、JBoss アプリケーションサーバを使用します。ユーザー管理の
トランザクションの例です。実際には、トランザクションを自前で管理するのではなく、Spring ま
たは EJB のコンテナから JTA を使用することが多いはずです。しかし、このサンプルでは、どのよ
163
うにトランザクションが管理されているのかを知ることができます。以下のコードは SimpleTX サ
ーブレットの一部で、トランザクションを示す部分です。
Ehcache cache = cacheManager.getEhcache("xaCache"); UserTransaction ut = getUserTransaction(); printLine(servletResponse, "Hello..."); try { ut.begin(); int index = serviceWithinTx(servletResponse, cache); printLine(servletResponse, "Bye #" + index); ut.commit(); } catch(Exception e) { printLine(servletResponse, "Caught a " + e.getClass() + "! Rolling Tx back"); if(!printStackTrace) { PrintWriter s = servletResponse.getWriter(); e.printStackTrace(s); s.flush(); } rollbackTransaction(ut); }
このコードを含むソースコードは、Terracotta Forgeから入手できます。サンプルアプリケーション
の使用方法はREADME.txtに記載してあります。
23.7.2 XAによる銀行向けアプリケーション このアプリケーションは、実際の業務で使用されるシナリオに準じています。Web アプリケーショ
ンがキューから<account transfer>メッセージを読み取り、そのアカウント転送の処理を開始します。
JTA を有効化しておくと、障害発生時にはロールバックが働くため、キャッシュ上の残高はデータ
ベースから取得した本当の残高と一致します。このアプリケーションは Spring をベースにした
Java の Web アプリケーションで、Jetty コンテナ内で動作します。以下のコンポーネントが埋め込
まれています。
• A メッセージブローカー（ActiveMQ）
• 2 つのデータベース（Derby XA インスタンス埋め込み）
• 2 つのキャッシュ（トランザクション対応の Ehcache）
Atomikos TransactionManager が、すべての XA リソースを管理します。トランザクションの境界は、
Spring AOP の@Transactional アノーテーションで区切ります。このアプリケーションは mvn clean
164
jetty:run で起動します。起動後、Web ブラウザでを開いてください。XA トランザクションを使用
していないときの動作を確認する場合は mvn clean jetty:run -Dxa=no を指定します。
このコードを含むソースコードは、Terracotta Forgeから入手できます。サンプルアプリケーション
の使用方法はREADME.txtに記載してあります。
23.7.3 Examinator ExaminatorはWebベースの試験アプリケーションで、キャッシュのさまざまな機能を利用していま
す。すべてTerracottaサーバアレイを利用しています。Terracotta Forgeからチェックアウトして使
用してください。
23.8 トランザクションマネージャー
23.8.1 自動検出できるトランザクションマネージャー Ehcache は、自動検出機能を利用して、トランザクションマネージャーを検索します。検索の順序
は以下のとおりです。
• GenericJNDI（例：Glassfish、JBoss、JTOM、および JNDI に登録済みで標準パス
「java:/TransactionManager」に記録されたすべてのトランザクションマネージャー）
• Weblogic (since 2.4.0)
• Bitronix
• Atomikos
これらに対する構成情報の設定は不要です。そのまま利用できます。最初に見つかったトランザク
ションマネージャーを使用します。
23.8.2 トランザクションの構成設定 前述の製品以外のトランザクションマネージャーを使用する場合や、検索の優先順位を変更する場
合は、net.sf.ehcache.transaction.manager.TransactionManagerLookup の実装に従って参照クラスを
変更し、ehcache.xml の DefaultTransactionManagerLookup に指定します。
<transactionManagerLookup class= "com.mycompany.transaction.manager.MyTransactionManagerLookupClass" properties="" propertySeparator=":"/>
ほかに、jndiName プロパティを DefaultTransactionManagerLookup に指定することで JNDI の参照
を変更する方法もあります。以下は、GlassFish v3 の TransactionManager の場所を指定する場合の
例です。
165
<transactionManagerLookup class="net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup" properties="jndiName=java:appserver/TransactionManager" propertySeparator=";"/>
23.9 ローカルトランザクション
1 つの CacheManager は複数のキャッシュを扱います。各キャッシュには、複数のオペレーション
が実行されます。ローカルトランザクションは、このような場合に、単相コミットを提供します。
この機能により、CacheManager 上の複数の変更を独自のトランザクションとして扱えるようにな
ります。トランザクションは、データベースなど、キャッシュ以外のリソースの変更にも応用でき
ます。トランザクションを開始後、手動でコミットやロールバックを実行することでデータの不整
合を防止できます。なお、トランザクションマネージャーはローカルトランザクションを制御しま
せん。代わりに、CacheManager が TransactionController への参照を取得するための API が提供さ
れています。cacheManager.getTransactionController()を呼び出し、それから独自のトランザクショ
ン処理を実行してください。ローカルトランザクションの実行手順は以下のとおりです。
• transactionController.begin()：現在のスレッドに、ローカルトランザクションが開始したこと
を知らせます。このあとの変更は、他のスレッドや他のトランザクションから不可視になりま
す。
• transactionController.commit()：トランザクションの呼び出しスレッドに、現在のトランザク
ションをコミットすることを知らせます。
• transactionController.rollback()：トランザクション呼び出しスレッドに、現在のトランザクシ
ョンをロールバックすることを知らせます。トランザクション開始後の変更はキャッシュに反
映されません。この処理は、try-catch ブロックの TransactionException をキャッチする部分で
実行してください。何らかの例外が発生した場合は、rollback()を呼び出します。ローカルト
ランザクションは、独自の例外をスローします。これらの例外は、すべて CacheException の
サブクラスです。以下の例外があります。
• TransactionException：一般的な例外。
• TransactionInterruptedException：キャッシュがトランザクションを処理しているときに
Thread.interrupt()が呼び出された場合に発生する例外。
• TransactionTimeoutException：タイムアウトのあとにコミットやキャッシュオペレーションが
呼び出された場合に発生する例外。
23.9.1 紹介ビデオ ローカルトランザクション作成の第一人者であるLudovic Orbanによる、ローカルトランザクション
の紹介ビデオが公開されています。
166
23.9.2 構成 ローカルトランザクションの構成情報は、次のように設定します。
<cache name="sampleCache" ... transactionalMode="local" </cache>
23.9.3 分離レベル ほかのトランザクションモードと同様、分離レベルは「READ_COMMITTED」です。
23.9.4 トランザクションのタイムアウト トランザクションがタイムアウト値で指定された時間内に完了しなかった場合は
TransactionTimeoutException がスローされます。transactionController.rollback()を呼び出して、キ
ャッシュの整合性を保証する必要があります。TransactionController は CacheManager のレベルで
動作しています。したがって、その CacheManager が扱うすべてのキャッシュに対し、同じタイム
アウト値が適用されます。タイムアウト値のデフォルト値は 15 秒です。値の変更方法は次のとお
りです。
transactionController.setDefaultTransactionTimeout(int defaultTransactionTimeoutSeconds)
begin()の呼び出した瞬間から時間の計測が始まります。JDBC 接続で、ほかのローカルトランザク
ションが発生する場合もあります。このため、複数の変更処理が同時に発生する場合もあります。
トランザクションが 15 秒よりも長くなりそうな場合は、トランザクション開始時に個別のタイム
アウト値を指定できます。
transactionController.begin(int transactionTimeoutSeconds) {
23.9.5 サンプルコード 2 つのキャッシュに対し、トランザクションで複数の処理を行うな場合の例を以下に示します。
CacheManager cacheManager = CacheManager.getInstance(); try { cacheManager.getTransactionController().begin(); cache1.put(new Element(1, "one")); cache2.put(new Element(2, "two")); cache1.remove(4); cacheManager.getTransactionController().commit(); } catch (CacheException e) { cacheManager.getTransactionController().rollback() }
167
23.10 パフォーマンス
23.10.1 競合の管理 スタンドアロンまたはクラスタのトランザクションが同時に 2 つ発生し、それらが同一の Elementに対するキャッシュオペレーションを開始した場合、以下のルールが適用されます。
• 1 番目のトランザクションがアクセス権を確保します。
• 2 番目のトランザクションによるキャッシュオペレーションは、1 番目のトランザクションが
完了するか、タイムアウトが発生するまでブロックされます。
実際の内部処理では、トランザクションが Element を利用する時点で新しい Element を作成し、
「ロックされている」というマークと、そのトランザクションの ID を記録します。ここでは、通
常のクラスタのセマンティクスが適用されます。トランザクションは「consistency=strong」のキャ
ッシュだけを扱います。したがって、1 番目のトランザクションが、不可分処理の一部として、
Element をに対するソフトロックを施す処理を管理するはずです。（これは、CAS ベースの
putIfAbsent メソッドと replace メソッドが行います。）
23.10.2 ロックの粒度 Ehcache は、Element のキーを利用して、Element に対するソフトロックを行います。
23.10.3 パフォーマンス比較 トランザクション対応のキャッシュへの書き込みには大きなオーバーヘッドが生じます。しかし読
み取りではほとんどオーバーヘッドは生じません。モード「off」における書き込みのパフォーマン
スを「1」とした場合、各モードの相対的なパフォーマンスは以下のとおりです。
• off - オーバーヘッドなし
• xa_strict - 20 倍（遅い）
• xa - 3 倍（遅い）
• local - 3 倍（遅い）
同様に、読み取りのパフォーマンスは以下のとおりです。
• off - オーバーヘッドなし
• xa_strict - 20 倍（遅い）
• xa - 30%（遅い）
• local - 30%（遅い）
168
以上からわかるとおり、完全な内容の保証が必要な場合のみ xa_strict を使用してください。そうで
ない場合は、ほかのモードの使用をお勧めします。
23.11 FAQ
23.11.1 一部のスレッドが定期的にタイムアウトを起こし、例外をスローします。なぜ
ですか。 トランザクション対応のキャッシュの要素に対し、更新、削除、追加を行うと、必ず書き込みロッ
クが発生します。こうしたキャッシュに同時アクセスが発生すると、一部のスレッドはロックされ、
デッドロックになる場合があります。デッドロックに陥ったスレッドは、やがてタイムアウトにな
り、例外をスローします。こうしてデッドロックが解消されます。
23.11.2 IBM Websphereのトランザクションマネージャーはサポートされていますか。 利用できますが、サポートされていない機能があります。xastrict はサポートされていません。こ
れは、Websphere の各バージョンが独自の実装を行っているからです。したがって、xastrict の実
装に適合するインターフェースがありません。その一方で、xa は TransactionManager のコールバ
ックを使用します。もちろん local はサポートされています。
Spring を使用する場合は、PlatformTransactionManager と Websphere TM を使用できるよう、構成
情報を正しく設定してください。
Ehcache が正しく動作することを確認するには、
com.ibm.websphere.jtaextensions.ExtendedJTATransaction に
com.ibm.websphere.jtaextensions.SynchronizationCallback を手動で登録します。そして、JNDI から
java:comp/websphere/ExtendedJTATransaction を取得して
com.ibm.websphere.jtaextensions.ExtendedJTATransaction にキャストし、
registerSynchronizationCallbackForCurrentTran メソッドを呼び出します。これが正しく動作すれば、
Ehcache も正しく動作します。
23.11.3 トランザクションは、どのようにライトビハインドキャッシュやライトスルー
キャッシュとやりとりするのでしょうか。 トランザクション対応のキャッシュをライターと一緒に使用する場合、書き込み処理はトランザク
ションがコミットされるまでキューに入ります。ライトスルーを利用するアプローチは、同時に使
用する XAResource と同じトランザクションに属する可能性があります。一方、ライトビハインド
もサポートされていますが、XA トランザクション対応のキャッシュと一緒に使用される可能性は
低いと考えられます。これは、オペレーションが同じトランザクションに属することがないからで
す。ライターを作成する場合は、新しいトランザクションを取得する必要があります。ライトスル
ーを非 XA リソースと共に使用した場合も動きますが、書き込みオペレーションが成功した後にト
ランザクションが成功するという保証はありません。その一方で、書き込みオペレーションで例外
が発生すると UserTransaction.commit()が RollbackException をスローするため、トランザクション
はロールバックします。
169
23.11.4 Hibernateのトランザクションはサポートされていますか。 Ehcache は、Hibernate のための「トランザクション対応」のキャッシュです。
net.sf.ehcache.hibernate.EhCacheRegionFactory は、構成情報に<cache usage="transactional"/>を含
む Hibernate のエンティティをサポートします。
23.11.5 WebLogic 10 でトランザクション対応のEhcacheを使用するにはどうしたらよい
でしょうか。 WebLogic は Terracotta の実装でサポートされていない最適化を使用します。デフォルト状態の場
合、WebLogic 10 は XAResource ごとのトランザクションを並行して起動します。Terracotta では、
これらのトランザクションを同一の Thread で実行する必要があるため、ドメインの構成情報で
parallel-xa-enabled オプションを false に設定し、この機能を無効化してください。
<jta> ... <checkpoint-interval-seconds>300</checkpoint-interval-seconds> <parallel-xa-enabled>false</parallel-xa-enabled> <unregister-resource-grace-period>30</unregister-resource-grace-period> ... </jta>
23.11.6 AtomikosでEhcacheのxaモードを使用するにはどうしたらよいでしょうか。 Atomikosには、xaモードの正常トランザクションの終了メカニズムが信頼できなくなるというバ
グ があります。このため、トランザクションマネージャーとしてAtomikosが使用されている場合、
トランザクション終了に異なるメカニズムを採用する機能が組み込まれています。
net.sf.ehcache.transaction.xa.alternativeTerminationModeをtrueに設定した場合も、この仕組みが有
効になります。この代替終了メカニズムには、トランザクションマネージャーのスレッドの扱い方
に厳しい制限があります。また、Atomikosのデフォルト設定では使用できません。この機能を正し
く動作させるには、以下のプロパティ構成を設定する必要があります。
com.atomikos.icatch.threaded_2pc=false
24 明示的ロック
24.1 はじめに
BigMemory Max の Ehcache は、リードおよびライトに使用できる明示的ロックを実装しています。
明示的ロックにより、Ehcache のロックの動作を細かく制御できます。これによりビジネスロジッ
クは、1 つ以上のキャッシュの 1 つ以上のキーに対し、保証された順番で不可分な変更を行うこと
が可能になります。したがって、XA トランザクションや Local トランザクションに代わり、カス
タマイズされた処理を実行することも可能です。
170
効果的ではあるものの、利用には注意が必要です。この API によって、ビジネスロジック内にデッ
ドロックが発生する場合もあるからです。
24.2 API Cache と Ehcache では、以下のメソッドを利用できます。
/** * Acquires the proper read lock for a given cache key * * @param key - The key that retrieves a value that you want to protect via locking */ public void acquireReadLockOnKey(Object key) { this.acquireLockOnKey(key, LockType.READ); } /** * Acquires the proper write lock for a given cache key * * @param key - The key that retrieves a value that you want to protect via locking */ public void acquireWriteLockOnKey(Object key) { this.acquireLockOnKey(key, LockType.WRITE); } /** * Try to get a read lock on a given key. If can't get it in timeout millis then * return a boolean telling that it didn't get the lock * * @param key - The key that retrieves a value that you want to protect via locking * @param timeout - millis until giveup on getting the lock * @return whether the lock was awarded * @throws InterruptedException */ public boolean tryReadLockOnKey(Object key, long timeout) throws InterruptedException { Sync s = getLockForKey(key); return s.tryLock(LockType.READ, timeout); } /** * Try to get a write lock on a given key. If can't get it in timeout millis then * return a boolean telling that it didn't get the lock * * @param key - The key that retrieves a value that you want to protect via locking
171
* @param timeout - millis until giveup on getting the lock * @return whether the lock was awarded * @throws InterruptedException */ public boolean tryWriteLockOnKey(Object key, long timeout) throws InterruptedException { Sync s = getLockForKey(key); return s.tryLock(LockType.WRITE, timeout); } /** * Release a held read lock for the passed in key * * @param key - The key that retrieves a value that you want to protect via locking */ public void releaseReadLockOnKey(Object key) { releaseLockOnKey(key, LockType.READ); } /** * Release a held write lock for the passed in key * * @param key - The key that retrieves a value that you want to protect via locking */ public void releaseWriteLockOnKey(Object key) { releaseLockOnKey(key, LockType.WRITE); } /** * Returns true if a read lock for the key is held by the current thread * * @param key * @return true if a read lock for the key is held by the current thread */ boolean isReadLockedByCurrentThread(Object key); /** * Returns true if a write lock for the key is held by the current thread * * @param key * @return true if a write lock for the key is held by the current thread */ boolean isWriteLockedByCurrentThread(Object key);
172
24.3 サンプル
簡単なサンプルを紹介します。
String key = "123"; Foo val = new Foo(); cache.acquireWriteLockOnKey(key); try { cache.put(new Element(key, val)); } finally { cache.releaseWriteLockOnKey(key); } ...sometime later String key = "123"; cache.acquireWriteLockOnKey(key); try { Object cachedVal = cache.get(key).getValue(); cachedVal.setSomething("abc"); cache.put(new Element(key, cachedVal)); } finally { cache.releaseWriteLockOnKey(key); }
24.4 動作の仕組み
READ ロックが取得済みの場合でも、ほかのスレッドは READ ロックを取得できます。また、読み
取りも可能です。ほかのスレッドが WRITE ロックを取得済みの場合、READ ロックは取得できず、
待ち状態に入ります。ほかのスレッドが READ ロックを取得済みの場合、WRITE ロックは取得で
きず、待ち状態に入ります。ロックのトラブルを防ぐため、利用後はロックの解放が必要です。ロ
ックの解放は finally ブロックで実行してください。読み取りの前に必ず READ ロックを取得し、書
き込みの前に必ず WRITE ロックを取得するようにすれば、分離レベルの READ_COMMITTED と同
等の処理が達成できます。
25 CacheWriterを用いたライトスルーとライトビハインド
25.1 はじめに
「ライトスルー」は、キャッシュの書き込み方式の 1 つです。キャッシュへ書き込むと、そのキャ
ッシュの元データを記録したリソースも同時に更新されます。つまり、キャッシュは、土台となる
リソースのファサード（表面）として機能します。この書き込み方式の場合、読み取りも「リード
173
スルー」となります。もう 1 つの「ライトビハインド」も、同様のクライアント API を使用します。
しかし、書き込みは非同期で行われます。
ファイルシステムや Web サービスクライアントと連携したキャッシュも多数存在します。しかし、
最も多いのはデータベースと連携したキャッシュです。説明をシンプルにするため、このページで
はキャッシュがデータベースを土台にしていると仮定します。
25.2 ライトビハインドの長所
ライトビハインド方式の主な長所は、データベースの負荷を低減できることです。これには、さま
ざまなシナリオが考えられます。
• タイムシフト：特定の時間に書き込む、あるいは特定の間隔で書き込むようにします。例えば、
書き込みを夜間バッチ処理で行います。あるいは毎時 5 分に書き込みます。このようなタイム
シフトを採用することで、処理がピークを迎えるときの書き込みを回避できます。
• 更新頻度の制限：時間ごとの更新回数を制限することで、書き込み頻度を平準化します。例え
ば POS（販売店舗のネットワーク）が業務終了直後に定常処理を実行し、中央サーバに書き込
み処理を行うとします。このような場合、すべての POS の処理が、同じ時間帯に発生します。
書き込み処理も、同時に多数発生します更新頻度を制限すれば、データベースの負荷を抑えら
れます。
• 併合：複数の書き込みを 1 つにまとめ、全体のトランザクション数を減らします。例えば、あ
るデータベースの行を更新する処理が 4 回あるとします。それぞれの処理では、元の値を 10、20、31、40、45 と増やします。処理を併合し、最初から 45 を書き込むようにすれば、書き
込み回数は 1 回で済みます。
これらのシナリオは、実際のシステムの制限や制約に合わせてプライオリティを設定し、適用して
ください。
25.3 ライトビハインドの制限と制約
25.3.1 トランザクションの境界 JTA トランザクションを利用している場合（つまりキャッシュが XAResource である場合）、キャ
ッシュ内容とデータベースとの整合性が保証されます。データベースへの書き込み、コミット、ロ
ールバックなどは、トランザクションの境界が明確です。ライトビハインドの場合は、キャッシュ
への書き込みが完了してからリソースへの書き込みを行います。トランザクションの境界は、書き
込み処理をキューに登録する部分になります。リソース本体への書き込みではありません。ライト
スルー方式の場合、明示的にコミットを行うと、キャッシュと、その土台となるリソースへの書き
込みが同時に行われます。しかし、ライトビハインド方式の場合、リソース本体への書き込みは、
トランザクション境界の外側になります。したがって、リソース本体への書き込みで障害が起こる
174
というリスクを常に抱えることになります。もちろん、このリスクは再試行回数や遅延などで軽減
できます。しかし、何らかの補償処理は必要です。
25.3.2 時間的な遅延 非同期書き込みの明らかな問題点は、データベース更新の遅延、つまりキャッシュ更新よりもあと
にデータベースが更新されることです。この時間は、キャッシュとデータベースとの間に不整合が
生じた状態になります。キャッシュの値は正しく、データベースの値は間違っています。この状態
はデータベースへの書き込みが完了した時点で、初めて解消します。CacheWriter メソッドに渡し
たデータは、書き込み処理が発生した時点でのスナップショットになります。したがって、直接デ
ータベースからデータをロードした値は正しくない可能性があります。
25.3.3 不整合に対応できるアプリケーション アプリケーションは、こうした不整合を正しく処理する必要があります。要件の例は以下のとおり
です。
• データベースにはトランザクションのログの追加だけを行います。
• 読み取りを行うのは、書き込みを行わないアプリケーションに限定します。これにより、不正
なデータの書き込みは発生しません。遅延は、アプリケーションの動作に影響しません。例え
ばニュースを表示するアプリケーションでユーザーが表示するのは、キャッシュに書き込まれ
た記事のほうです。
他のアプリケーションが直接データベースに書き込みを行うと、キャッシュとの不整合が簡単に発
生するので注意が必要です。
25.3.4 各ノードのタイマーの同期 クラスタ内の各ノードのタイマー（時計）は同期しておくのが理想です。ライトビハインドキャッ
シュのキューの内容は、タイムスタンプの順番で、土台となるリソースへ書き込まれます。このタ
イムスタンプは、キャッシュ操作のときに作成されます。ノードのタイマーが狂っていると、書き
込み順番も狂います。全ノードのタイマーが正確であれば、正しい順番で書き込まれるようになり
ます。この問題の対処は非常に簡単です。NTP（ネットワークタイムプロトコル）でインターネッ
ト時刻サーバと時刻を同期するように、各ノードを設定してください。
25.3.5 キャッシュからリソースへの書き込み順が保証されないことへの対応 基本的に、ライトビハインドキャッシュの書き込みキューは正しい順番に並んでいます。しかし順
番が保証されているわけではありません。特にクラスタ環境の場合、状況によっては処理の順番が
狂ってしまう場合も考えられます。さらに、一括処理の際は、CacheWriter がコレクションの書き
込みや削除を個別にまとめ、実際のキュートは異なる順番で処理します。したがって、項目が並べ
替えられたとしても正しく処理できるアプリケーションを用意する必要があります。あるいは、独
自の CacheWriter を作成し、順番の変更を補う処理を実装する必要があります。考えられる方法は
次のとおりです。
• キャッシュの要素に対し、バージョン番号を割り当てる。
175
キャッシュ内の各要素にバージョン番号を割り当てます。デフォルトでは自動バージョン設定
が OFF になっています。また、この機能はクラスタを使用しない環境のメモリ層のキャッシ
ュにしか利用できません。分散キャッシュや、オフヒープ層やディスク層を使用したキャッシ
ュでは、自動バージョン設定が利用できません。自動バージョン設定を有効化するには、シス
テムプロパティの net.sf.ehcache.element.version.auto を使用します（デフォルトは false）です。
自動バージョン設定を利用できないキャッシュに対してこの機能を有効化するとエラーが発生
します。ただし、メッセージ等は出力されません。
• キャッシュの対象となるリソースを確認し、関連するデータのライトビハインド処理がスケジ
ュールされているかどうかを確認する。
25.4 リードスルー方式とライトビハインド方式のキャッシュの組み合わせ
キャッシュとリソースに不整合があると正しく動作しないアプリケーションの場合は、常にライト
スルーのキャッシュを使用し、そのキャッシュに対してリードスルー処理を行うのが確実です。デ
ータベース書き込みに、常にライトスルー方式のキャッシュを使用すれば整合性が保証されます。
分散キャッシュを使用する場合、Terracotta クラスタは、クラスタ全体に対する整合性を保証しま
す。トランザクションを使用時、キャッシュは XAResource となります。したがって、コミットは
「キャッシュに対するコミット」となります。つまり、キャッシュそのものが SOR（System Of Record）として働きます。高可用性と持続性を誇る Terracotta のクラスタ化技術によって、キャッ
シュは十分に SOR として機能します。そして、データベースは、この SOR のバックアップとして
働きます。ライトビハインドとリードスルーを組み合わせる場合は、以下の点を考慮する必要があ
ります。
25.4.1 レイジーロード システムの起動時に、データセット全体をキャッシュにロードしておく必要はありません。リード
スルーキャッシュは、要求に応じてキャッシュにデータをロードする CacheLoader を使用します。
キャッシュの内容は、このようにして、あとからロードされます。
25.4.2 一部のデータセットだけをキャッシュ化 データセット全体をキャッシュにロードできない場合、キャッシュデータに対するアクセスの一部
はヒットしません。この結果、CacheLoader によるデータベースへのアクセスが発生します。ライ
トビハインド方式を採用している場合、データベースへの書き込みには遅延が生じます。このため、
データベースから読み込んだデータが最新であるとは限りません。最も簡単な解決策は、データベ
ースの内容をすべてキャッシュに取り込むことです。この場合、キャッシュ構成情報の有効期限や
エビクションを調整する必要があります。
エビクション
キャッシュ要素の数が最大に達すると、エビクション（要素の破棄）またはフラッシュ（要素の移
動）が発生します。エビクションやフラッシュが発生しないよう、適切なサイズをキャッシュに割
176
り当ててください。キャッシュのサイズの指定方法は「ストレージ層のサイズ指定」を参照してく
ださい。
有効期限
データベースの内容全体をキャッシュに搭載できたとしても、要素が有効期限を迎えると、エビク
ションが発生します。有効期限切れによるエビクションを防止するために、timeToLive と
timeToIdle の値に"0"（無期限）を設定してください。
25.5 紹介ビデオ
ライトビハインド方式の開発の第一人者であるAlex Snapsによる、ライトビハインドの紹介ビデオ
が公開されています。
25.6 サンプルアプリケーション
ライトビハインド方式の利用方法を紹介するため、「くじ引き（Raffle)」をおこなうサンプルWebアプリケーションを用意してあります。このアプリケーション（Ehcache-Raffle）は、Githubからダ
ウンロードできます。CacheWriterとCacheLoaderの理解に役立ててください。
25.7 構成情報
設定すべき構成情報は多数あります。設定できるプロパティとその効果は、
CacheWriterConfiguration を参照してください。XML を使った CacheWriter の構成情報の例を以下
に示します。
<cache name="writeThroughCache1" ... > <cacheWriter writeMode="write_behind" maxWriteDelay="8" rateLimitPerSecond="5" writeCoalescing="true" writeBatching="true" writeBatchSize="20" retryAttempts="2" retryAttemptDelaySeconds="2"> <cacheWriterFactory class="com.company.MyCacheWriterFactory" properties="just.some.property=test; another.property=test2" propertySeparator=";"/> </cacheWriter> </cache>
以下は、別の構成情報の例です。
<cache name="writeThroughCache2" ... > <cacheWriter/> </cache> <cache name="writeThroughCache3" ... > <cacheWriter writeMode="write_through" notifyListenersOnException="true" maxWriteDelay="30"
177
rateLimitPerSecond="10" writeCoalescing="true" writeBatching="true" writeBatchSize="8" retryAttempts="20" retryAttemptDelaySeconds="60"/> </cache> <cache name="writeThroughCache4" ... > <cacheWriter writeMode="write_through" notifyListenersOnException="false" maxWriteDelay="0" rateLimitPerSecond="0" writeCoalescing="false" writeBatching="false" writeBatchSize="1" retryAttempts="0" retryAttemptDelaySeconds="0"> <cacheWriterFactory class="net.sf.ehcache.writer.WriteThroughTestCacheWriterFactory"/> </cacheWriter> </cache> <cache name="writeBehindCache5" ... > <cacheWriter writeMode="write-behind" notifyListenersOnException="true" maxWriteDelay="8" rateLimitPerSecond="5" writeCoalescing="true" writeBatching="false" writeBatchSize="20" retryAttempts="2" retryAttemptDelaySeconds="2"> <cacheWriterFactory class="net.sf.ehcache.writer.WriteThroughTestCacheWriterFactory" properties="just.some.property=test; another.property=test2" propertySeparator=";"/> </cacheWriter> </cache>
以上の構成情報と同等の設定を Java プログラムで行うには、Cache のコンストラクタを使用します。
以下に例を示します。
Cache cache = new Cache( new CacheConfiguration("cacheName", 10) .cacheWriter(new CacheWriterConfiguration() .writeMode(CacheWriterConfiguration.WriteMode.WRITE_BEHIND) .maxWriteDelay(8) .rateLimitPerSecond(5) .writeCoalescing(true) .writeBatching(true) .writeBatchSize(20) .retryAttempts(2) .retryAttemptDelaySeconds(2) .cacheWriterFactory(new CacheWriterConfiguration.CacheWriterFactoryConfiguration() .className("com.company.MyCacheWriterFactory") .properties("just.some.property=test; another.property=test2") .propertySeparator(";"))));
178
CacheWriterFactoryConfiguration で CacheWriter を作成作成するのではなく、Java のコードから明
示的に CacheWriter インスタンスを登録することも可能です。コードで作成した場合は、データベ
ース接続のハンドルやファイルのハンドルなど、ローカルなリソースの参照が可能になります。
Cache cache = manager.getCache("cacheName"); MyCacheWriter writer = new MyCacheWriter(jdbcConnection); cache.registerCacheWriter(writer);
25.7.1 構成情報の属性 CacheWriterFactory には、以下の属性を指定できます。
すべてのモードで使用できる属性
• writeMode [write-through | write-behind]：ライトスルー方式とライトビハインド方式のどちら
を採用するのかを指定します。デフォルト値は"write-through"です。
ライトスルーモードのときに使用できる属性
• notifyListenersOnException：リソース更新（ストア操作）で発生した例外をリスナーに通知す
るかどうかを指定します。デフォルト値は"false"です。キャッシュのレプリケーションを使用
する場合は、キャッシュ対象のデータソースのレプリケーションも有効にする必要があります。
したがって、この属性を"true"に設定してください。
ライトビハインドモードのときに使用できる属性
• writeBehindMaxQueueSize：キューまたはバケット（1 つのキューに複数のバケットがある場
合）に登録できる要素数の最大値を指定します。デフォルト値は"0"で、これは無制限である
ことを表します。キュー（またはバケット）に要素を追加すると、キューの空きサイズが確認
されます。キューが一杯だった場合、キューの要素が 1 つ減るまで、そのオペレーションはブ
ロックされます。リソースへの書き込みが実行中の要素、一括処理で書き込む要素（併合済み
の要素）は、このサイズに含まれません。この属性をプログラムから設定するには
net.sf.ehcache.config.CacheWriterConfiguration.setWriteBehindMaxQueueSize()を実行します。
• writeBehindConcurrency：ノード上の特定キャッシュに対するスレッドとバケットのペアの数
を指定します。デフォルト値は"1"です。各スレッドは、ライトビハインドに設定された構成
情報を使用します。例えば rateLimitPerSecond に 100 を設定した場合、スレッドとバケット
のペアも、それぞれ 1 秒当たり 100 回の処理を実行します。キャッシュに対して
「writeBehindConcurrency="4"」を同時に指定しておけば、そのノードでは 1 秒あたり 400 回
の処理が実行されることになります。この属性をプログラムから設定するには
net.sf.ehcache.config.CacheWriterConfiguration.setWriteBehindConcurrency()を実行します。
• maxWriteDelaySeconds：ライトビハインドによる書き込み遅延時間の最大値を指定します。
デフォルトは"0"です。0 より大きい値を設定すると、キューに蓄積した操作が効果的に併合
やバッチ処理を行えるようになります。
179
• rateLimitPerSecond： 1 秒当たりのリソース更新回数の最大値を指定します。
• writeCoalescing：書き込み処理の併合（複数の書き込み要求を 1 つにまとめること）を行うか
どうかを指定します。デフォルト値は"false"です。"true"に設定すると、ライトビハインドの
キューの中に同一のキーが存在した場合、最後の書き込み要求だけを実行します。（最後の書
き込み要求以外は余分なためスキップします。）この処理により、書き込み対象のリソースの
負荷を大きく低減できます。
• writeBatching：一括書き込み処理を行うかどうかを指定します。デフォルト値は"false"です。
"true"に設定すると、値を個別に更新するオペレーション（store または delete）ではなく、一
括して更新するオペレーション（storeAll または deleteAll）が使用されます。一括更新ではデ
ータベースのようなリソースを効率的に更新できるため、これらの負荷を低減できます。
• writeBatchSize：一括処理に含めることのできるオペレーションの数を指定します。デフォル
トは"1"です。ライトビハインドのキューのエントリー数が一括処理のサイズよりも小さい場
合は、キューにあるエントリーの数が優先します。一括処理では、オペレーションを区別して
併合します。例えば writeBatchSize が"10"のときに、5 つの put（更新）と 5 つの delete（削
除）がキューに登録されたとします。この時点で CacheWriter は処理を開始します。put が 10に、delete が 10 になるのを待つわけではありません。
• retryAttempts：キューからの書き込みの再試行回数を指定します。デフォルトは"1"です。
• retryAttemptDelaySeconds：再試行前の待機時間を指定します。単位は「秒」です。
25.8 API API から CacheLoader を使用するには cache.getWithLoader(...)メソッドを使用します。API から
CacheWriter を使用するには、cache.putWithWriter(...)メソッドと cache.removeWithWriter(...)メソ
ッドを使用します。cache.putWithWriter(...)メソッドのシグネチャを以下に紹介します。
/** * Put an element in the cache writing through a CacheWriter. If no CacheWriter has been * set for the cache, then this method has the same effect as cache.put(). * * Resets the access statistics on the element, which would be the case if it has previously * been gotten from a cache, and is now being put back. * * Also notifies the CacheEventListener, if the writer operation succeeds, that: * * - the element was put, but only if the Element was actually put. * - if the element exists in the cache, that an update has occurred, even if the element * would be expired if it was requested *
180
* * @param element An object. If Serializable it can fully participate in replication and the * DiskStore. * @throws IllegalStateException if the cache is not * {@link net.sf.ehcache.Status#STATUS_ALIVE} * @throws IllegalArgumentException if the element is null * @throws CacheException */ void putWithWriter(Element element) throws IllegalArgumentException, IllegalStateException, CacheException;
完全な API は Cache の JavaDoc を参照してください。
25.9 SPI CacheWriter インターフェースは、Ehcache のライトスルーの SPI です。キャッシュの土台となる
リソースにアクセスするには、このインターフェースを実装する必要があります。
/** * A CacheWriter is an interface used for write-through and write-behind caching to a * underlying resource. * <p/> * If configured for a cache, CacheWriter's methods will be called on a cache operation. * A cache put will cause a CacheWriter write * and a cache remove will cause a writer delete. * <p> * Implementers should create an implementation which handles storing and deleting to an * underlying resource. * </p> * <h4>Write-Through</h4> * In write-through mode, the cache operation will occur and the writer operation will occur * before CacheEventListeners are notified. If * the write operation fails an exception will be thrown. This can result in a cache which * is inconsistent with the underlying resource. * To avoid this, the cache and the underlying resource should be configured to participate * in a transaction. In the event of a failure * a rollback can return all components to a consistent state. * <p/> * <h4>Write-Behind</h4> * In write-behind mode, writes are written to a write-behind queue. They are written by a * separate execution thread in a configurable * way. When used with Terracotta Server Array, the queue is highly available. In addition
181
* any node in the cluster may perform the * write-behind operations. * <p/> * <h4>Creation and Configuration</h4> * CacheWriters can be created using the CacheWriterFactory. * <p/> * The manner upon which a CacheWriter is actually called is determined by the * {@link net.sf.ehcache.config.CacheWriterConfiguration} that is set up for a cache * using the CacheWriter. * <p/> * See the CacheWriter chapter in the documentation for more information on how to use writers. * * @author Greg Luck * @author Geert Bevin * @version $Id: $ */ public interface CacheWriter { /** * Creates a clone of this writer. This method will only be called by ehcache before a * cache is initialized. * <p/> * Implementations should throw CloneNotSupportedException if they do not support clone * but that will stop them from being used with defaultCache. * * @return a clone * @throws CloneNotSupportedException if the extension could not be cloned. */ public CacheWriter clone(Ehcache cache) throws CloneNotSupportedException; /** * Notifies writer to initialise themselves. * <p/> * This method is called during the Cache's initialise method after it has changed it's * status to alive. Cache operations are legal in this method. * * @throws net.sf.ehcache.CacheException */ void init(); /** * Providers may be doing all sorts of exotic things and need to be able to clean up on
182
* dispose. * <p/> * Cache operations are illegal when this method is called. The cache itself is partly * disposed when this method is called. */ void dispose() throws CacheException; /** * Write the specified value under the specified key to the underlying store. * This method is intended to support both key/value creation and value update for a * specific key. * * @param element the element to be written */ void write(Element element) throws CacheException; /** * Write the specified Elements to the underlying store. This method is intended to * support both insert and update. * If this operation fails (by throwing an exception) after a partial success, * the convention is that entries which have been written successfully are to be removed * from the specified mapEntries, indicating that the write operation for the entries left * in the map has failed or has not been attempted. * * @param elements the Elements to be written */ void writeAll(Collection<Element> elements) throws CacheException; /** * Delete the cache entry from the store * * @param entry the cache entry that is used for the delete operation */ void delete(CacheEntry entry) throws CacheException; /** * Remove data and keys from the underlying store for the given collection of keys, if * present. If this operation fails * (by throwing an exception) after a partial success, * the convention is that keys which have been erased successfully are to be removed from * the specified keys, indicating that the erase operation for the keys left in the collection * has failed or has not been attempted. * * @param entries the entries that have been removed from the cache
183
*/ void deleteAll(Collection<CacheEntry> entries) throws CacheException; /** * This method will be called whenever an Element couldn't be handled by the writer and all of * the {@link net.sf.ehcache.config.CacheWriterConfiguration#getRetryAttempts() retryAttempts} * have been tried. * <p>When batching is enabled, all of the elements in the failing batch will be passed to * this method. * <p>Try to not throw RuntimeExceptions from this method. Should an Exception occur, * it will be logged, but the element will still be lost. * @param element the Element that triggered the failure, or one of the elements in the * batch that failed. * @param operationType the operation we tried to execute * @param e the RuntimeException thrown by the Writer when the last retry attempt was * being executed */ void throwAway(Element element, SingleOperationType operationType, RuntimeException e); }
25.10 FAQ ライトビハインドのキャッシュの空きサイズを確認する方法はありますか。
net.sf.ehcache.statistics.LiveCacheStatistics#getWriterQueueLength()メソッドを使用してください。
このメソッドは、ローカルキュー（ローカルバケット全体）に登録された書き込み待ち要素の数を
返します。ライトビハインドのキューが空の場合は「-1」を返します。リソースへの書き込みが実
行中の要素、一括処理で書き込む要素（併合済みの要素）は、この戻り値に含まれません。
CacheWriter などの書き込み処理の呼び出しで例外が発生した場合はどうなりますか。
書き込みの再試行回数の上限を超えると、例外が発生した要素（または一括処理の対象となる全要
素）が net.sf.ehcache.writer.CacheWriter#throwAway メソッドに渡されます。これにより、書き込
みに失敗した要素に対する最終的な対処を、ユーザーが作成したメソッドで実行できるようになり
ます。要素の処理で最後にスローされた RuntimeException への参照と、その例外が発生したオペ
レーションの種類が取得できます。要素に対する最終的な対処を行うユーザーメソッドで例外が発
生した場合は、その例外がログに記録されるだけで、それ以外の処理は発生しません。この場合、
この要素は完全に失われます。したがって、要素に対する最終的な対処を行うメソッドを実装する
際は、例外に対して適切な対処を行うよう注意してください。
184
これには、CacheWriter などを使って、例外が発生したオペレーションと要素を永続化したキャッ
シュに記録しておく方法が考えられます。ユーザーがこの情報を監視し、あとから発生したエラー
に手動で対処するとよいでしょう。
26 BlockingキャッシュとSelf-Populatingキャッシュ
26.1 はじめに
net.sf.ehcache.constructs パッケージには、拡張キャッシュクラスが同梱されています。これらのキ
ャッシュは、日々のキャッシュの問題を解決するためにコアとなるクラスを使用します。この拡張
キャッシュとは、BlockingCache と SelfPopulatingCache です。
26.2 Blockingキャッシュ
例えば、常に 1000 人以上のユーザが同時にアクセスする Web サイトがあったとします。このサイ
トでは、ユーザによる各ページのアクセス頻度が均等ではなく、一部のページに集中する傾向があ
ります。アクセスが集中するのは、数分で内容が陳腐化するようなデータを扱う動的なページです。
これ以外にも、数分で内容の更新が必要になるデータのコレクションといった例が考えられます。
いずれの場合も、その都度データを計算するのでは負荷が高すぎます。各リクエストのスレッドは、
ほとんど同じデータを要求していると考えてよいでしょう。リクエストのたびに計算を実行して結
果を返すのは無駄です。こうした場合にキャッシュを使用します。各スレッドがキャッシュへアク
セスするようにします。キャッシュにデータがない場合のみ、新しいデータを用意して、それをキ
ャッシュに配置します。
それでは、多数のユーザが同じデータを同時にリクエストするケースを考えてみましょう。ユーザ
のリクエストに応じて計算を実行し、それをキャッシュに配置します。ところが、全く同じことを
同時に 10 人のユーザーが実行しています。このような場合、アップストリームシステムは、本来
必要な処理の 10 倍の処理を行うことになります。たとえ、JSP ページだったとしても velocity ペー
ジだったとしても、あるいはサーバレイヤーへのアクセスだったとしてもデータベースへのアクセ
スだったとしても、無駄な処理であることは間違いありません。このようなケースには
BlockingCache を導入します。このキャッシュは、最初のスレッドの処理が完了するまで、同じキ
ーに対するスレッドの処理をブロックし、待ち状態にします。最初のスレッドが完了したら、残り
のスレッドはキャッシュから取得した値を返すだけで済みます。このようにして、BlockingCacheはアクセス量の多いシステムをスケールアップできます。ブロックによる待ち時間は、コンストラ
クタ引数の timeoutMillis で設定できます。無制限にすることも可能です。
Blocking Cacheの詳細は Javadocを参照してください。
185
26.3 SelfPopulatingキャッシュ
BlockingCacge を使用したいものの、常にロックの解放を行うようにすると危険なコードを生成す
る可能性が生じる場合もあります。キャッシュのことを気にせず、処理内容だけに集中したい場合
もあります。このような場合は SelfPopulatingCache を導入します。SelfPopulatingCache は、一般的
なキャッシュ用語のプルスルー型キャッシュと同義です。ただし、SelfPopulatingCache は、
BlockingCache の拡張です。SelfPopulatingCache は CacheEntryFactory を使用します。このキーを使
用して、どのエントリーを展開すべきかを決定します。補足：SelfPopulatingCache は、
CacheLoader と連携する Ehcache の getWithLoader および getAllWithLoader ディレクトリから生成
した JCache でも代用できます。
Self-PopulatingCacheの詳細は Javadocを参照してください。
27 Terracottaクラスタイベント
27.1 はじめに
Terracotta BigMemory Max のクラスタイベント API を利用すると、Terracotta 関連のクラスタイベ
ントやクラスタトポロジにアクセスできるようになります。このイベント通知の仕組みは、
Terracotta クラスタのノード関連イベントを通知しますが、キャッシュイベントは通知しません。
27.2 クラスタトポロジ
net.sf.ehcache.cluster.CacheCluster インターフェースは、Terracotta クラスタのトポロジ情報を取得
するためのメソッドを提供します。以下のメソッドを利用できます。
• String getScheme()
クラスタ情報のスキーム名を返します。現在サポートされているスキームは、TERRACOTTAのみです。スキーム名は、「CacheManager.getCluster()」がクラスタ情報を返す際に使用しま
す。
• Collection<ClusterNode> getNodes()
ID、ホスト名、IP アドレスなど、クラスタのノードに登録されたすべての情報を返します。
• boolean addTopologyListener(ClusterTopologyListener listener)
クラスタのイベントリスナーを追加します。リスナーがすでにアクティブな場合は、「true」を返します。
• boolean removeTopologyListener(ClusterTopologyListener)
186
クラスタのイベントリスナーを削除します。リスナーがすでにアクティブでない場合は、
「true」を返します。
net.sf.ehcache.cluster.ClusterNode インターフェースは、特定のクラスタノード情報を取得するメソ
ッドを提供します。
public interface ClusterNode { /** * Get a unique (per cluster) identifier for this node. * * @return Unique per cluster identifier */ String getId(); /** * Get the host name of the node * * @return Host name of node */ String getHostname(); /** * Get the IP address of the node * * @return IP address of node */ String getIp(); }
27.3 クラスタイベントの待ち受け
net.sf.ehcache.cluster.ClusterTopologyListener インターフェースは、クラスタイベントを検出するメ
ソッドを提供します。提供されるメソッドは以下のとおりです。
public interface ClusterTopologyListener { /** * A node has joined the cluster * * @param node The joining node */ void nodeJoined(ClusterNode node); /** * A node has left the cluster
187
* * @param node The departing node */ void nodeLeft(ClusterNode node); /** * This node has established contact with the cluster and can execute clustered operations. * * @param node The current node */ void clusterOnline(ClusterNode node); /** * This node has lost contact (possibly temporarily) with the cluster and cannot execute * clustered operations * * @param node The current node */ void clusterOffline(ClusterNode node); } /** * This node lost contact and rejoined the cluster again. * * This event is only fired in the node which rejoined and not to all the connected nodes * @param oldNode The old node which got disconnected * @param newNode The new node after rejoin */ void clusterRejoined(ClusterNode oldNode, ClusterNode newNode);
27.3.1 サンプルコード 以下のサンプルは、最初にクラスタノードのリストを画面に出力します。その後、イベントを発生
順に出力するための ClusterTopologyListener を登録します。
CacheManager mgr = ... CacheCluster cluster = mgr.getCluster("TERRACOTTA"); // Get current nodes Collection<ClusterNode> nodes = cluster.getNodes(); for(ClusterNode node : nodes) { System.out.println(node.getId() + " " + node.getHostname() + " " + node.getIp()); } // Register listener cluster.addTopologyListener(new ClusterTopologyListener() {
188
public void nodeJoined(ClusterNode node) { System.out.println(node + " joined"); } public void nodeLeft(ClusterNode node) { System.out.println(node + " left"); } public void clusterOnline(ClusterNode node) { System.out.println(node + " enabled"); } public void clusterOffline(ClusterNode node) { System.out.println(node + " disabled"); } public void clusterRejoined(ClusterNode node, ClusterNode newNode) { System.out.println(node + " rejoined the cluster as " + newNode); } });
プログラムから CacheManager インスタンスの作成と構成設定を行った場合（ehcache.xml や外部
構成情報リソースを使用しない場合）、Terracotta クラスタが存在しているのに
getCluster("TERRACOTTA")が Null を返すことがあります。この現象を回避してクラスタ情報を正し
く取得するには、Terracotta でクラスタ化したキャッシュを取得します。
// mgr created and configured programmatically.
CacheManager mgr = new CacheManager();
// myCache has Terracotta clustering. Cache cache = mgr.getEhcache("myCache");
// A Terracotta client has started, making available cluster information.
CacheCluster cluster = mgr.getCluster("TERRACOTTA");
注意：プログラムによるキャッシュマネージャーの作成
カレントノードの nodeJoined
カレントノードがクラスタと接続するのは、トポロジリスナーを追加するコードが実行される前で
す。このため、nodeJoined イベントの通知を受信できないことがあります。カレントノードの接続
が完了すると、クラスタはオンラインになります。したがって、クラスタがオンラインであること
を先に確認してください。
cluster.addTopologyListener(cacheListener); if(cluster.isClusterOnline()) { cacheListener.clusterOnline(cluster.getCurrentNode()); }
189
28 Cache Decorator
28.1 はじめに
BigMemory Max は、Cache クラスの実装に Ehcache インターフェースを使用しています。Cache イ
ンスタンスが使用する Ehcache の Decorator を作成し、Ehcache の実装と追加機能を提供してくだ
さい。
Decorator は、GoF（Gang of Four）によるデザインパターンの 1 つです。
Decorator で拡張したキャッシュを使用するには、CacheManager から
CacheManager.getEhcache(String name)を呼び出します。下位互換のため、
CacheManager.getCache(String name)も提供されています。しかし、Decorator で拡張したキャッシ
ュを返すのは CacheManager.getEhcache(String name)だけです。
28.2 Decoratorの作成
28.2.1 プログラムを使用する作成 キャッシュ Decorator は、次のように作成します。
BlockingCache newBlockingCache = new BlockingCache(cache);
クラスには Ehcache を実装してください。
28.2.2 構成を使用する作成 キャッシュ Decorator の構成情報は、ehcache.xml で設定します。ここで設定した Decorator が
CacheManager クラスに追加されます。
そして、net.sf.ehcache.constructs.CacheDecoratorFactory を継承した具象クラスの名前を受け取りま
す。
プロパティは区切り文字（デフォルト値はカンマ「,」）ごとに解析され、そのキャッシュ自身に対
する参照と共に具象ファクトリの createDecoratedEhcache(Ehcache cache, Properties properties)メソッドへ渡されます。
以下に、Decorator の構成情報の例を示します。
<cacheDecoratorFactory class="com.company.SomethingCacheDecoratorFactory" properties="property1=36 ..." />
なお、Decorator は defaultCache に構成できます。Hibernate のような、defaultCache の拡張キャッ
シュを追加するフレームワークを作成する際には、特に便利です。
190
28.3 Decoratorによる拡張キャッシュのCacheManagerへの追加
プログラムから作成した Decorator は、複数のスレッドがアクセスする場所へ配置するのが便利で
す。なお、CacheManager は、ehcache.xml の構成情報で作成した Decorator を既に含んでいます。
28.3.1 CacheManager.replaceCacheWithDecoratedCache()の使用 ビルトインによる方法を使用する場合は、CacheManager 内の Cache を Decorator で拡張した Cacheに置き換えます。置き換え方法の例は以下のとおりです。
cacheManager.replaceCacheWithDecoratedCache(cache, newBlockingCache);
CacheManager の{replaceCacheWithDecoratedCache}メソッドは、キャッシュが、その基底キャッシ
ュと同じ名前でビルドされていることを前提にしています。
なお、一般的な Java のルールに従い、オーバーライドされた Ehcache のメソッドは変数のキャス
トを行いません。キャストが必要になるのは Decorator によって追加された新しいメソッドを使用
する場合だけです。
以上で、CacheManager に対してキャッシュの取り出しを要求すると、Decorator で拡張されたキャ
ッシュを返すようになります。
注意：複数のスレッドからこのメソッドを呼び出す場合は、最初に同期型メソッドで正しく初期化
しておく必要があります。また、すべてのスレッドから、同一のキャッシュ（Decorator で拡張さ
れたキャッシュ）を参照してください。適切な初期化メソッドの例は CachingFilter を参照してくだ
さい。
/** * The cache holding the web pages. Ensure that all threads for a given cache name * are using the same instance of this. */ private BlockingCache blockingCache; /** * Initialises blockingCache to use * * @throws CacheException The most likely cause is that a cache has not been * configured in Ehcache's configuration file ehcache.xml * for the filter name */ public void doInit() throws CacheException { synchronized (this.getClass()) { if (blockingCache == null) { final String cacheName = getCacheName();
191
Ehcache cache = getCacheManager().getEhcache(cacheName); if (!(cache instanceof BlockingCache)) { //decorate and substitute BlockingCache newBlockingCache = new BlockingCache(cache); getCacheManager().replaceCacheWithDecoratedCache(cache, newBlockingCache); } blockingCache = (BlockingCache) getCacheManager().getEhcache(getCacheName()); } } } Ehcache blockingCache = singletonManager.getEhcache("sampleCache1");
戻り値のキャッシュは、Decorator による拡張を備えています。
28.3.2 CacheManager.addDecoratedCache()の使用 Decorator によって拡張されたキャッシュを利用する一方で、その基底キャッシュへのアクセスも
確保したい場合があります。
このような場合は、Decorator で拡張キャッシュを作成してから cache.setName(new_name)を呼び
出し、さらに CacheManager.addDecoratedCache()を使用して CacheManager に追加します。
/** * Adds a decorated {@link Ehcache} to the CacheManager. This method neither creates * the memory/disk store nor initializes the cache. It only adds the cache reference * to the map of caches held by this cacheManager. * * It is generally required that a decorated cache, once constructed, is made available * to other execution threads. The simplest way of doing this is to either add it to * the cacheManager with a different name or substitute the original cache with the * decorated one. * * This method adds the decorated cache assuming it has a different name. If another * cache (decorated or not) with the same name already exists, it will throw * {@link ObjectExistsException}. For replacing existing * cache with another decorated cache having same name, please use * {@link #replaceCacheWithDecoratedCache(Ehcache, Ehcache)} * * Note that any overridden Ehcache methods by the decorator will take on new * behaviours without casting. Casting is only required for new methods that the * decorator introduces. For more information see the well known Gang of Four
192
* Decorator pattern. * * @param decoratedCache * @throws ObjectExistsException * if another cache with the same name already exists. */ public void addDecoratedCache(Ehcache decoratedCache) throws ObjectExistsException {
28.4 ビルトインのDecorator
28.4.1 BlockingCache {@link Ehcache}に基づき、Ehcache へのアクセスをブロックするための拡張機能です。
キャッシュ内の要素に対して同時に発生する読み取りアクセスをサポートします。要素が NULL の
場合、同一のキーを持つ値がキャッシュに記録されるまで、ほかの読み取りアクセスがブロックさ
れます。この機能は、リードスルー型や Self-Populating Cache に便利です。BlockingCache は
CachingFilter が使用します。
28.4.2 SelfPopulatingCache これは、Decorator で拡張した Self-Populating 型の Ehcache です。要求に応じてエントリーを作成
します。
クライアントは単純にキャッシュを呼び出します。キャッシュ内にエントリーがあるかどうかを気
にする必要はありません。エントリーが NULL だった場合はキャッシュが作成されます。キャッシ
ュはリフレッシュされるようになっています。リフレッシュは、基底となるキャッシュに対して実
施されます。呼び出しによるパフォーマンスの低下はありません。
SelfPopulatingCache は BlockingCache を継承しています。NULL 要素に対して複数のスレッドから
アクセスがあった場合は、最初のスレッドの処理が完了するまで、ほかのスレッドのアクセスがブ
ロックされます。リフレッシュ処理中にキャッシュへのアクセスがあった場合は、そのアクセスを
ブロックせず、古いデータを返します。この機能は、高度にスケーラブルなシステムの設計に便利
です。
28.4.3 例外処理を備えたキャッシュ この機能も、Decorator によるキャッシュ拡張です。詳細は「Cache Exception ハンドラー」を参照
してください。
193
29 イベントリスナー
29.1 CacheManagerのイベントリスナー
BigMemory Max の Ehcache には、CacheManager のイベントリスナーも実装されています。これら
のリスナーを利用することで、CacheManager のイベントが発生したときにコールバックされるメ
ソッドの実装も利用できるようになります。Cache クラスのリスナーは
CacheManagerEventListener インターフェースを実装します。イベントには以下のようなものがあ
ります。
• Cache の追加。
• Cache の削除
コールバック方法には、同期型と非同期型の両方があります。実装する際は、リスナーが実行して
いる処理に配慮し、スレッドセーフとパフォーマンスを損なわないように注意が必要です。
29.1.1 構成 CacheManager のインスタンスには、1 つの CacheManagerEventListenerFactory と、それに伴う 1つの CacheManagerEventListener を指定できます。ファクトリは以下のように構成されています。
<cacheManagerEventListenerFactory class="" properties=""/>
このエントリーでは、ファクトリ CacheManagerEventListenerFactory を指定します。このファクト
リは、CacheManagerEventListener の作成に使用されます。こうして作成されたリスナーが、
CacheManager における Cache の追加や削除といったイベントの通知を受信します。
CacheManagerEventListenerFactory の属性は以下のとおりです。
• class：ファクトリクラスの完全修飾名です。
• properties：ファクトリが使用するプロパティをカンマで区切って指定します。
リスナーメソッドのコールバック方法には、同期型と非同期型の両方があります。実装する際は、
リスナーが実行している処理に配慮し、スレッドセーフとパフォーマンスを損なわないように注意
が必要です。クラスが指定されていない場合、あるいは cacheManagerEventListenerFactory 要素が
ない場合、リスナーは作成されません。デフォルト値はありません。
29.1.2 CacheManagerのイベントリスナーファクトリとイベントリスナーの実装 CacheManagerEventListenerFactory は、CacheManager のリスナーを作成するための抽象ファクト
リです。この抽象ファクトリを継承して、独自の具象ファクトリを実装してください。実装した具
象ファクトリの構成情報は ehcache.xml で設定します。ファクトリクラスは、以下に示すとおり、
抽象ファクトリ CacheManagerEventListenerFactory の具象サブクラスである必要があります。
194
/** * An abstract factory for creating {@link CacheManagerEventListener}s. Implementers should * provide their own concrete factory extending this factory. It can then be configured in * ehcache.xml * */ public abstract class CacheManagerEventListenerFactory { /** * Create a CacheEventListener * * @param properties implementation specific properties. * These are configured as comma-separated name value pairs in ehcache.xml. * Properties may be null. * @return a constructed CacheManagerEventListener */ public abstract CacheManagerEventListener createCacheManagerEventListener(Properties properties); }
ファクトリは、以下に示すとおり、CacheManagerEventListener の具象クラスを作成します。
/** * Allows implementers to register callback methods that will be executed when a * CacheManager event occurs. * The events include: * * adding a Cache * removing a Cache * * * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of * the implementer to safely handle the potential performance and thread safety issues * depending on what their listener is doing. */ public interface CacheManagerEventListener { /** * Called immediately after a cache has been added and activated. * * Note that the CacheManager calls this method from a synchronized method. Any attempt to * call a synchronized method on CacheManager from this method will cause a deadlock.
195
* * Note that activation will also cause a CacheEventListener status change notification * from {@link net.sf.ehcache.Status#STATUS_UNINITIALISED} to * {@link net.sf.ehcache.Status#STATUS_ALIVE}. Care should be taken on processing that * notification because: * <ul> * <li>the cache will not yet be accessible from the CacheManager. * <li>the addCaches methods whih cause this notification are synchronized on the * CacheManager. An attempt to call {@link net.sf.ehcache.CacheManager#getCache(String)} * will cause a deadlock. * </ul> * The calling method will block until this method returns. * * @param cacheName the name of the Cache the operation relates to * @see CacheEventListener */ void notifyCacheAdded(String cacheName); /** * Called immediately after a cache has been disposed and removed. The calling method will * block until this method returns. * * Note that the CacheManager calls this method from a synchronized method. Any attempt to * call a synchronized method on CacheManager from this method will cause a deadlock. * * Note that a {@link CacheEventListener} status changed will also be triggered. Any * attempt from that notification to access CacheManager will also result in a deadlock. * @param cacheName the name of the Cache the operation relates to */ void notifyCacheRemoved(String cacheName); }
この実装は、Ehcache にアクセスできるクラスパスに配置してください。Ehcache は
Thread.currentThread().getContextClassLoader()が返した ClassLoader を使用してクラスをロードし
ます。
29.2 Cacheのイベントリスナー
BigMemory Max の Ehcache には、Cache のイベントリスナーも実装されています。Cache リスナー
を利用することで、CacheManager のイベントが発生したときにコールバックされるメソッドの実
196
装も利用できるようになります。Cache クラスのリスナーは CacheEventListener インターフェース
を実装します。イベントには以下のようなものがあります。
• Element の登録。
• Element の更新。ここでいう「更新」とは、Cache 内に存在する Element と同一のキーを持つ
Element を登録する動作を指します。
• Element の削除。
• Element の有効期限切れ。timeToLive または timeToIdle に達した場合を指します。
コールバック方法には、同期型と非同期型の両方があります。実装する際は、リスナーが実行して
いる処理に配慮し、スレッドセーフとパフォーマンスを損なわないように注意が必要です。各イベ
ントは、発生した順番どおりにリスナーへ通知されることが保証されています。リスナーへ通知せ
ずにキャッシュの登録や削除を行いたい場合は、putQuiet メソッドまたは removeQuiet メソッドを
使用します。
29.2.1 構成 キャッシュイベントリスナーの構成情報は、各キャッシュごとに設定されます。各キャッシュには
複数のリスナーを実装できます。キャッシュの各イベントリスナーの構成を設定するには、以下に
示す cacheEventListenerFactory 要素を追加します。
<cache ...> <cacheEventListenerFactory class="" properties="" listenFor=""/> ... </cache>
このエントリーでは、ファクトリ CacheEventListenerFactory を指定します。このファクトリで作
成した CacheEventListener が、イベントの通知を受信します。CacheEventListenerFactory の属性は
以下のとおりです。
• class：ファクトリクラスの完全修飾名です。
• properties：ファクトリが使用するプロパティをカンマで区切って指定します。省略可能です。
• listenFor：クラスター環境で受信するイベントの種類を定義します（デフォルト値は"all"です）。
指定できる値は次のとおりです。
– "all"：すべてのローカルイベントとリモートイベントを受信します。デフォルト値です。
– "local"：現在のノードで発生したイベントだけを受信します。
– "remote"：他のノードで発生したイベントだけを受信します（BigMemory Max 専用）。
197
リスナーメソッドのコールバック方法には、同期型と非同期型の両方があります。実装する際は、
リスナーが実行している処理に配慮し、スレッドセーフとパフォーマンスを損なわないように注意
が必要です。
29.2.2 Cacheのイベントリスナーファクトリとイベントリスナーの実装 CacheEventListenerFactory は、Cache のイベントリスナーを作成するための抽象ファクトリです。
この抽象ファクトリを継承して、独自の具象ファクトリを実装してください。実装した具象ファク
トリの構成情報は ehcache.xml で設定します。抽象 CacheEventListenerFactory の作成の例を以下に
示します。
/** * An abstract factory for creating listeners. Implementers should provide their own * concrete factory extending this factory. It can then be configured in ehcache.xml * */ public abstract class CacheEventListenerFactory { /** * Create a CacheEventListener * * @param properties implementation specific properties. These are configured as comma * separated name value pairs in ehcache.xml * @return a constructed CacheEventListener */ public abstract CacheEventListener createCacheEventListener(Properties properties); }
CacheEventListener インターフェースの具象クラス作成の例を以下に示します。
/** * Allows implementers to register callback methods that will be executed when a cache event * occurs. * The events include: * <ol> * <li>put Element * <li>update Element * <li>remove Element * <li>an Element expires, either because timeToLive or timeToIdle has been reached. * </ol> * * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of * the implementer to safely handle the potential performance and thread safety issues
198
* depending on what their listener is doing. * * Events are guaranteed to be notified in the order in which they occurred. * * Cache also has putQuiet and removeQuiet methods which do not notify listeners. * */ public interface CacheEventListener extends Cloneable { /** * Called immediately after an element has been removed. The remove method will block until * this method returns. * * Ehcache does not check for * * As the {@link net.sf.ehcache.Element} has been removed, only what was the key of the * element is known. * * * @param cache the cache emitting the notification * @param element just deleted */ void notifyElementRemoved(final Ehcache cache, final Element element) throws CacheException; /** * Called immediately after an element has been put into the cache. The * {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method * will block until this method returns. * * Implementers may wish to have access to the Element's fields, including value, so the * element is provided. Implementers should be careful not to modify the element. The * effect of any modifications is undefined. * * @param cache the cache emitting the notification * @param element the element which was just put into the cache. */ void notifyElementPut(final Ehcache cache, final Element element) throws CacheException; /** * Called immediately after an element has been put into the cache and the element already * existed in the cache. This is thus an update. *
199
* The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method * will block until this method returns. * * Implementers may wish to have access to the Element's fields, including value, so the * element is provided. Implementers should be careful not to modify the element. The * effect of any modifications is undefined. * * @param cache the cache emitting the notification * @param element the element which was just put into the cache. */ void notifyElementUpdated(final Ehcache cache, final Element element) throws CacheException; /** * Called immediately after an element is found to be expired. The * {@link net.sf.ehcache.Cache#remove(Object)} method will block until this method returns. * * As the {@link Element} has been expired, only what was the key of the element is known. * * Elements are checked for expiry in Ehcache at the following times: * <ul> * <li>When a get request is made * <li>When an element is spooled to the diskStore in accordance with a MemoryStore * eviction policy * <li>In the DiskStore when the expiry thread runs, which by default is * {@link net.sf.ehcache.Cache#DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS} * </ul> * If an element is found to be expired, it is deleted and this method is notified. * * @param cache the cache emitting the notification * @param element the element that has just expired * * Deadlock Warning: expiry will often come from the DiskStore * expiry thread. It holds a lock to the DiskStore at the time the * notification is sent. If the implementation of this method calls into a * synchronized Cache method and that subsequently calls into * DiskStore a deadlock will result. Accordingly implementers of this method * should not call back into Cache. */ void notifyElementExpired(final Ehcache cache, final Element element); /**
200
* Give the replicator a chance to cleanup and free resources when no longer needed */ void dispose(); /** * Creates a clone of this listener. This method will only be called by Ehcache before a * cache is initialized. * * This may not be possible for listeners after they have been initialized. Implementations * should throw CloneNotSupportedException if they do not support clone. * @return a clone * @throws CloneNotSupportedException if the listener could not be cloned. */ public Object clone() throws CloneNotSupportedException; }
ほかにも 2 つのメソッドが提供されています。
• void notifyElementEvicted(Ehcache cache, Element element)
エビクションによってキャッシュの Element を破棄した直後に呼び出されます。キャッシュの
ストアから要素を除去する処理には、エビクションによる破棄と、
Cache.removeElement(Element)による削除があります。両者を混同しないよう注意してくださ
い。
• void notifyRemoveAll(Ehcache cache)
Ehcache.removeAll()の処理中に呼び出されます。すべてのエレメントがキャッシュから一括削
除されたことを通知します。通常の削除時に利用される
notifyElementRemoved(net.sf.ehcache.Ehcache, net.sf.ehcache.Element)は呼び出されません。パ
フォーマンス低下を避けるため、個々のキャッシュの削除は通知しません。一括削除で個々の
キャッシュの通知を行うと、数百万もの通知処理が発生する可能性があるからです。
この実装は、Ehcache にアクセスできるクラスパスに配置してください。これらのクラスがロード
される仕組みの詳細は「クラスロードとクラスローダ」のページを参照してください。
29.2.3 プログラムによるリスナーの追加 プログラムによってリスナーを追加する方法は、以下のサンプルを参考にしてください。
cache.getCacheEventNotificationService().registerListener(myListener);
201
29.2.4 例：複数のイベントリスナーを別々のノードで実行する あるノードのリスナーB が他のノードのリスナーA のアクションによって発生したイベントを待ち
受けている場合、リスナーA がアクションを別のスレッドで行なわないかぎり、そのイベントを受
信することはできません。
例えば、リスナーA がキャッシュ A への書き込みを検出し、キャッシュ B に要素を書き込んだ場合、
（正しくキャッシュ B に登録されていれば）リスナーB がイベントを受信することになります。た
だし、次のコードを使うと、リスナーB は書き込みによって発生したイベントを受信できなくなり
ます。
// This method is within listener A public void notifyElementPut(...) { ... ... cache.put(...); ... ... }
次のコードを使うと、リスナーB はイベントを受信できるようになります。
// This method is within listener A public void notifyElementPut(...) { executorService.execute(new Runnable() { public void run() { ... ... cache.put(...); ... ... } ... ... } ...
202
30 Cache Exceptionハンドラー
30.1 はじめに
BigMemory Max の Ehcache には、Cache Exception ハンドラーが実装されています。ほとんどのキ
ャッシュオペレーションは、例外発生時にデフォルトで CacheException をスローします。動的プ
ロキシを設定すれば、この例外を CacheExceptionHandler がキャッチできるようになります。エラ
ーはキャッチされません。
Ehcache 型のキャッシュは、ExceptionHandling の構成が設定されています。例外処理を行うには、
Decorator で拡張されていない基底キャッシュを返す CacheManager.getCache()ではなく、
CacheManager.getEhcache()から参照できるようにしておく必要があります。
CacheExceptionHandlers の定義方法には、ehcache.xml で構成情報を指定する方法と、プログラム
から指定する方法があります。
30.2 構成情報を利用する定義
キャッシュイベントリスナーの構成情報は、各キャッシュごとに設定されます。例外ハンドラーは、
各キャッシュに対して 1 つだけ登録できます。例外ハンドラーの構成情報を定義するには
cacheExceptionHandlerFactory 要素を使用します。記述のサンプルを以下に示します。
<cache ...> <cacheExceptionHandlerFactory class="net.sf.ehcache.exceptionhandler.CountingExceptionHandlerFactory" properties="logLevel=FINE"/> </cache>
30.3 Cache ExceptionハンドラーFactoryとCache Exception Handlerの実装方法
CacheExceptionHandlerFactory は、Cache Exception ハンドラーを作成するための抽象ファクトリで
す。この抽象ファクトリを継承して、独自の具象ファクトリを実装してください。実装した具象フ
ァクトリの構成情報は ehcache.xml で設定します。ファクトリクラスは、以下に示すとおり、抽象
ファクトリ CacheExceptionHandlerFactory の具象サブクラスである必要があります。
/** * An abstract factory for creating <code>CacheExceptionHandler</code>s at configuration * time, in ehcache.xml. * <p/> * Extend to create a concrete factory *
203
*/ public abstract class CacheExceptionHandlerFactory { /** * Create an <code>CacheExceptionHandler</code> * * @param properties implementation specific properties. These are configured as comma * separated name value pairs in ehcache.xml * @return a constructed CacheExceptionHandler */ public abstract CacheExceptionHandler createExceptionHandler(Properties properties); }
ファクトリは、以下に示すとおり、CacheExceptionHandler インターフェースの具象クラスを作成
します。
/** * A handler which may be registered with an Ehcache, to handle exception on Cache operations. * * Handlers may be registered at configuration time in ehcache.xml, using a * CacheExceptionHandlerFactory, or * set at runtime (a strategy). * * If an exception handler is registered, the default behaviour of throwing the exception * will not occur. The handler * method on Exception will be called. Of course, if * the handler decides to throw the exception, it will * propagate up through the call stack. * If the handler does not, it won't. * * Some common Exceptions thrown, and which therefore should be considered when implementing * this class are listed below: * <ul> * <li>{@link IllegalStateException} if the cache is not * {@link net.sf.ehcache.Status#STATUS_ALIVE} * <li>{@link IllegalArgumentException} if an attempt is made to put a null * element into a cache * <li>{@link net.sf.ehcache.distribution.RemoteCacheException} if an issue occurs * in remote synchronous replication * <li> * <li> * </ul> * */
204
public interface CacheExceptionHandler { /** * Called if an Exception occurs in a Cache method. This method is not called * if an Error occurs. * * @param Ehcache the cache in which the Exception occurred * @param key the key used in the operation, or null if the operation does not use a * key or the key was null * @param exception the exception caught */ void onException(Ehcache ehcache, Object key, Exception exception); }
この実装は、Ehcache にアクセスできるクラスパスに配置してください。これらのクラスがロード
される仕組みの詳細は「クラスロードとクラスローダ」を参照してください。
30.4 プログラムによる構成設定
すべてのクライアントがキャッシュの Decorator 拡張を使用できるようにするには、キャッシュに
例外ハンドラーを追加したあと、そのキャッシュをキャッシュマネージャーに追加する必要があり
ます。その方法の例を以下に示します。
CacheManager cacheManager = ... Ehcache cache = cacheManger.getCache("exampleCache"); ExceptionHandler handler = new ExampleExceptionHandler(...); cache.setCacheLoader(handler); Ehcache proxiedCache = ExceptionHandlingDynamicCacheProxy.createProxy(cache); cacheManager.replaceCacheWithDecoratedCache(cache, proxiedCache);
31 キャッシュ拡張
31.1 はじめに
BigMemory Max の Ehcache には、キャッシュ拡張が実装されています。キャッシュ拡張は、Cacheに拡張機能を加える汎用の仕組みです。キャッシュ拡張は Cache のライフサイクルに組み込まれて
います。このため、このインターフェースはライフサイクルを扱うメソッドも提供します。
キャッシュ拡張は CacheExtensionFactory を使用して作成します。このクラスの
createCacheCacheExtension()>メソッドに、Cache とプロパティを指定します。その後、load メソッ
ドを含むすべての public な Cache のメソッドからコールバックできます。キャッシュ拡張は、キャ
ッシュオペレーションを実行するタイマーを作成するためのサービスで利用すると便利です。（ほ
205
かに、Decorator を使用してキャッシュを拡張する方法があります。使用方法とサンプルは
「Blocking Cache」を参照してください。）
CacheExtension は Cache への参照を記録しています。このため CacheExtension は、
CacheEventListener や CacheManagerEventListener の登録ができます。これらはすべて
CacheExtension 内で実行するため、簡単にカスタマイズできます。
31.2 構成情報を利用する定義
キャッシュ拡張の構成情報は、各キャッシュごとに設定されます。各キャッシュにはゼロまたはそ
れ以上が入ります。以下に、cacheExceptionHandlerFactory 要素を追加することで CacheExtensionの構成を設定する例を以下に示します。
<cache ...> <cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory" properties="refreshIntervalMillis=18000, loaderTimeout=3000, flushPeriod=whatever, someOtherProperty=someValue ..."/> </cache>
31.3 Cache ExtensionファクトリとCache Extensionの実装
CacheExtensionFactory は、キャッシュ拡張を作成するための抽象ファクトリです。この抽象ファ
クトリを継承して、独自の具象ファクトリを実装してください。実装した具象ファクトリの構成情
報は ehcache.xml で設定します。ファクトリクラスは、以下に示すとおり、抽象ファクトリ
CacheExtensionFactory の具象サブクラスである必要があります。
/** * An abstract factory for creating CacheExtensions. Implementers should * provide their own * concrete factory extending this factory. It can then be configured * in ehcache.xml. * */ public abstract class CacheExtensionFactory { /** * @param cache the cache this extension should hold a reference to, and to whose * lifecycle it should be bound. * @param properties implementation specific properties configured as delimiter separated * name value pairs in ehcache.xml */ public abstract CacheExtension createCacheExtension(Ehcache cache, Properties properties); }
206
ファクトリは、以下に示すとおり、CacheExtension インターフェースの具象クラスを作成します。
/** * This is a general purpose mechanism to allow generic extensions to a Cache. * * CacheExtensions are tied into the Cache lifecycle. For that reason this interface has the * lifecycle methods. * * CacheExtensions are created using the CacheExtensionFactory which has a * createCacheCacheExtension() method which takes as a parameter a Cache and * properties. It can thus call back into any public method on Cache, including, of course, * the load methods. * * CacheExtensions are suitable for timing services, where you want to create a timer to * perform cache operations. The other way of adding Cache behaviour is to decorate a cache. * See {@link net.sf.ehcache.constructs.blocking.BlockingCache} for an example of how to do * this. * * Because a CacheExtension holds a reference to a Cache, the CacheExtension can do things * such as registering a CacheEventListener or even a CacheManagerEventListener, all from * within a CacheExtension, creating more opportunities for customisation. * */ public interface CacheExtension { /** * Notifies providers to initialise themselves. * * This method is called during the Cache's initialise method after it has changed it's * status to alive. Cache operations are legal in this method. * * @throws CacheException */ void init(); /** * Providers may be doing all sorts of exotic things and need to be able to clean up on * dispose. * * Cache operations are illegal when this method is called. The cache itself is partly * disposed when this method is called. *
207
* @throws CacheException */ void dispose() throws CacheException; /** * Creates a clone of this extension. This method will only be called by Ehcache before a * cache is initialized. * * Implementations should throw CloneNotSupportedException if they do not support clone * but that will stop them from being used with defaultCache. * * @return a clone * @throws CloneNotSupportedException if the extension could not be cloned. */ public CacheExtension clone(Ehcache cache) throws CloneNotSupportedException; /** * @return the status of the extension */ public Status getStatus(); }
この実装は、Ehcache にアクセスできるクラスパスに配置してください。これらのクラスがロード
される仕組みの詳細は「クラスロードとクラスローダ」を参照してください。
31.4 プログラムによる構成設定
プログラムを使って Cache にキャッシュ拡張を追加する方法は以下のとおりです。
TestCacheExtension testCacheExtension = new TestCacheExtension(cache, ...); testCacheExtension.init(); cache.registerCacheExtension(testCacheExtension);
32 キャッシュエビクションアルゴリズム
32.1 はじめに
キャッシュのエビクションアルゴリズムとは、キャッシュが一杯になったとき、どの要素をキャッ
シュから破棄するのかを決定するアルゴリズムです。BigMemory Max の Ehcache では、メモリス
トアとオフヒープストアのサイズに制限があります。（サイズの情報は「ストレージ層のサイズ指
定」を参照してください。）これらの領域が一杯になった場合は、キャッシュ内の要素をエビクシ
208
ョンによって破棄します。Ehcache のエビクションアルゴリズムは、破棄すべき要素を決定します。
デフォルト値は LRU です。
エビクションの影響は、キャッシュの構成によって異なります。ディスクストアの場合、破棄され
た要素はディスクにフラッシュされます。それ以外の場合は単に削除されます。デフォルトのディ
スクストアのサイズは無制限です。しかし、制限値を設定することも可能です（詳細は、ストレー
ジ層のサイズ指定の、「属性によるサイズ指定」を参照してください）。サイズに制限のあるディ
スクストアが一杯になった場合、1 つの要素を追加するには 1 つの要素を破棄する必要があります。
ディスクストアのエビクションアルゴリズムには、設定の必要な構成情報がありません。ディスク
ストアは常に LFU を使用します。
32.2 メモリストア用に提供されているエビクションアルゴリズム
基本的な考え方は、キャッシュの項目数に限りがあるとき、どの項目を破棄したら最善の結果が得
られるのか、ということです。
1966 年に Laszlo Belady は、最も効果的なキャッシュアルゴリズムは、将来最も長く利用されない
情報を破棄することだという考え方を示しました。しかしこれは、論理的な結論に過ぎません。そ
の業務領域の知識がなければ実装は不可能です。この代替案として、最もよく利用されるのが
Least Recently Used（LRU）アルゴリズムです。参照という事象の特性からも、このアルゴリズム
は非常に効果的であるため、多くのキャッシュがデフォルトとして採用しています。
Ehcache でも、この LRU の一種をデフォルトのエビクションアルゴリズムとして採用しています。
Ehcache は、メモリストアに対して合計 3 種類のエビクションアルゴリズムを提供しています。
32.2.1 Least Recently Used (LRU) Least Frequently Used の一種で、デフォルト値に設定されています。
最も古い Element が、最も使用されていない（LRU）要素です。Element がキャッシュに登録され
たとき、あるいは get の呼び出しによるキャッシュの取得が発生したとき、タイムスタンプが更新
されます。
このアルゴリズムでは、Element のランダムサンプルを抽出し、タイムスタンプが最も古いものを
破棄します。15 の Element をサンプルとして使用すると、下位 4 分の 1 に該当する Element を99%の確率で破棄できることが、これまでのテストで判明しています。
このような確率に頼るエビクションアルゴリズムがアプリケーションに合わない場合もあります。
そのようなときは、次のパラメーターを設定することで、本当に最もタイムスタンプの古い
Element が破棄されるようになります：java -Dnet.sf.ehcache.use.classic.lru=true
209
32.2.2 Least Frequently Used (LFU) get 呼び出しのたびに、該当する Element のヒット回数が更新されます。put 呼び出しによって新
しい Element をキャッシュに記録する場合（かつ、キャッシュサイズの上限に達している場合）、
最もヒット回数の小さい（Least Frequently Used）Element が破棄されます。
キャッシュ利用がパレート分布の場合、このアルゴリズムのほうが LRU よりも効率的です。
LFU は Ehcache 独自のアルゴリズムです。このアルゴリズムでは、Element のランダムサンプルを
抽出し、ヒット回数が最も小さいものを破棄します。15 の Element をサンプルとして使用すると、
下位 4 分の 1 に該当する Element を 99%の確率で破棄できることが、これまでのテストで判明し
ています。
32.2.3 First In First Out (FIFO) キャッシュ内の Element を、登録時間の古いものから順番に破棄します。put 呼び出しによって新
しい Element をキャッシュに記録する場合（かつ、キャッシュサイズの上限に達している場合）、
最も早く（First-In）ストアに登録されていた Element が、エビクションの対象（First-Out）になり
ます。
このアルゴリズムは、一度使用した Element が将来ほとんど利用される可能性がないときに使用し
ます。例えば認証に使用するキャッシュなどが該当します。
32.3 独自のエビクションアルゴリズムをプラグインとして使用
BigMemory Max では、独自のエビクションアルゴリズムをプラグインとして組み込むことが可能で
す。Element の任意のメタデータを利用することで、さまざまなアプローチが可能です。例えば、
10 回ヒットした時点で Element を破棄するような設定ができます。
/** * Sets the eviction policy strategy. The Cache will use a policy at startup. * There are three policies which can be configured: LRU, LFU and FIFO. However * many other policies are possible. That the policy has access to the whole element * enables policies based on the key, value, metadata, statistics, or a combination * of any of the above. * * It is safe to change the policy of a store at any time. The new policy takes * effect immediately. * * @param policy the new policy */ public void setMemoryStoreEvictionPolicy(Policy policy) { memoryStore.setEvictionPolicy(policy); }
210
ポリシーには、以下のインターフェースの実装が必要です。
public interface Policy { /** * @return the name of the Policy. Inbuilt examples are LRU, LFU and FIFO. */ String getName(); /** * Finds the best eviction candidate based on the sampled elements. What * distinguishes this approach from the classic data structures approach is * that an Element contains metadata (e.g. usage statistics) which can be used * for making policy decisions, while generic data structures do not. It is * expected that implementations will take advantage of that metadata. * * @param sampledElements this should be a random subset of the population * @param justAdded we probably never want to select the element just added. * It is provided so that it can be ignored if selected. May be null. * @return the selected Element */ Element selectedBasedOnPolicy(Element[] sampledElements, Element justAdded); /** * Compares the desirableness for eviction of two elements * * @param element1 the element to compare against * @param element2 the element to compare * @return true if the second element is preferable for eviction to the first * element under ths policy */ boolean compare(Element element1, Element element2); }
32.4 ディスクストアのエビクションアルゴリズム
ディスクストアの要素が一杯になった場合は LFU（Least Frequently Used）アルゴリズムを使用し
ます。
211
33 クラスロードとクラスローダ
33.1 はじめに
Ehcache はさまざまな環境で動作します。このため、クラスのロードの仕組みも複雑です。しかし
BigMemory Max は、ユーティリティクラス ClassLoaderUtil を利用する標準的なクラスのロード方
法を提供します。
33.2 クラスロードのプラグイン
Ehcache のイベントや分散ではプラグインを使用できます。プラグインの作成およびロードは次の
とおりです。
/** * Creates a new class instance. Logs errors along the way. Classes are loaded * using the Ehcache standard classloader. * * @param className a fully qualified class name * @return null if the instance cannot be loaded */ public static Object createNewInstance(String className) throws CacheException { Class clazz; Object newInstance; try { clazz = Class.forName(className, true, getStandardClassLoader()); } catch (ClassNotFoundException e) { //try fallback try { clazz = Class.forName(className, true, getFallbackClassLoader()); } catch (ClassNotFoundException ex) { throw new CacheException("Unable to load class " + className + ". Initial cause was " + e.getMessage(), e); } } try { newInstance = clazz.newInstance(); } catch (IllegalAccessException e) { throw new CacheException("Unable to load class " + className + ". Initial cause was " + e.getMessage(), e);
212
} catch (InstantiationException e) { throw new CacheException("Unable to load class " + className + ". Initial cause was " + e.getMessage(), e); } return newInstance; } /** * Gets the ClassLoader that all classes in ehcache, and extensions, * should use for classloading. All ClassLoading in Ehcache should use this one. * This is the only thing that seems to work for all of the class loading * situations found in the wild. * @return the thread context class loader. */ public static ClassLoader getStandardClassLoader() { return Thread.currentThread().getContextClassLoader(); } /** * Gets a fallback ClassLoader that all classes in ehcache, and * extensions, should use for classloading. This is used if the context class loader * does not work. * @return the ClassLoaderUtil.class.getClassLoader(); */ public static ClassLoader getFallbackClassLoader() { return ClassLoaderUtil.class.getClassLoader(); }
以上のコードは、何らかの理由で動作しなかった場合に CacheException をスローします。この例
外は詳細なエラーメッセージを含んでいます。
33.3 ehcache.xmlリソースのロード
Ehcache の構成情報を指定しなかった場合、Ehcache は以下の順番で構成情報を検索します。
• Thread.currentThread().getContextClassLoader().getResource("/ehcache.xml")
• ConfigurationFactory.class.getResource("/ehcache.xml")
• ConfigurationFactory.class.getResource("/ehcache-failsafe.xml")
213
Ehcache は最初に見つかった構成情報を使用します。「/ehcache.xml」は、必ずクラスパスのルー
トに保存してください。パッケージの中に含めることはできません。
34 Developing Applications With the Terracotta Toolkit
34.1 Introduction The Terracotta Toolkit is intended for developers working on scalable applications, frameworks, and software tools. The Terracotta Toolkit provides the following features:
• Ease-of-use – A stable API, fully documented classes (see the 「Terracotta Toolkit Javadoc」), and a versioning scheme that's easy to understand.
• Guaranteed compatibility – Verified by a Terracotta Compliance Kit that tests all classes to ensure backward compatibility.
• Extensibility – Includes all of the tools used to create Terracotta products, such as concurrent maps, locks, counters, queues.
• Flexibility – Can be used to build clustered products that communicate with multiple clusters.
• Platform independence – Runs on any Java 1.6 or 1.7 JVM and requires no boot-jars, agents, or container-specific code.
The Terracotta Toolkit 2.x is available with Terracotta kits version 4.0.0 and higher.
34.2 Installing the Terracotta Toolkit The Terracotta Toolkit is contained in the following JAR file:
${BIGMEMORY_HOME}/apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar
The Terracotta Toolkit JAR file should be on your application's classpath or in WEB-INF/lib if using a WAR file.
Maven users can add the Terracotta Toolkit as a dependency (shown for BigMemory Max 4.0.0):
<dependency> <groupId>org.terracotta</groupId> <artifactId>terracotta-toolkit-runtime-ee</artifactId> <version>4.0.0</version> </dependency>
See the Terracotta kit version you plan to use for the correct API and JAR versions to specify in the dependency block.
The repository is given by the following:
214
<repository> <id>terracotta-repository</id> <url>http://www.terracotta.org/download/reflector/releases</url> <releases> <enabled>true</enabled> </releases> </repository>
34.3 Understanding Versions The products you create with the Terracotta Toolkit depend on the API at its heart. The Toolkit's API has a version number with a major digit and a minor digit that indicate its compatibility with other versions. The major version number indicates a breaking change, while the minor version number indicates a compatible change. For example, Terracotta Toolkit API version 1.1 is compatible with version 1.0. Version 1.2 is compatible with both versions 1.1 and 1.0. Version 2.0 is not compatible with any version 1.x, but will be forward compatible with any version 2.x.
35 Working With the Terracotta Toolkit
35.1 Introduction The Terracotta Toolkit provides access to a number of useful classes, or tools, such as distributed collections. All provided Toolkit types are automatically distributed and all changes (except as noted below) are shared across all nodes by the Terracotta Server Array. This gives all nodes the same view of state.
While the Toolkit types differ in their usage and functionality based on characteristics inherited from their parent types, there are 「certain shared features」.
This document provides information on getting started using the Terracotta Toolkit. For more detailed information on Toolkit types, see the Terracotta Toolkit Javadoc.
35.2 Initializing the Toolkit To access the tools in the Toolkit, your application must first initialize the Terracotta Toolkit. Initializing the Terracotta Toolkit always begins with starting a Terracotta client:
... // These classes must be imported: import org.terracotta.toolkit.*; ... // A configuration source must be specified in the argument. // In this case the source is a server and its configured port.
215
Toolkit toolkit = ToolkitFactory.createToolkit("toolkit:terracotta://localhost:9510"); ...
When a Terracotta client is started, it must load a Terracotta configuration. Programmatically, createToolkit() takes as argument the source for the client's configuration. In the example above, the configuration source is a Terracotta server running on the local host, with port set to 9510. In general, a filename, an URL, or a resolvable hostname or IP address and port number can be used. The specified server instance must be running and accessible before the code that starts the client executes.
The data structures and other tools provided by the Toolkit are automatically distributed (clustered) when your application is run in a Terracotta cluster. Since the Toolkit is obtained from an instantiated client, all Toolkit tools must be used clustered. Unclustered use is not supported in this version.
35.2.1 Adding Rejoin Behavior Clients can be initialized with the ability to 「rejoin」 the cluster after being ejected. Clients rejoin as new clients.
Clients are initialized with rejoin using a Properties object:
Properties properties = new Properties(); properties.put("rejoin","true"); Toolkit toolkit = ToolkitFactory .createToolkit("toolkit:terracotta://localhost:9510", properties);
35.3 Toolkit Data Structures All data structures must have serializable keys and values. In addition, data structures may have other requirements on keys as noted.
35.3.1 ToolkitStore The ToolkitStore is a key-value data store that is automatically distributed in a Terracotta cluster. The ToolkitStore is used similarly to the ToolkitCache except that it lacks eviction. It is limited to keys of type String.
To create a ToolkitStore, use the following:
// Enforce type checking -- can store only Value.class. ToolkitStore<Value> store1 = toolkit.getStore("myStore1", Value.class); // Do not enforce type checking -- any type of value can be stored. ToolkitStore store2 = toolkit.getStore("myStore2", null); // Use the provided configuration instead of default configuration. ToolkitStore<Value> store3 = toolkit.getStore("myStore3", configuration, Value.class);
216
Store Configuration
Configuration properties available for the toolkit are shown in the following table.
Property
Default Value
Definition
Edit Dynamically?
CONSISTENCY
EVENTUAL
EVENTUAL sets no cache-level locks for better performance and allows reads without locks, which means the cache may temporarily return stale data in exchange for substantially improved performance. STRONG uses cache-level locks for immediate cache consistency at a potentially high cost to performance, guaranteeing that after any update is completed no local read can return a stale value. If using strong consistency with off-heap, a large number of locks may need to be stored in client and server heaps. In this case, be sure to test the cluster with the expected data set to detect situations where OutOfMemory errors are likely to occur. SYNCHRONOUSSTRONG adds synch-write locks to STRONG consistency, which otherwise uses asynchronous writes. SYNCHRONOUSSTRONG provides extreme data safety at a very high performance cost by requiring that a client receive server acknowledgement of a transaction before that client can proceed.
No
CONCURRENCY
256
Sets the number of segments for the map backing the underlying server store managed by the Terracotta Server Array. If concurrency is not explicitly set (or set to "0"), the system selects an optimized value.
No
MAXCOUNTLOCAL_HEAP
0 (no limit)
The maximum number of data entries that the store can have in local heap memory.
Yes (locally)
217
MAXBYTESLOCAL_HEAP
0 (no limit)
The maximum amount of data in bytes that the store can have in local heap memory.
Yes (locally)
MAXBYTESLOCALOFFHEAP
0 (no limit)
The maximum amount of data in bytes that the store can have in local off-heap memory.
No
OFFHEAPENABLED
false
Enables ("true") or disables ("false") the store's use of off-heap memory.
No
LOCALCACHEENABLED
true
Enables ("true") or disables ("false") local caching of distributed store data, forcing all of that cached data to reside on the Terracotta Server Array. Disabling local caching may improve performance for distributed stores in write-heavy use cases.
Yes (locally)
Stores created without explicit configuration are provided a default configuration. To customize configuration, either pass configuration to ToolkitStore or edit the store's configuration.
You can also create a default store configuration with ToolkitCacheConfigBuilder():
Configuration initiallyDefaultConfig = new ToolkitStoreConfigBuilder().build();
This configuration can be passed to a store and further edited. Store configuration is governed by the same rules as cache configuration. To learn more about how to configure a store and edit its configuration, see the 「cache configuration section」, remembering to substitute the "store" types and methods.
218
35.3.2 ToolkitCache The ToolkitCache is a fully featured cache that is automatically distributed in a Terracotta cluster. It has configurable eviction and also inherits all of the functionality of the 「Toolkit store」. It is limited to keys of type String.
To create a ToolkitCache, use the following:
// Enforce type checking -- can store only Value.class. ToolkitCache<Value> cache1 = toolkit.getCache("myCache1", Value.class); // Do not enforce type checking -- any type of value can be stored. ToolkitCache cache2 = toolkit.getCache("myCache2", null); // Use the provided configuration instead of default configuration. ToolkitCache<Value> cache3 = toolkit.getCache("myCache3", configuration, Value.class); // You can also create a default cache configuration with ToolkitCacheConfigBuilder(): Configuration initiallyDefaultConfig = new ToolkitCacheConfigBuilder().build();
This configuration can be passed to a cache and further edited based on 「certain rules」.
Configuring ToolkitCache
Caches created without explicit configuration are provided a default configuration. To customize configuration, either pass configuration to ToolkitCache or 「edit the cache's configuration」.
In addition to the configuration properties inherited from ToolkitStore, the following configuration properties are available to the ToolkitCache:
Property Default Value Definition
Edit Dynamically
MAXTTISECONDS 0 The time-to-idle setting for all cache entries. Default (0) is unlimited.
Yes (cluster-wide)
MAXTTLSECONDS 0 The time-to-live setting for all cache entries. Default (0) is unlimited.
Yes (cluster-wide)
MAXTOTALCOUNT 0 The total number of entries allowed for the cache across all client nodes.
Yes (cluster-wide)
PINNING_STORE NONE Cache data is forced to remain in the designated storage tier, if any, and cannot be evicted. Valid values are INCACHE (any tier where the cache's data is located), LOCALHEAP, LOCALMEMORY (heap and off-heap), NONE. Issues due to lack of memory could arise with
No
219
pinned caches that grow in size.
To create a cache with a custom configuration use the following:
// Create the configuration with the fluent builder interface. Configuration configuration = new ToolkitCacheConfigBuilder() .maxBytesLocalHeap(2g) .offheapEnabled(true) .maxBytesLocalOffheap(10g) .maxTTLseconds(3600) .maxTTIseconds(600) .maxTotalCount(40000) .pinningStore(LOCALMEMORY) .build(); ToolkitCache<String> cache3 = toolkit.getCache("myCache3", configuration, String.class); // Create the configuration using a builder instance. ToolkitCacheConfigBuilder builder = new ToolkitCacheConfigBuilder(); builder.maxCountLocalHeap(10000); builder.offheapEnabled(true); builder.maxBytesLocalOffheap(10 * GIGABYTE); ToolkitCache cache4 = toolkit.getCache("myCache4", null); builder.apply(cache4);
To find the values of specific configuration properties, use the corresponding get methods. For example:
Long maxCountLocalHeap = builder.getMaxCountLocalHeap()
Editing Cache Configuration
Some configuration properties can be edited dynamically. For example:
// Change the time-to-live value for cache4. builder.maxTTLseconds(3000); builder.apply(cache4);
220
In the example above, builder reapplies its other configuration properties with the same values without effect. Applying configuration properties with values that match the cache's configuration values leaves those values unchanged.
To learn which configuration properties can be edited dynamically, see the 「table showing basic configuration」 and the 「table showing cache-specific configuration」.
Note that default configurations have MAXCOUNTLOCAL_HEAP in effect, and this cannot be edited:
// Create the configuration using a builder instance. ToolkitCacheConfigBuilder builder5 = new ToolkitCacheConfigBuilder(); builder.maxBytesLocalHeap(2g); builder.offheapEnabled(true); builder.maxBytesLocalOffheap(10 * GIGABYTE); // cache5 will have a default configuration. ToolkitCache cache5 = toolkit.getCache("myCache5", null); // The following will throw an IllegalStateException. builder5.apply(cache5);
35.3.3 Clustered Collections Clustered collections, all based on standard Java clustered collections, are found in the package org.terracotta.collections. Operations on these collections are locked.
ToolkitBlockingQueue
Since this is a bounded BlockingQueue, use ToolkitBlockingQeue.getCapacity() to return an integer representing the queue's maximum capacity (maximum number of entries), which is not changeable once the queue has been created. If no capacity is specified, the effective capacity is Integer.MAX_VALUE.
To create a ToolkitBlockingQueue, use the following:
// A blocking queue with no capacity restriction. Restricted to the type Value.class. ToolkitBlockingQueue<Value> queue1 = toolkit.getBlockingQueue("myBlockingQueue1", Value.class); // A blocking queue with no capacity or type restrictions. ToolkitBlockingQueue queue2 = toolkit.getBlockingQueue("myBlockingQueue2", null); // A blocking queue with specified capacity. Restricted to the type Value.class. ToolkitBlockingQueue queue3 = toolkit.getBlockingQueue("myBlockingQueue3", 1024, Value.class);
221
If the blocking queue specified by getBlockingQueue() exists, it is returned instead (no new blocking queue is created). Note that if queue3 exists and has a capacity value different than the one specified in getBlockingQueue(), an IllegalArgumentException is thrown.
ToolkitMap and ToolkitSortedMap
These types behave as expected. Note that ToolkitSortedMap values must allow ordering (implement Comparable).
To create a ToolkitMap, use the following:
// Enforce type checking -- can store only Value.class using keys of type Key.class. ToolkitMap<Key, Value> map = toolkit.getMap("myMap", Key.class, Value.class); // Do not enforce type checking -- any type of key-value can be stored. ToolkitMap<Key, Value> map = toolkit.getMap("myMap", null, null);
ToolkitSortedMap is created similarly.
ToolkitSet, ToolkitSortedSet, and ToolkitList
These types behave as expected, but note the following:
• ToolkitList does not allow null elements.
• SortedSet values must allow ordering (implement Comparable).
All are created similarly. To create a ToolkitSet, for example, use the following:
// Enforce type checking -- can store only Value.class. ToolkitSet<Value> set1 = toolkit.getSet("mySet1", Value.class); // Do not enforce type checking -- any type of value can be stored. ToolkitSet set2 = toolkit.getSet("mySet2", null);
35.4 Cluster Information and Messaging To implement messaging in a Terracotta cluster, you can use the built-in cluster events and custom messages with a clustered notifier.
35.4.1 Cluster Events You can access cluster information for monitoring the nodes in a Terracotta cluster, as well as obtaining specific information about those nodes.
For example, you can set up a cluster listener to receive events about the status of client nodes:
222
// Start a client and access cluster events and meta data such as topology // for the cluster that the client belongs to: ClusterInfo clusterInfo = toolkit.getClusterInfo(); // Register a cluster listener: clusterInfo.addClusterListener(new ClusterListener());
Custom Listener Classes
You can write your own listener classes that implement the event methods, and add or remove your own listeners:
MyClusterListener myClusterListener = new MyClusterListener(); clusterInfo.addClusterListener(new myClusterListener()); // To remove a listener: clusterInfo.removeClusterListener(myClusterListener);
Handling Cluster Events
To handle events, use onClusterEvent(), which is called whenever a ClusterEvent occurs. See the suggested approaches below.
Custom Implemented Methods
Implement methods to handle each type of event, then use them in a test for the event type.
public void onClusterEvent(ClusterEvent event) { if (event.getType() == NODE_LEFT) { handleNodeLeft(); } if (event.getType() == NODE_JOINED) { handleNodeJoined(); } if (event.getType() == OPERATIONS_DISABLED) { handleOperationsDisabled(); } if (event.getType() == OPERATIONS_ENABLED) {
223
handleOperationsEnabled(); } }
Switch Case
Implement a switch-case block to handle each element type.
public void onClusterEvent(ClusterEvent event) { switch (event.getType()) { case NODE_JOINED: // Handle the fact that a node joined. break; case NODE_LEFT: // Handle node leaving. break; case OPERATIONS_ENABLED: // Handle operations disabled. break; case OPERATIONS_ENABLED: // Handle operations disabled. break; default: // handle other events generically } }
35.4.2 Toolkit Notifier ToolkitNotifier provides simple-to-use, clustered, and customizable messaging.
To create a ToolkitNotifier, use the following:
// Enforce type checking -- can send/receive only Value.class. ToolkitNotifier<Value> notifier1 = toolkit.getNotifier("my-notifier1", Value.class); // Do not enforce type checking -- any type of value can be sent/received. ToolkitNotifier notifier2 = toolkit.getNotifier("my-notifier2", null); // Add a notification listener. notifier1.addNotificiationListener(new MyToolkitNotificationListener());
224
The notification listener is a custom implementation of the ToolkitNotificationListener interface. Specifically, implement ToolkitNotificationListener.onNotification().
To send a message, use the following:
notifier1.notifyListeners(new Value());
Only remote listeners receive the message.
35.5 Locks Clustered locks allow you to perform safe operations on clustered data. The following types of locks are available:
• READ-WRITE – This provides an exclusive read lock and a shared read lock.
• WRITE – This is an exclusive write lock that blocks all reads and writes. To improve performance, this lock flushes changes to the Terracotta Server Array asynchronously.
To get and use clustered READ-WRITE locks, use the following:
ToolkitReadWriteLock rwLock = toolkit.getReadWriteLock("myReadWriteLock"); rwlock.readLock().lock(); // shared read lock try { // some read operation under the lock } finally { rwlock.readLock().unlock(); } rwlock.writeLock().lock(); // exclusive write lock try { // some write operation under the lock } finally { rwlock.writeLock().unlock(); }
To get and use an exclusive WRITE lock, use the following:
ToolkitLock wLock = toolkit.getLock("myWriteLock"); wLock.lock(); try { // some operation under the lock } finally { wLock.unlock(); }
225
If you are using BigMemory Max, you can use explicit locking methods on specific keys. See the BigMemory Max documentation for more information.
35.6 Barriers Coordinating independent nodes is useful in many aspects of development, from running more accurate performance and capacity tests to more effective management of workers across a cluster. A clustered barrier is a simple and effective way of coordinating client nodes.
To get a clustered barrier, use the following:
// Get a clustered barrier with 4 parties. ToolkitBarrier clusteredBarrier = toolkit.getBarrier("myBarrier", 4);
Note the following:
• getBarrier() as implemented in Terracotta Toolkit returns an object that behaves like CyclicBarrier but lacks barrierAction support.
• The number of parties must be an integer equal to or greater than 1.
• If getBarrier() returns an existing barrier, and the specified number of parties does not match that of the returned barrier, an IllegalArgumentException is thrown.
35.7 Utilities Utilities such as a clustered AtomicLong help track counts across a cluster. You can get (or create) a ToolkitAtomicLong using toolkit.getAtomicLong(String name).
An events utility, available with Toolkit.fireOperatorEvent(OperatorEventLevel level, String applicationName, String eventMessage), can be used to log specific application-related events.
35.8 Shared Characteristics Certain characteristics are shared by many of the Terracotta Toolkit types.
35.8.1 Nonstop Behavior for Data Structures The nonstop feature is enabled by specifying it at the time a toolkit is initialized:
Toolkit toolkit = ToolkitFactory.createToolkit("nonstop-toolkit:terracotta://localhost:9510");
Use the following if you are passing a properties object (to 「add rejoin behavior」 for example):
Toolkit toolkit = ToolkitFactory .createToolkit("nonstop-toolkit:terracotta://localhost:9510", properties);
Nonstop behavior allows the following limited functionality whenever a Terracotta client disconnects from the TSA:
226
• Throw exception for read and write operations
• Silently ignore read and write operations (no-op)
• Allow local reads
In addition, nonstop data structures running in a client that is unable to locate the TSA at startup will initiate nonstop behavior as if the client had disconnected.
Toolkit Types Supporting Nonstop
ToolkitCaches and ToolkitStores can be configured with the full range of nonstop behaviors. The following Toolkit types support only throwing a NonStopException: ToolkitAtomicLong, ToolkitList, ToolkitMap, ToolkitSortedMap, ToolkitLock, ToolkitReadWriteLock, ToolkitNotifier, ToolkitSet, ToolkitSortedSet. Other Toolkit types cannot be configured with nonstop.
Adding Nonstop Config to a Cache
You can add nonstop configuration to Toolkit caches.
// Get the cache: ToolkitCache<String> cache = toolkit.getCache(“myCache”, configuration, String.class); // Build the nonstop configuration: NonStopConfiguration nsconfig = new NonStopConfigurationBuilder() .nonStopReadTimeoutBehavior(LOCAL_READS) .timeOutMillis(90000) .build(); // Register the nonstop configuration with the cache: NonStopFeature nonStop = toolkit.getFeature(ToolkitFeatureType.NONSTOP); NonStopConfigurationRegistry registry = nonStop.getNonStopConfigurationRegistry(); registry.registerForInstance(nsconfig, myCache, ToolkitCache)
35.8.2 Disposing of Toolkit Objects Many types are destroyable and can be disposed of using destroy(). If the object is distributed, it is destroyed in all nodes if destroy() is called in one node. For example, ToolkitCache.destroy() disposes of the cache and its data in all nodes where it exists.
Calling destroy() on a nonexistent object has no effect (no-op). However, attempting to use a destroyed object throws an IllegalStateException.
227
The following Toolkit types are destroyable: ToolkitAtomicLong, ToolkitBarrier, ToolkitBlockingQueue, ToolkitCache, ToolkitList, ToolkitMap, ToolkitNotifier, ToolkitSet, ToolkitSortedMap, ToolkitSortedSet, ToolkitStore.
35.8.3 Finding the Assigned Name Most Toolkit types have assigned String names. You can find an object's assigned name using its getName() method, even after that object has been destroyed.
The following Toolkit types support getName(): ToolkitAtomicLong, ToolkitBarrier, ToolkitBlockingQueue, ToolkitCache, ToolkitList, ToolkitLock, ToolkitMap, ToolkitNotifier, ToolkitReadWriteLock, ToolkitSet, ToolkitSortedMap, ToolkitSortedSet, ToolkitStore.
35.8.4 Returning Existing Toolkit Objects With certain Toolkit types, the Toolkit get methods will either return the existing named object or create it. For example, running Toolkit.getMap("myMap", null, null) returns myMap if it already exists, otherwise a new map is created with the name "myMap".
The following Toolkit types support this functionality: ToolkitBlockingQueue, ToolkitCache, ToolkitList, ToolkitMap, ToolkitNotifier, ToolkitSet, ToolkitSortedMap, ToolkitSortedSet, ToolkitStore.
Names can be reused. If the specified name belonged to a destroyed object, a new object is created using that name.
36 Terracotta Toolkit Reference
This section describes functional aspects of the Terracotta Toolkit.
36.1 Reconnected Client Rejoin A Terracotta client may disconnect and be timed out (ejected) from the cluster. Typically, this occurs because of network communication interruptions lasting longer than the configured HA settings for the cluster. Other causes include long GC pauses and slowdowns introduced by other processes running on the client hardware.
With the rejoin feature, clients will follow a predictable pattern during temporary disconnections:
1. The client receives a clusterOffline event and attempts to reconnect.
2. The 「reconnection timeout」 is reached and the TSA will no longer wait for the client (the client is ejected from the cluster).
3. The client no longer blocks the application, instead throwing RejoinException if any application threads attempt to use its data structures.
4. Upon receiving a clusterOnline event, the client reinitializes its state and joins the cluster as a new client.
228
5. If the rejoin fails, the client continues as before (throwing RejoinException as expected) until a new clusterOnline event is received.
Note the following about the rejoin process:
• Clients rejoin as new members and will wipe all local cached data to ensure that no pauses or inconsistencies are introduced into the cluster. Data that was pending on the rejoined client (data NOT yet acknowledged and persisted by the server) MAY BE LOST.
• Clients cannot rejoin a new cluster; if the TSA has been restarted and its data has not been persisted, the client can never rejoin and must be restarted.
• Any 「nonstop-related operations」 that begin (and do not complete) before the rejoin operation completes may be unsuccessful and may generate a NonStopCacheException. Other operations that begin and do not complete before the rejoin operation completes may throw other exceptions.
• Nonstop and rejoin are independent aspects of the behavior of disconnected clients, but if nonstop is in effect and set to throw an exception, only the NonStopException is thrown. RejoinException is thrown if nonstop is not in effect, or if it is set to no-op or local reads.
• If a Terracotta client with rejoin enabled is running in a JVM with clients that do not have rejoin, then only that client will rejoin after a disconnection. The remaining clients cannot rejoin and may cause the application to behave unpredictably.
• Once a client rejoins, the clusterRejoined event is fired on that client only.
36.2 Connection Issues Client creation can block on resolving URL at this point:
TerracottaClient client = new TerracottaClient("myHost:9510");
If it is known that resolving "myHost" may take too long or hang, your application can should wrap client instantiation with code that provides a reasonable timeout.
A separate connection issue can occur after the server URL is resolved but while the client is attempting to connect to the server. The timeout for this type of connection can be set using the Terracotta property l1.socket.connect.timeout (see 「First-Time Client Connection」).
36.3 Multiple Terracotta Clients in a Single JVM When using the Terracotta Toolkit, you may notice that there are more Terracotta clients in the cluster than expected.
36.3.1 Multiple Clients With a Single Web Application This situation can arise whenever multiple classloaders are involved with multiple copies of the Toolkit JAR.
229
For example, to run a web application in Tomcat, one copy of the Toolkit JAR may need to be in the application's WEB-INF/lib directory while another may need to be in Tomcat's common lib directory to support loading of the context-level . In this case, two Terracotta clients will be running with every Tomcat instance.
36.3.2 Clients Sharing a Node ID Clients instantiated using the same constructor (a constructor with matching parameters) in the same JVM will share the same node ID. For example, the following clients will have the same node ID:
TerracottaClient client1 = new TerracottaClient("myHost:9510"); TerracottaClient client2 = new TerracottaClient("myHost:9511");
Cluster events generated from client1 and client2 will appear to come from the same node. In addition, cluster topology methods may return ambiguous or useless results.
Web applications, however, can get a unique node ID even in the same JVM as long as the Terracotta Toolkit JAR is loaded by a classloader specific to the web application instead of a common classloader.
37 Javadoc
製品に含まれる Javadoc を参照してください。
Microsoft Windows
%BIGMEMORY_HOME%\apis\ehcache\javadoc
UNIX/Linux
${BIGMEMORY_HOME}/apis/ehcache/javadoc
38 Terracottaツールカタログ
38.1 はじめに
ここでは、BigMemory のインストール、テスト、保全に役立つツールを紹介します。特に明記して
いないかぎり、以下のツールは BigMemory のキットに含まれています。
ツールにスクリプトがある場合は、そのスクリプトの名前とパスが、各ツールを説明するセクショ
ンのタイトルのカッコ内に記載されています。スクリプトファイルの拡張子は、UNIX および Linuxでは.sh、Microsoft Windows では.bat です。
ツールによっては、さらに詳しいガイドをご利用いただけます。それぞれのツールに関する記述で、
他のドキュメントが利用可能か確認してください。
230
38.2 アーカイブ・ユーティリティ (archive-tool)
Terracotta サーバまたはクライアントは、Terracotta にサポート関連の問い合わせをする場合にロ
グを生成します。archive-tool はこれらのログを収集します。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\archive-tool.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/archive-tool.sh <args>
<args>には以下のオプションを指定します。
• [-n]（No Data：データファイルを除きます）
• [-c]（Client：クライアントからのファイルを含みます）
• [Terracotta の構成設定用 XML ファイルへのパスまたはログディレクトリへのパス]
• [出力するファイル名。「.zip」形式]
38.3 データベースバックアップユーティリティ (backup-data)
バックアップユーティリティは、Terracotta サーバアレイ（TSA）が保有するデータのスナップシ
ョットを保存します。これにより、お使いのアプリケーションが共有するデータのバックアップが
作成されます。バックアップは、デフォルトのディレクトリである${user.dir}/terracotta/backupsに保存されます。ただし、構成情報の設定で別のディレクトリを指定することもできます。
38.3.1 バックアップの構成情報の設定 以下のように、サーバの構成設定ファイルにある<data-backup>プロパティを使えば、デフォルト
とは違うディレクトリを指定することが可能です。
<servers> <restartable enabled="true"/> ... <server host="%i" name="myServer"> ... <data-backup>/Users/myBackups</data-backup> </server> ... </servers>
バックアップユーティリティを使うには、<restartable>モードを有効にしてください。
231
38.3.2 バックアップの作成 バックアップユーティリティは、バックアップの検出と実行に「Terracotta 管理サーバ（TMS）」
を必要とします。そのため、バックアップを行なうには TMS が稼働中であり、なおかつ TSA に接
続している必要があります。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\tools\security\bin\backup-data.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/backup-data.sh <args>
<args>には以下のオプションを指定します。
• [l] <tms-host:port> –： TMS への接続に使うホストとポートです。省略した場合は、デフォル
トで localhost:9889 を使用します。
• [u] <username> –： TMS が認証を必要とする場合、ユーザー名を指定してください。
• [p] <password> –： TMS が認証を必要とする場合、パスワードを指定してください。
• [a] <agentID> –： TSA のエージェント ID を指定します。TMS 上で TSA への接続の構成設定を
行なう場合、エージェント ID は接続名として設定されます。エージェント ID を指定しないと、
TMS は構成設定済みのエージェント ID の一覧を返します。
• [k] ：このフラグにより、TMS の無効な SSL 証明書は無視されるようになります。
例えば、"someConnection"というエージェント ID を持つクラスタでバックアップを開始するには
以下のように指定します。
${BIGMEMORY_HOME}/tools/security/bin/backup-data.sh -l my-tms-host:9889 -u admin -p admin -a someConnection -k
正常に行なわれた場合、スクリプトはパックアップのプロセスが開始したことを報告します。バッ
クアップが完了すると、現在のデータファイルがある場所で「バックアップデータファイルを使っ
てデータをリストア」できるようになります。
38.4 バックアップステータス (backup-status)
backup-status スクリプトは tools/security/bin ディレクトリから起動します。このスクリプトは、
backup-data ユーティリティの機能を補完するためのツールで、指定クラスタに実行したバックア
ップのステータスを調査します。例えば、エージェント「myClusterAgent」で実行したバックアッ
プ処理の一覧を取得するには、次のように操作します。
232
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/backup-status -l http://myTMShost:9889 -a myClusterAgent
backup-status スクリプトには、backup-data と同じ引数を入力します。
38.5 クラスタのスレッドや状態のダンプ (debug-tool)
クラスタのスレッドや状態のダンプ用デバッグツールを使えば、デバッグ情報を簡単に生成できる
ようになります。生成したデバッグ情報はローカルで分析したり、サポートスタッフに転送するこ
とができます。デバッグツールは、ファイアーウォールが標準 JMX を基にしたツールをブロックし
たり、TMS の使用が困難になった場合に役立ちます。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\debug-tool.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/debug-tool.sh <args>
<args>には以下のオプションを指定します。
• [-d] –：クラスタ内のすべてのノード（サーバおよびクライアント）の状態のダンプを行ない
ます。出力は各ノードのログに記録されます。このオプションを使用すると、非常に大きな情
報量が生成されることがあるので、注意してください。
• [-h] –：標準出力に、簡単なヘルプ情報をプリントアウトします。
• [-n] <hostname> – (--hostname)：対象クラスタ内の Terracotta サーバインスタンスを指定する
引数です。この引数でホスト名を指定しないと、"localhost"が使われます。
• [-p] <jmx-port> – (--jmxport)：対象ホストの JMX ポートを指定する引数です。この引数で JMXポートを指定しないと、"9520"が使われます。
• [-u] <string> – (--username)： JMX ユーザー名（JMX 承認がセットアップされている場合）を
指定します。
• [-w] <string> – (--password)： JMX パスワード（JMX 承認がセットアップされている場合）を
指定します。
-d オプションを使わずにデバッグツールを実行すると、クラスタスレッドのダンプ（すべてのノー
ドにおけるダンプ）が発生します。スレッドのダンプは cluster-dump.zip という ZIP ファイルに書
き込まれ、作業ディレクトリに保存されます。
233
38.6 分散ガベージコレクタ（run-dgc）
run-dgc は、指定したクラスタで分散ガベージコレクション（DGC）を実行するユーティリティで
す。「run-dgc」を使うと、Terracotta ツールキットのデータ構造の使用時など、インライン DGCが有効でない環境において定期的な DGC サイクルを強制実行できます。ただし、ほとんどの環境
では、自動 DGC によるコレクションが十分な役割を果たします。
このユーティリティは、バックアップの検出と実行に「Terracotta 管理サーバ（TMS）」を必要と
します。そのため、DGC を行なうには TMS が稼働中であり、なおかつ TSA に接続している必要が
あります。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\tools\security\bin\run-dgc.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/run-dgc.sh <args>
<args>には以下のオプションを指定します。
• [l] <tms-host:port> –： TMS への接続に使うホストとポートです。省略した場合は、デフォル
トで localhost:9889 を使用します。
• [u] <username> –： TMS が認証を必要とする場合、ユーザー名を指定してください。
• [p] <password> –： TMS が認証を必要とする場合、パスワードを指定してください。
• [a] <agentID> –： TSA のエージェント ID を指定します。TMS 上で TSA への接続の構成設定を
行なう場合、エージェント ID は接続名として設定されます。エージェント ID を指定しないと、
TMS は構成設定済みのエージェント ID の一覧を返します。
• [k] ：このフラグにより、TMS の無効な SSL 証明書は無視されるようになります。
複数の DGC サイクルを同時に実行することはできません。すでに DGC サイクルが進行中のサーバ
で別の DGC サイクルを実行しようとすると、エラーが発生します。
注意：DGC サイクルの多重実行
分散ガベージコレクションの詳細については、「TSA のアーキテクチャーガイド」を参照してくだ
さい。
234
38.7 サーバ起動スクリプトとサーバ停止スクリプト（start-tc-server, stop-tc-
server）
start-tc-server スクリプトを使い、Terracotta サーバを起動します。構成設定ファイルを指定する
ことも可能です。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\start-tc-server.bat [-n <name of server>] [-f <config specification>]
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/start-tc-server.sh [-n <name of server>] [-f <config specification>]
<config specification>には以下の一つを指定します。
• 構成設定ファイルのパス
• 構成設定ファイルの URL
• 別に稼働中の Terracotta サーバの<server host>:<tsa-port>
以下に注意してください。
• 構成情報を設定しないと、現在の作業ディレクトリにある tc-config.xml というファイルが使用
されます。
• 構成情報を設定せず、tc-config.xml というファイルが現在の作業ディレクトリに見つからない
場合は、デフォルトの構成情報が使用されます。
• 使用する構成設定ファイルに複数のサーバが存在する状態でサーバを指定しなかった場合、エ
ラーが標準出力にプリントアウトされます。また、サーバは起動しません。
以下のように stop-tc-server スクリプトを使い、Terracotta サーバを正常に終了します。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\stop-tc-server.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/stop-tc-server.sh <args>
<args>には以下のオプションを指定します。
235
• [f] –：使用する構成設定ファイルを、ファイルのパスまたは URL で指定します。
• [--force] –：アクティブなサーバを強制終了します。
「プロダクションモード」では、「stop-tc-server」スクリプトが STANDBY ステータスのミラ
ーサーバを検出できなかった場合、このスクリプトは警告を出力します。アクティブサーバの
シャットダウンも実行しません。フェイルオーバーが目的でない場合は、--force を使用して、
アクティブサーバを強制的にシャットダウンできます。
• [n] –：シャットダウンするサーバの名前デフォルトはローカルホストです。
• [s] – サーバが JMX パスワードによってセキュリティ保護されている場合は、ユーザー名とパ
スワードをスクリプトに渡してください。
• [u] –： JMX のユーザー名を指定します。
• [w] –： JMX のパスワードを指定します。
38.8 サーバのステータス (server-stat)
ステータスツールはコマンドラインを使うユーティリティです。一つまたは複数の Terracotta サー
バインスタンスの現在のステータスを確認するために使用します。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\server-stat.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/server-stat.sh <args>
<args>には以下のオプションを指定します。
• [-s] host1,host2,... –：デフォルトの JMX ポート（9520）を使ったホスト名や IP アドレスを使
用している一つまたは複数のサーバを確認します。
• [-s] host1:9520,host2:9521,... –： JMX ポートを指定したホスト名や IP アドレスを使用している
一つまたは複数のサーバを確認します。
• [-f] <path>/tc-config.xml –：指定した構成設定ファイルで定義されているサーバを確認します。
ステータスツールは各サーバで問い合わせる以下のデータを返します。
• Health – OK（サーバの応答が正常）または FAILED（接続に失敗またはサーバの応答が正常で
ない）。
236
• Role – アクティブとミラーのグループ内でのサーバの役割。単一のサーバは常に ACTIVE とし
て表示します。バックアップサーバは MIRROR または PASSIVE として表示します。
• State – サーバの作業ステータス。通常、アクティブサーバは ACTIVE-COORDINATOR、ミラー
サーバは MIRROR-STANDBY または PASSIVE-STANDBY と表示します。
• JMX port – JMX イベントの待ち受けにサーバが使用している TCP ポートです。
• Error – ステータスツールに障害があった場合のエラーの種類です。
38.8.1 サンプル 以下のサンプルはステータスツールからの出力と使用量を示します。
[PROMPT] server-stat.sh -s myhost:9521 localhost.health: OK localhost.role: ACTIVE localhost.state: ACTIVE-COORDINATOR localhost.jmxport: 9521
サーバを指定しないと、ステータスツールはデフォルトで JMX ポート「9520」の「localhost」のス
テータスを確認します。
38.9 バージョン･ユーティリティ (version)
バージョンツールはユーティリティスクリプトの一種です。バージョン、日付、インストールを作
成したバージョンコントロールの変更番号などの BigMemory のインストールに関する情報を出力
します。サポートに関するお問い合わせで Terracotta にご連絡する際は、問題解決の促進のため、
バージョンツールの出力をお知らせください。
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\version.bat
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/version.sh&
さらに多くの情報を出力するためには、以下のフラグを使います。
• [r] –：詳細情報を「property=value」形式で出力します。
• [v] –：さらに詳しい情報を出力します。
237
38.10 Terracotta用Mavenプラグイン
Terracotta 用 Maven プラグインを使うと、お使いのアプリケーションの Terracotta でのインスト
ール、統合、更新、実行、テストが可能になります。
Terracotta用Mavenプラグインと詳しいドキュメントは、Terracotta Forgeでご利用になれます。
39 JMX管理と監視
39.1 はじめに
JMX は、管理や監視の仕組みでクラスを取り扱うための標準的な方法を提供します。これにより、
サードパーティー製のツールを使用する際も、「Terracotta 管理サーバ」と同等の機能を利用でき
るようになります。
39.2 JMXの概要
net.sf.ehcache.managementパッケージには、BigMemory MaxでJMXの管理を行なうMBeansとManagementServiceが含まれています。このパッケージは完全に独立しており、JMXとの依存関係
がEhcacheパッケージに影響を与えることはありません。したがって、JMXライブラリを使用するの
は、それが必要になった場合だけで構いません。このJMXは、SunのJMXの成功事例に従って実装さ
れています。
メソッドの MBeanServer に MBeans を登録する場合は、static なメソッド
net.sf.ehcache.management.ManagementService.registerMBeans(...)を使用します。JMX を使用せずに
Ehcache を管理するには、Cache および CacheStatistics が提供する public なメソッドを使用してく
ださい。
以下の図は、管理パッケージのイメージです。
238
39.3 MBeans BigMemory Max は標準 MBeans を使用します。以下の MBeans が提供されています。
• CacheManager
• Cache
• CacheConfiguration
• CacheStatistics
ローカルの MBeanServer には、すべての MBean 属性を指定できます。CacheManager MBean が持
つ Cache MBeans をトラバーサルによって解析し、コレクションが作成されます。各 Cache MBean
239
と、そのサブクラスでは、CacheConfiguration MBean と CacheStatistics MBean のトラバース解析を
実施できます。
39.4 JMXによるリモート処理
リモートの JMX エージェントから MBeanServerConnection 経由で MBeansServer へアクセスするに
は、JMX のリモート API を使用します。リモートアクセスで使用できるのは Serializable 属性だけ
です。Ehcache MBean 属性のうち、リモートアクセスで使用できる属性は以下のとおりです。
• CacheManager 属性の一部
• Cache 属性の一部
• すべての CacheConfiguration 属性
• すべての CacheStatistics 属性
ほとんどの属性はビルトイン型です。すべての属性にアクセスするには、JMX クライアントのクラ
スパスに「ehcache.jar」を追加してください。例：jconsole -J-Djava.class.path=ehcache.jar.
39.5 ObjectNameの名称の構造
• CacheManager - "net.sf.ehcache:type=CacheManager,name=<CacheManager>"
• Cache - "net.sf.ehcache:type=Cache,CacheManager=<cacheManagerName>,name=<cacheName>"
• CacheConfiguration
• "net.sf.ehcache:type=CacheConfiguration,CacheManager=<cacheManagerName>,name=<cacheName>"
• CacheStatistics - "net.sf.ehcache:type=CacheStatistics,CacheManager=<cacheManagerName>,name=<cacheName>"
240
39.6 管理サービス
ManagementService クラスは、API のエントリーポイントです。
メソッドは ManagementService.registerMBeans が 1 つだけです。このメソッドは、CacheManagerが搭載する MBeans を JMX に登録するときに使用します。ManagementService は、
CacheManagerEventListener の 1 つです。したがって、Cache の新規追加や削除と、MBeanServerの正常な更新などの処理が通知されます。MBeans を起動すると、MBeanServer に登録されます。
CacheManager をシャットダウンすると、MBeans の登録が取り消されます。この動作のおかげで、
アプリケーションの配置・削除の対象であるアプリケーションサーバも正しく動作します。
/** * This method causes the selected monitoring options to be be registered * with the provided MBeanServer for caches in the given CacheManager. * * While registering the CacheManager enables traversal to all of the other * items, * this requires programmatic traversal. The other options allow entry points closer * to an item of interest and are more accessible from JMX management tools like JConsole. * Moreover CacheManager and Cache are not serializable, so remote monitoring is not * possible * for CacheManager or Cache, while CacheStatistics and CacheConfiguration are. * Finally * CacheManager and Cache enable management operations to be performed. * * Once monitoring is enabled caches will automatically added and removed from the
241
* MBeanServer * as they are added and disposed of from the CacheManager. When the * CacheManager itself * shutsdown all registered MBeans will be unregistered. * * @param cacheManager the CacheManager to listen to * @param mBeanServer the MBeanServer to register MBeans to * @param registerCacheManager Whether to register the CacheManager MBean * @param registerCaches Whether to register the Cache MBeans * @param registerCacheConfigurations Whether to register the CacheConfiguration MBeans * @param registerCacheStatistics Whether to register the CacheStatistics MBeans */ public static void registerMBeans( net.sf.ehcache.CacheManager cacheManager, MBeanServer mBeanServer, boolean registerCacheManager, boolean registerCaches, boolean registerCacheConfigurations, boolean registerCacheStatistics) throws CacheException {
39.7 JConsoleのサンプル
ここでは、JConsole の管理エージェントと連携して動作する JDK プラットフォームの MBeanServerに、CacheStatistics を登録する方法を紹介します。
CacheManager manager = new CacheManager(); MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer(); ManagementService.registerMBeans(manager, mBeanServer, false, false, false, true);
242
以上で、CacheStatistics MBeans が登録されます。
JConsole 内の CacheStatistics MBeans
39.8 Hibernateの統計
Terracottaでクラスタ化したキャッシュをHibernateの 2 次キャッシュプロバイダーとして利用して
いる場合は、Hibernate統計とEhcacheステータスにJMX経由でアクセスできます。
EhcacheHibernateMBeanは、JMXが提供するすべてのAPIからアクセスするための主要インターフェ
ースです。このインターフェースは、基本的に 2 つのインターフェース（EhcacheStatsとHibernateStats）を継承して作成されています。詳細は、各インターフェースを参照してください。
また、オンラインチュートリアルも参照してください。
39.9 パフォーマンス
キャッシュ統計のコレクションを作成すると、システムのパフォーマンスに悪影響を与える可能性
があります。ただし、統計用の API は有効／無効を自動的に切り替えます。必要な統計情報の規模
が小さい場合、オーバーヘッドはほとんどありません。統計情報の規模が大きくなるほど、オーバ
ーヘッドも大きくなります。デフォルトでは、統計情報が無効化されています。
243
40 ログ
40.1 はじめに
BigMemory Maxは、ユーザーが独自のログフレームワークをプラグインとして利用できるよう、
SLF4Jログファサードを使用しています。ここでは、Ehcacheのログ機能を紹介します。SLF4J全般
の詳細情報は、SLF4Jのサイトを参照してください。
40.2 SLF4Jのログ機能
SLF4F を使用する場合は、ログ作成のための実装を配備のときに選択します。ダウンロードしたキ
ットや Maven が選択可能です。
40.2.1 Mavenが提供するログ機能の実装 ここでは、Maven によるログ機能を選択する場合の例を紹介します。Maven の POM に、以下の 1つを入力してください。
<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-jdk14</artifactId> <version>1.5.8</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> <version>1.5.8</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>1.5.8</version> </dependency>
40.2.2 ダウンロードしたキットが提供するログ機能の実装 ダウンロードしたキットには、BigMemory Maxのjarファイルに加え、slf4j-apiとslf4j-jdk14 のjarファイルが含まれています。アプリケーションがSLF4Jを使用していなくとも、これらのjarファイル
を直ちに利用できます。SLF4JのWebサイトには、ほかのログ機能の実装も公開されています。
244
40.3 ログのレベルの推奨値
BigMemory Max は、重要なメッセージに加え、開発担当者による運用サポートで必要になる詳細な
メッセージも用意しています。「ERROR」メッセージは、正常な運用で表示されてはならないメッ
セージです。何らかの対処が必要であることを意味します。
「WARN」メッセージは、正常時には発生しないイベントが起きた場合や、構成情報の変更が必要
な場合に表示されます。「DEBUG」メッセージと「TRACE」メッセージは、開発担当者が解析に使
用します。DEBUG レベルのメッセージを出力するステートメントは、デバッグ用のブロックに記
述されています。したがって、このレベルを設定しない限り、パフォーマンスには影響しません。
何らかの問題が発生し、問題の原因を追及する必要がある場合に限り、このログレベルを指定して
ください。多くのログ出力システムでは、アプリケーションを再起動しなくともログのレベルを変
更できるようになっています。
41 BigMemoryのシャットダウン
41.1 はじめに
BigMemory は、Ehcache の API を使用してシャットダウンします。なお、Hibernate は、Hibernateの Ehcache の CacheManager を自動的にシャットダウンします。
Ehcache に対する推奨シャットダウン方法は次のとおりです。
• CacheManager.shutdown()を呼び出します。
• Web アプリケーションに、Ehcache の ShutdownListener を登録します。
CacheManager をシャットダウンすると、既存のキャッシュデータはローカルで削除されますが、
（分散キャッシュと共に）TSA またはディスク（再起動可能な場合）に残ることもあります。キャ
ッシュのみが削除された場合（Cache.dispose()または CacheManager.removeCache())）も同様のこ
とが発生します。不必要なデータが永続化しないようにするには、こういったデータを持つすべて
のキャッシュで Cache.removeAll()を呼び出します。
41.2 データの明示的な削除
Cache.remove()を使うことで、キャッシュから特定のエントリーを削除できます。キャッシュを空
にするには Cache.removeAll()を使います。キャッシュそのものを削除（Cache.dispose()または
CacheManager.removeCache())）すると、キャッシュ内に残っていたデータもローカルからは削除
されます。ただし、TSA またはディスク（再起動可能な場合）からは削除されません。
なお、Ehcache には JVM シャットダウンフックも登録できます。しかし、この方法は推奨しません。
245
41.3 ServletContextListener Ehcache は、CacheManager をシャットダウンする ServletContextListener を提供しています。Webアプリケーションをシャットダウンしたとき Ehcache も自動シャットダウンするには、このリスナ
ーを使用してください。通知イベントを受信するためには、Web アプリケーションの配備の記述子
に、このリスナークラスの情報を設定しておく必要があります。設定するには、Web アプリケーシ
ョンの「web.xml」に、以下の記述を追加します。
<listener> <listener-class>net.sf.ehcache.constructs.web.ShutdownListener</listener-class> </listener>
41.4 シャットダウンフック
Ehcache の CacheManager にシャットダウンフックを登録しておくことも可能です。システムプロ
パティに net.sf.ehcache.enableShutdownHook=true を設定することで登録できます。CacheManagerのシャットダウンが完了していないときに仮想マシン（JVM）のシャットダウンを検出すると、自
動的にシャットダウンの処理を行います。
使用中のフレームワークあるいはアプリケーションから CacheManager のシャットダウンを行って
いない場合は、シャットダウンフックを使用します。
注意：シャットダウンフックは、問題を引き起こしやすい機能です。JVM がシャットダウンするた
め、null になってはならないデータが null になる状況などが発生します。Ehcache は、こうした状
況を可能な限り防止します。いずれにせよ、シャットダウンフックは最後の手段とし、できるだけ
使用を避けてください。
シャットダウンフックは、CacheManager 上に存在します。そして、単純にシャットダウン用のメ
ソッドを呼び出します。イベントの発生順序は以下のとおりです。
• 登録されている CacheManager のイベントリスナーに対する呼び出しが終了。
• Cache の呼び出しが終了。各 Cache は、次の処理を行います。
• MemoryStore のシャットダウン。MemoryStore から DiskStore への移動（フラッシュ）。
• DiskStore のシャットダウン。DiskStore が永続化されている（"localRestartable"が設定されて
いる）場合、エントリーとインデックスがディスクに記録されます。
• 登録されている CacheEventListener のシャットダウン。
• Cache のステータスを「シャットダウン」に変更し、それ以上の処理の発生を禁止。
• CacheManager のステータスを「シャットダウン」に変更し、それ以上の処理の発生を禁止。
以下の場合、シャットダウンフックが起動します。
246
• プログラムが正常に稼働している場合。例えば System.exit()が呼び出された場合や、最後のデ
ーモンでないスレッドが終了した場合。
• 仮想マシンを終了した場合。例： UNIX システムでは、CTRL-C が kill -SIGTERM pid または kill -15 pid に応答します。
以下の場合、シャットダウンフックは起動しません。
• 仮想マシンが異常終了した場合。
• UNIX システムで稼働している仮想マシンに、シグナルの「SIGKILL」を送信した場合（例：
kill -SIGKILL pid または kill -9 pid）
• Windows システムのプロセスに TerminateProcess 呼び出しを送信した場合。
41.5 異常なシャットダウン
正常な手順を踏まずに Ehcache をシャットダウンした場合でも、BigMemory の高速再起動が有効
化されている場合、メモリ上のデータは保護されます。詳細は「高速再起動」を参照してください。
42 BigMemory Max Best Practices
The following sections contain advice for optimizing BigMemory Max operations.
42.1 Tuning Off-Heap Store Performance Memory-related or performance issues that arise during operations can be related to improper allocation of memory to the off-heap store. If performance or functional issues arise that can be traced back to the off-heap store, see the suggested tuning tips in this section.
42.1.1 General Memory allocation Committing too much of a system's physical memory is likely to result in paging of virtual memory to disk, quite likely during garbage-collection operations, leading to significant performance issues. On systems with multiple Java processes, or multiple processes in general, the sum of the Java heaps and off-heap stores for those processes should also not exceed the size of the physical RAM in the system. Besides memory allocated to the heap, Java processes require memory for other items, such as code (classes), stacks, and PermGen.
Note that MaxDirectMemorySize sets an upper limit for the JVM to enforce, but does not actually allocate the specified memory. Overallocation of direct memory (or buffer) space is therefore possible, and could lead to paging or even memory-related errors. The limit on direct buffer space set by MaxDirectMemorySize should take into account the total physical memory available, the amount of memory that is allotted to the JVM object heap, and the portion of direct buffer space that other Java processes may consume.
247
In addition, be sure to allocate at least 15 percent more off-heap memory than the size of your data set. To maximize performance, a portion of off-heap memory is reserved for meta-data and other purposes.
Note also that there could be other users of direct buffers (such as NIO and certain frameworks and containers). Consider allocating additional direct buffer memory to account for that additional usage.
42.1.2 Compressed References For 64-bit JVMs running Java 6 Update 14 or higher, consider enabling compressed references to improve overall performance. For heaps up to 32GB, this feature causes references to be stored at half the size, as if the JVM is running in 32-bit mode, freeing substantial amounts of heap for memory-intensive applications. The JVM, however, remains in 64-bit mode, retaining the advantages of that mode.
For the Oracle HotSpot, compressed references are enabled using the option -XX:+UseCompressedOops. For IBM JVMs, use -Xcompressedrefs.
42.1.3 Slow Off-Heap Allocation Based on configuration, usage, and memory requirements, BigMemory could allocate off-heap memory multiple times. If off-heap memory comes under pressure due to over-allocation, the host OS may begin paging to disk, thus slowing down allocation operations. As the situation worsens, an off-heap buffer too large to fit in memory can quickly deplete critical system resources such as RAM and swap space and crash the host OS.
To stop this situation from degrading, off-heap allocation time is measured to avoid allocating buffers too large to fit in memory. If it takes more than 1.5 seconds to allocate a buffer, a warning is issued. If it takes more than 15 seconds, the JVM is halted with System.exit() (or a different method if the Security Manager prevents this).
To prevent a JVM shutdown after a 15-second delay has occurred, set the net.sf.ehcache.offheap.DoNotHaltOnCriticalAllocationDelay system property to true. In this case, an error is logged instead.
42.1.4 Maximum Serialized Size of an Element This section applies when using BigMemory through the Ehcache API.
Unlike the memory and the disk stores, by default the off-heap store has a 4MB limit for classes with high quality hashcodes, and 256KB limit for those with pathologically bad hashcodes. The built-in classes such as String and the java.lang.Number subclasses Long and Integer have high quality hashcodes. This can issues when objects are expected to be larger than the default limits.
To override the default size limits, set the system property net.sf.ehcache.offheap.cache_name.config.idealMaxSegmentSize to the size you require.
For example,
248
net.sf.ehcache.offheap.com.company.domain.State.config.idealMaxSegmentSize=30M
42.1.5 Reducing Faulting While the memory store holds a hotset (a subset) of the entire data set, the off-heap store should be large enough to hold the entire data set. The frequency of misses (get operations that fail to find the data in memory) begins to rise when the data is too large to fit into off-heap memory, forcing gets to fetch data from the disk store (called faulting). More misses in turn raise latency and lower performance.
For example, tests with a 4GB data set and a 5GB off-heap store recorded no misses. With the off-heap store reduced to 4GB, 1.7 percent of cache operations resulted in misses. With the off-heap store at 3GB, misses reached 15 percent.
42.1.6 Swapiness and Huge Pages An operating system (OS) that is swapping to disk can substantially slow down or even stop your application. If the OS is under pressure because Terracotta servers—along with other processes running on a host—are squeezing the available memory, then memory will start to be paged in and out. This type of operation, when too frequent, requires either tuning of the swap parameters or a permanent solution to a chronic lack of RAM.
An OS could swap data from memory to disk even if memory is not running low. For the purpose of optimization, data that appears to be unused may be a target for swapping. Because BigMemory can store substantial amounts of data in RAM, its data may be swapped by the OS. But swapping can degrade overall cluster performance by introducing thrashing, the condition where data is frequently moved forth and back between memory and disk.
To make heap memory use more efficient, Linux, Microsoft Windows, and Oracle Solaris users should review their configuration and usage of swappiness as well as the size of the swapped memory pages. In general, BigMemory benefits from lowered swappiness and the use of huge pages (also known as big pages, large pages, and superpages). Settings for these behaviors vary by OS and JVM. For Oracle HotSpot, -XX:+UseLargePages and -XX:LargePageSizeInBytes=<size> (where <size> is a value allowed by the OS for specific CPUs) can be used to control page size. However, note that this setting does not affect how off-heap memory is allocated. Over-allocating huge pages while also configuring substantial off-heap memory can starve off-heap allocation and lead to memory and performance problems.
Reduce Swapping
Many tools are available to help you diagnose swapping. Popular options include using a built-in command-line utility. On Linux, for example:
• See available RAM with free -m (display memory statistics in megabtyes). Pay attention to swap utilization.
249
• vmstat displays swap-in ("si") and swap-out ("so") numbers. Non-zero values indicate swapping activity. Set vmstat to refresh on a short interval to detect trends.
• Process status can be used to get detailed information on all processes running on a node. For example, ps -eo pid,ppid,rss,vsize,pcpu,pmem,cmd -ww --sort=pmem displays processes ordered by memory use. You can also sort by virtual memory size ("vsize") and real memory size ("rss") to focus on both the most memory-consuming processes and their in-memory footprint.
42.2 Tuning Heap Memory Performance Long garbage collection (GC) cycles are one of the most common causes of issues in a Terracotta cluster because a full GC event pauses all threads in the JVM. Servers disconnecting clients, clients dropping servers, and timed-out processes are just some of the problems long GC cycles can cause. Having a clear understanding of how your application behaves with respect to creating garbage, and how that garbage is being collected, is necessary for avoiding or solving these issues.
42.2.1 Printing and Analyzing GC Logs The most effective way to gain that understanding is to create a profile of GC in your application by using tools made for that purpose. Consider using JVM options to generate logs of GC activity:
• -verbose:gc
• -Xloggc:<filename>
• -XX:+PrintGCDetails
• -XX:+PrintGCTimeStamps
Apply an appropriate parsing and visualization tool to GC log files to help analyze their contents.
42.2.2 Observing GC Statistics With jstat One way to observe GC statistics is by using the Java utility jstat. The following command will produce a log of GC statistics, updated every ten seconds:
jstat -gcutil <pid> 10 1000000
An important statistic is the Full Garbage Collection Time. The difference between the total time for each reading is the amount of time the system was paused. A jump of more than a few seconds will not be acceptable in most application contexts.
42.2.3 Solutions to Problematic GC Once your application's typical GC cycles are understood, consider one or more of the following solutions:
• Maximizing BigMemory to eliminate the drag GC imposes on performance in large heaps.
250
BigMemory opens up off-heap memory for use by Java applications, and off-heap memory is not subject to GC.
• Configuring the 「HealthChecker parameters」 in the Terracotta cluster to account for the observed GC cycles.
Increase nodes' tolerance of inactivity in other nodes due to GC cycles.
• Tuning the GC parameters to change the way GC runs in the heap.
If running multi-core machines and no collector is specifically configured, consider -XX:+UseParallelGC and -XX:+UseParallelOldGC.
If running multiple JVMs or application processes on the same machine, tune the number of concurrent threads in the parallel collector with -XX:ParallelGCThreads=<number>.
Another collector is called Concurrent Mark Sweep (CMS). This collector is normally not recommended (especially for Terracotta servers) due to certain performance and operational issues it raises. However, under certain circumstances related to the type of hosting platform and application data usage characteristics, it may boost performance and may be worth testing with.
• If running on a 64-bit JVM, and if your JDK supports it, use -XX:+UseCompressedOops.
This setting can reduce substantially the memory footprint of object pointer used by the JVM.
• Refactoring clustered applications that unnecessarily create too much garbage.
• Ensuring that the problem node has enough memory allocated to the heap.
42.3 Common Causes of Failures in a Cluster The most common causes of failures in a cluster are interruptions in the network and long Java GC cycles on particular nodes. Tuning the HealthChecker and reconnect features can reduce or eliminate these two problems. However, additional actions should also be considered.
Sporadic disruptions in network connections between L2s and between L2s and L1s can be difficult to track down. Be sure to thoroughly test all network segments connecting the nodes in a cluster, and also test network hardware. Check for speed, noise, reliability, and other applications that grab bandwidth.
Other sources of failures in a cluster are disks that are nearly full or are running slowly, and running other applications that compete for a node's resources.
42.3.1 Do Not Interrupt! Ensure that your application does not interrupt clustered threads. This is a common error that can cause the Terracotta client to shut down or go into an error state, after which it will have to be restarted.
251
The Terracotta client library runs with your application and is often involved in operations which your application is not necessarily aware of. These operations can get interrupted, something the Terracotta client cannot anticipate. Interrupting clustered threads, in effect, puts the client into a state which it cannot handle.
42.3.2 Diagnose Client Disconnections If clients disconnect on a regular basis, try the following to diagnose the cause:
• Analyze the Terracotta client logs for potential issues, such as long GC cycles.
• Analyze the Terracotta server logs for disconnection information and any rejections of reconnection attempts by the client.
• See the operator events panel in the 「Terracotta Management Console」 for disconnection events, and note the reason.
If the disconnections are due to long GC cycles or inconsistent network connections in the client, consider the remedies suggested in 「this section」. If disconnections continue to happen, consider configuring caches with 「nonstop behavior」 and enabling 「rejoin」.
42.3.3 Detect Memory Pressure Using the Terracotta Logs Terracotta server and client logs contain messages that help you track memory usage. Locations of server and client logs are configured in the Terracotta configuration file, tc-config.xml.
You can view the state of memory usage in a node by finding messages similar to the following:
2011-12-04 14:47:43,341 [Statistics Logger] ... memory free : 39.992699 MB 2011-12-04 14:47:43,341 [Statistics Logger] ... memory used : 1560.007301 MB 2011-12-04 14:47:43,341 [Statistics Logger] ... memory max : 1600.000000 MB
These messages can indicate that the node is running low on memory.
42.3.4 Disk usage with both Search and Fast Restart enabled The TSA may be configured to be restartable in addition to including searchable caches, but both of these features require disk storage. When both are enabled, be sure that enough disk space is available. Depending upon the number of searchable attributes, the amount of disk storage required may be up to 1.5 times the amount of in-memory data.
42.4 Manage Sessions in a Cluster • Make sure the configured time zone and system time is consistent between all application servers.
If they are different a session may appear expired when accessed on different nodes.
• Set -Dcom.tc.session.debug.sessions=true and -Dcom.tc.session.debug.invalidate=true to generate more debugging information in the client logs.
252
• All clustered session implementations (including terracotta Sessions) require a mutated session object be put back into the session after it's mutated. If the call is missing, then the change isn't known to the cluster, only to the local node. For example:
Session session = request.getSession(); Map m = session.getAttribute("foo"); m.clear(); session.setAttribute("foo", m); // Without this call, the clear() is not effective across the cluster.
Without a setAttribute() call, the session becomes inconsistent across the cluster. Sticky sessions can mask this issue, but as soon as the session is accessed on another node, its state does not match the expected one. To view the inconsistency on a single client node, add the Terracotta property -Dcom.tc.session.clear.on.access=true to force locally cached sessions to be cleared with every access.
If third-party code cannot be refactored to fix this problem, and you are running Terracotta 3.6.0 or higher, you can write a servlet filter that calls setAttribute() at the end of every request. Note that this solution may substantially degrade performance.
package controller.filter; import java.io.IOException; import java.util.Enumeration; import javax.servlet.Filter; import javax.servlet.FilterChain; import javax.servlet.FilterConfig; import javax.servlet.ServletException; import javax.servlet.ServletRequest; import javax.servlet.ServletResponse; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpSession; public class IterateFilter implements Filter { public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpSession session = ((HttpServletRequest) request).getSession(); if (session != null) { @SuppressWarnings("rawtypes") Enumeration e = session.getAttributeNames(); while (e.hasMoreElements()) {
253
String name = (String)e.nextElement(); Object value = session.getAttribute(name); session.setAttribute(name, value); } } } public void init(FilterConfig filterConfig) throws ServletException { // TODO Auto-generated method stub } public void destroy() { // TODO Auto-generated method stub } }
42.5 A Safe Failover Procedure To safely migrate clients to a standby server without stopping the cluster, follow these steps:
1. If it is not already running, start the standby server using the start-tc-server script. The standby server must already be configured in the Terracotta configuration file.
2. Ensure that the standby server is ready for failover (PASSIVE-STANDBY status). In the TMC, the status light will be cyan.
3. Shut down the active server using the stop-tc-server script.
NOTE: If the script detects that the mirror server in STANDBY state isn't reachable, it issues a warning and fails to shut down the active server. If failover is not a concern, you can override this behavior with the --force flag.
Clients will connect to the new active server.
4. Restart any clients that fail to reconnect to the new active server within the configured reconnection window.
The previously active server can now rejoin the cluster as a standby server. If restartable mode had been enabled, its data is first removed and then the current data is read in from the now active server.
42.6 A Safe Cluster Shutdown Procedure A safe cluster shutdown should follow these steps:
1. Shut down the standby servers using the stop-tc-server script.
254
2. Shut down the clients. The Terracotta client will shut down when you shut down your application.
3. Shut down the active server using the stop-tc-server script.
To restart the cluster, first start the server that was last active. If clustered data is not persisted, any of the servers could be started first as no data conflicts can take place.
43 BigMemory Max FAQ
This FAQ answers questions about how to use BigMemory Max and Terracotta products, integration with other products, and solving issues. If your question doesn't appear here, consider posting it on the Terracotta forums.
Other resources for resolving issues can be found on the Release and Compatibility Information page, including:
• Release Notes – Lists features and issues for specific versions of Terracotta products.
• Compatibility Information – Includes tables on compatible versions of Terracotta products, JVMs, and application servers.
The FAQ is divided into the following sections:
43.1 Getting Started
43.1.1 What's the difference between BigMemory Go and BigMemory Max? BigMemory Go is for in-memory data management on a single JVM (in-process) and comes with 32GB free. BigMemory Max is for distributed in-memory management across an array of servers. For more on Go vs. Max, see the BigMemory Overview.
43.1.2 What platforms does Terracotta software run on? Which application stacks does Terracotta support?
Terracotta is designed to work with as broad an array of platforms, JVMs and application server versions as possible. Supported platforms are listed in the Release and Platform Compatibility Information.
43.1.3 What is the Terracotta Client? The Terracotta Client is functionality in a Java library that operates inside your JVM that enables clustering. When your JVM starts and code is called that initializes Terracotta, the Terracotta Client automatically connects to the Terracotta Server Array to engage clustering services such as the lock manager, object manager, and memory manager.
43.1.4 What is the Terracotta Server Array? The Terracotta Server Array is a set of one or more processes that coordinate data sharing among all Terracotta Clients in the cluster. Each Terracotta Server Array process is a simple Java application that
255
runs directly on the JVM (ie without an application server or container). The Terracotta Server Array is designed to provide maximal High Availability and Scalability.
43.1.5 What is the Terracotta Toolkit? The Terracotta Toolkit is a powerful library designed for developers working on scalable applications, frameworks, and software tools. The Terracotta Toolkit provides a simple set of APIs, which themselves are used to create Terracotta products. Supported APIs include concurrent maps, cyclic barriers, locks, counters, and queues. The Toolkit is designed to be platform independent and runs on any JVM without requiring boot-jars, agents, or container-specific code.
43.2 Configuration, Development, and Operations
43.2.1 How do I enable restartable mode? In the servers section of your tc-config.xml, include the following configurations:
<servers> <server host="host1" name="Server1"> <data-backup>path/to/my/backup/directory</data-backup> <offheap enabled="true" maxDataSize="2tb"/> </server> <restartable enabled="true"/> </servers>
If persistence of shared data is not required across restarts, set <restartable enabled> to "false".
43.2.2 How do I configure failover to work properly with two Terracotta servers? Configure both servers in the <servers> section of the Terracotta configuration file. Start the two Terracotta server instances that use that configuration file, one server assumes control of the cluster (the ACTIVE) and the second becomes the mirror (the PASSIVE). See the 「high-availability page」 for more information.
43.2.3 How do I know that my application has started up with a Terracotta client and is sharing data?
The 「Terracotta Management Console (TMC)」 displays cluster topology by listing Terracotta server groups and connected client nodes in a navigation tree.
In addition, check standard output for messages that the Terracotta client has started up without errors. Terracotta clients also log messages to a file specified in the <clients> section of the tc-config file.
43.2.4 Is there a maximum number of objects that can be held by one Terracotta server instance?
The number of objects that can be held by a Terracotta server instance is two billion, a limit imposed by the design of Java collections. It is unlikely that a Terracotta cluster will need to approach even 50
256
percent of that maximum. However, if it does, other issues may arise that require the rearchitecting of how application data is handled in the cluster.
43.2.5 How many Terracotta clients (L1s) can connect to the Terracotta Server Array (L2s) in a cluster?
While the number of L1s that can exist in a Terracotta cluster is theoretically unbounded (and cannot be configured), effectively planning for resource limitations and the size of the shared data set should yield an optimum number. Typically, the most important factors that will impact that number are the requirements for performance and availability. Typical questions when sizing a cluster:
• What is the desired transactions-per-second?
• What are the failover scenarios?
• How fast and reliable is the network and hardware? How much memory and disk space will each machine have?
• How much shared data is going to be stored in the cluster? How much of that data should be on the L1s? Will BigMemory be used?
• How many stripes (active Terracotta servers) does the cluster have?
• How much load will there be on the L1s? On the L2s?
The most important method for determining the optimum size of a cluster is to test various cluster configurations under load and observe how well each setup meets overall requirements.
43.2.6 What's the best way for my application to listen to Terracotta cluster events such as lost application nodes?
If you are using Ehcache, use the cluster-events Ehcache API. In general, you can use the Terracotta Toolkit API to set up cluster-events listeners.
43.2.7 How can my application check that the Terracotta process is alive at runtime? Your application can check to see if the system property tc.active is true. For example, the following line of code would return true if Terracotta is active at the time it is run:
Boolean.getBoolean("tc.active");
43.2.8 How do I confirm that my Terracotta servers are up and running correctly? Here are some ways to confirm that your Terracotta servers are running:
• Connect to the servers using the 「Terracotta Management Console」.
• Check the standard output messages to see that each server started without errors.
257
• Check each server's logs to see that each server started without errors. The location of server logs is specified in tc-config.xml.
• Use the Terracotta script server-stat.sh or server-stat.bat to generate a short status report on one or more Terracotta servers.
• Use a tool such as wget to access the /config or /version servlet. For example, for a server running on localhost and port 9889, use the following wget command to connect to the version servlet:
[PROMPT] wget http://localhost:9889/version
43.2.9 Are there ways I can monitor the cluster that don't involve using the Terracotta Management Console?
You can monitor the cluster using JMX. .
Cluster events are available over JMX via the object name "org.terracotta:type=TC Operator Events,name=Terracotta Operator Events Bean". Use a tool such as JConsole to view other MBeans needed for monitoring
43.2.10 How can I control the logging level for Terracotta servers and clients? Create a file called .tc.custom.log4j.properties and edit it as a standard log4j.properties file to configure logging, including level, for the Terracotta node that loads it. This file is searched for in the path specified by the environment variable TCINSTALLDIR (if defined), user.home, and user.dir.
43.2.11 Why is it a bad idea to change shared data in a shutdown hook? If a node attempts to change shared data while exiting, and the shutdown thread blocks, the node may hang and be dropped from the cluster, failing to exit as planned. The thread may block for any number of reasons, such as the failure to obtain a lock. A better alternative is to use the cluster events API to have a second node (one that is not exiting) execute certain code when it detects that the first node is exiting. If you are using Ehcache, use the cluster-events Ehcache API. In general, you can use the Terracotta Toolkit API to set up cluster-events listeners.
You can call org.terracotta.api.Terracotta.registerBeforeShutdownHook(Runnable beforeShutDownHook) to perform various cleanup tasks before the Terracotta client disconnects and shuts down.
Note that a Terracotta client is not required to release locks before shutting down. The Terracotta server will reclaim those locks, although any outstanding transactions are not committed.
258
43.3 Environment and Interoperability
43.3.1 Where is there information on platform compatibility for my version of Terracotta software?
Information on the latest releases of Terracotta products, including a link to the latest platform support, is found on the Product Information page. This page also contains a table with links to information on previous releases.
43.3.2 Can I run the Terracotta process as a Microsoft Windows service? While running an application as a Microsoft Windows service has many advantages, such as scheduling and automatic start and restart, there is no official supported configuration for doing this with Terracotta software. However, there are solutions available that have been tried successfully, including some with Java Service Wrapper. This blog entry includes a short procedure, and this blog entry shows how to do the same on a 64-bit system.
Try an Internet search on "windows java service" to find other possible solutions and articles.
43.3.3 Do you have any advice for running Terracotta software on Ubuntu? The known issues when trying to run Terracotta software on Ubuntu are:
• Default shell is dashbash. Terracotta scripts don't behave under dash. You might solve this issue by setting your default shell to bash or changing /bin/sh in our scripts to /bin/bash.
• The Ubuntu default JDK is from GNU. Terracotta software compatibility information is on the Product Information page.
• See the 「UnknownHostException」 topic below.
43.3.4 Which Garbage Collector should I use with the Terracotta Server (L2) process? The Terracotta Server performs best with the default garbage collector. This is pre-configured in the startup scripts. If you believe that Java GC is causing performance degradation in the Terracotta Server, the simplest and best way to reduce latencies by reducing collection times is to store more data in BigMemory Max.
Generally, the use of the Concurrent Mark Sweep collector (CMS) is discouraged as it is known to cause heap fragmentation for certain application-data usage patterns. Expert developers considering use of CMS should consult the Oracle tuning and best-practice documentation.
43.3.5 Can I substitute Terracotta for JMS? How do you do messaging in Terracotta clusters? Using Terracotta with a simple data structure (such as java.util.concurrent.LinkedBlockingQueue), you can easily create message queues that can replace JMS. Your particular use case should dictate whether to replace JMS or continue using it alongside Terracotta. See the 「Terracotta Toolkit API」 for more information on using a clustered queue.
259
43.3.6 Does Terracotta clustering work with Hibernate? Through Ehcache, you can enable and cluster Hibernate second-level caches.
43.3.7 What other technologies does Terracotta software work with? Terracotta software integrates with most popular Java technologies being used today. For a full list, contact us at
info at terracotta dot org
.
43.4 Troubleshooting
43.4.1 After my application interrupted a thread (or threw InterruptedException), why did the Terracotta client die?
The Terracotta client library runs with your application and is often involved in operations which your application is not necessarily aware of. These operations may get interrupted, too, which is not something the Terracotta client can anticipate. Ensure that your application does not interrput clustered threads. This is a common error that can cause the Terracotta client to shut down or go into an error state, after which it will have to be restarted.
43.4.2 Why does the cluster seem to be running more slowly? There can be many reasons for a cluster that was performing well to slow down over time. The most common reason for slowdowns is Java Garbage Collection (GC) cycles. Another reason may be that near-memory-full conditions have been reached, and the TSA needs to clear space for continued operations by additional evictions. For more information, refer to 「Terracotta Server Array Architecture」.
Another possible cause is when an active server is syncing with a mirror server. If the active is under substantial load, it may be slowed by syncing process. In addition, the syncing process itself may appear to slow down. This can happen when the mirror is waiting for specific sequenced data before it can proceed, indicated by log messages similar to the following:
WARN com.tc.l2.ha.L2HACoordinator - 10 messages in pending queue. Message with ID 2273677 is missing still
If the message ID in the log entries changes over time, no problems are indicated by these warnings.
Another indication that slowdowns are occurring on the server and that clients are throttling their transaction commits is the appearance of the following entry in client logs:
INFO com.tc.object.tx.RemoteTransactionManagerImpl - ClientID「2」 : Took more than 1000ms to add to sequencer : 1497 ms
260
43.4.3 Why do all of my objects disappear when I restart the server? If you are not running the server in restartable mode, the server will remove the object data when it restarts. If you want object data to persist across server restarts, run the server in 「restartable mode」.
43.4.4 Why are old objects still there when I restart the server? If you are running the server in restartable mode, the server keeps the object data across restarts. If you want objects to disappear when you restart the server, you can either disable restartable mode or remove the data files from disk before you restart the server. See 「this question」.
43.4.5 Why can't certain nodes on my Terracotta cluster see each other on the network? A firewall may be preventing different nodes on a cluster from seeing each other. If Terracotta clients attempt to connect to a Terracotta server, for example, but the server seems to not not have any knowledge of these attempts, the clients may be blocked by a firewall. Another example is a backup Terracotta server that comes up as the active server because it is separated from the active server by a firewall.
43.4.6 Client and/or server nodes are exiting regularly without reason. Client or server processes that quit ("L1 Exiting" or "L2 Exiting" in logs) for seemingly no visible reason may have been running in a terminal session that has been terminated. The parent process must be maintained for the life of the node process, or use another workaround such as the nohup option.
43.4.7 I have a setup with one active Terracotta server instance and a number of standbys, so why am I getting errors because more than one active server comes up?
Due to network latency or load, the Terracotta server instances may not may be have adequate time to hold an election. Increase the <election-time> property in the Terracotta configuration file to the lowest value that solves this issue.
If you are running on Ubuntu, see the note at the end of the 「UnknownHostException」 topic below.
43.4.8 I have a cluster with more than one stripe (more than one active Terracotta server) but data is distributed very unevenly between the two stripes.
The Terracotta Server Array distributes data based on the hashcode of keys. To enhance performance, each server stripe should contain approximately the same amount of data. A grossly uneven distribution of data on Terracotta servers in a cluster with more than one active server can be an indication that keys are not being hashed well. If your application is creating keys of a type that does not hash well, this may be the cause of the uneven distribution.
43.4.9 Why is a crashed Terracotta server instance failing to come up when I restart it? If running in retartable mode, the ACTIVE Terracotta server instance should come up with all shared data intact. However, if the server's database has somehow become corrupt, you must clear the crashed server's data directory before restarting.
261
43.4.10 I lost some data after my entire cluster lost power and went down. How can I ensure that all data persists through a failure?
If only some data was lost, then Terracotta servers were configured to persist data. The cause for losing a small amount of data could be disk "write" caching on the machines running the Terracotta server instances. If every Terracotta server instance lost power when the cluster went down, data remaining in the disk cache of each machine is lost.
Turning off disk caching is not an optimal solution because the machines running Terracotta server instances will suffer a substantial performance degradation. A better solution is to ensure that power is never interrupted at any one time to every Terracotta server instance in the cluster. This can be achieved through techniques such as using uninterruptible power supplies and geographically subdividing cluster members.
43.4.11 Why does the JVM on my Sun SPARC machines crash regularly? You may be encountering a known issue with the Sun Hotspot JVM for SPARC. The problem is expected to occur with Hotspot 1.6.0_08 and higher, but may have been fixed in a later version. For more information, see this Sun bug report and this possible fix.
43.5 Specific Errors and Warnings
43.5.1 Why, after restarting an application server, does the error Client Cannot Reconnect... repeat endlessly until the Terracotta server's database is wiped?
The default value of the client reconnection setting l1.max.connect.retries is set to "-1" (infinite). If you frequently encounter the situation described in this question and do not want to wipe the database and restart the cluster, change the retry setting to finite value. See the 「high-availability page」 for more information.
43.5.2 What does the warning "WARN com.tc.bytes.TCByteBufferFactory - Asking for a large amount of memory..." mean?
If you see this warning repeatedly, objects larger than the recommended maximum are being shared in the Terracotta cluster. These objects must be sent between clients and servers. In this case, related warnings containing text similar to Attempt to read a byte array of len: 12251178; threshold=8000000 and Attempting to send a message (com.tc.net.protocol.delivery.OOOProtocolMessageImpl) of size may also appear in the logs.
If there are a large number of over-sized objects being shared, low-memory issues and degradation of performance may result.
43.5.3 What is causing regular segmentation faults (segfaults) with clients and/or servers failing?
Segfaults may be caused by Hyperic (Sigar), the library used by Terracotta servers and clients to report on certain system resources, mainly activity data for CPU, combined CPU, disk, and network. You may
262
need to turn off Sigar, thus losing the ability to monitor and record these network resources directly through Terracotta software. To turn off Sigar, set the Terracotta property sigar.enabled to false on the nodes that exhibit the error:
-Dsigar.enabled=false
For more information on setting Terracotta properties, see the Terracotta Configuration Guide and Reference.
43.5.4 When starting a Terracotta server, why does it throw a DBVersionMismatchException?
The server is expecting a Terracotta database with a compatible version, but is finding one with non-compatible version. This usually occurs when starting a Terracotta server with an older version of the database. Note that this can only occur with servers in the restartable mode.
43.5.5 Why am I getting MethodNotFound and ClassNotFound exceptions? If you've integrated a Terracotta product with a framework such as Spring or Hibernate and are getting one of these exceptions, make sure that an older version of that Terracotta product isn't on the classpath. With Maven involved, sometimes an older version of a Terracotta product is specified in a framework's POM and ends up ahead of the current version you've specified. You can use tools such as jconsole or jvisualvm to debug, or specify -XX:+TraceClassLoading on the command line.
If a ClassNotFound exception is thrown at startup, check that a supported JDK (not a JRE) is installed.
43.5.6 When I start a Terracotta server, why does it fail with a schema error? You may get an error similar to the following when a Terracotta server fails to start:
Error Message: Starting BootJarTool... 2008-10-08 10:29:29,278 INFO - Terracotta 2.7.0, as of 20081001-101049 (Revision 10251 by cruise@rh4mo0 from 2.7) 2008-10-08 10:29:30,459 FATAL - ******************************************************************************* The configuration data in the file at "/opt/terracotta/conf/tc-config.xml" does not obey the Terracotta schema: [0]: Line 8, column 3: Element not allowed: server in element servers *******************************************************************************
This error occurs when there's a schema violation in the Terracotta configuration file, at the line indicated by the error text. To confirm that your configuration file follows the required schema, see the schema file included with the Terracotta kit. The kit includes schema files (*.xsd) for Terracotta, Ehcache, and Quartz configurations.
263
43.5.7 The Terracotta servers crash regularly and I see a ChecksumException. If the logs reveal an error similar to com.sleepycat.je.log.ChecksumException: Read invalid log entry type: 0 LOG_CHECKSUM, there is likely a corrupted disk on at least one of the servers.
43.5.8 Why is java.net.UnknownHostException thrown when I try to run Terracotta sample applications?
If an UnknownHostException occurs, and you experience trouble running the Terracotta Welcome application and the included sample applications on Linux (especially Ubuntu), you may need to edit the etc/hosts file.
The UnknownHostException may be followed by "unknown-ip-address".
For example, your etc/hosts file may contain settings similar to the following:
127.0.0.1 localhost 127.0.1.1 myUbuntu.usa myUbuntu
If myUbuntu is the host, you must change 127.0.1.1 to the host's true IP address.
NOTE: You may be able to successfully start Terracotta server instances even with the "invalid" etc/hosts file, and receive no exceptions or errors, but other connectivity problems can occur. For example, when starting two Terracotta servers that should form a mirror group (one active and one standby), you may see behavior that indicates that the servers cannot communicate with each other.
43.5.9 On a node with plenty of RAM and disk space, why is there a failure with errors stating that a "native thread" cannot be created?
You may be exceeding a limit at the system level. In *NIX, run the following command to see what the limits are:
ulimit -a
For example, a limit on the number of processes that can run in the shell may be responsible for the errors.
43.5.10 Why does the Terracotta server crash regularly with java.io.IOException: File exists? Early versions of JDK 1.6 had a JVM bug that caused this failure. Update JDK to avoid this issue.
44 Terracottaサーバアレイ このページの情報は、BigMemory Max 4.0 を対象にしています（Quartz Scheduler および Web Sessions をご利用の際には、Terracotta バージョン 3.7 をご利用ください）。
264
44.1 はじめに
TSA（Terracotta サーバアレイ）は、Terracotta 製品を利用するためのプラットフォームと、
Terracotta クラスタを利用するためのバックボーンを提供する製品です。TSA は、2 つのノードに
よる基本的な並列構成から多重ノード構成までの幅広い構成をサポートし、高いパフォーマンス、
柔軟なスケーラビリティ、そしてさまざまな障害に対応できるフェイルオーバーといった機能を提
供します。
TSA の主な機能は、以下のとおりです。
• インメモリデータの分散管理：一般のデータグリッドに比べ、十数倍から数百倍もの規模のデ
ータを管理できます。
• 構成設定が不要なスケーラビリティ：簡単な構成設定でサーバインスタンスを追加できます。
性能の見積もりやニーズに応じた拡張も簡単です。
• 高可用性：フェイルオーバーは一瞬です。運用もサービス提供も、途切れることはありません。
• 柔軟な状態監視： Terracotta「ヘルスチェッカー」により、各ノードをまたがる監視が可能で
す。
• アプリケーションへの永続性の提供：インメモリで共有されているデータを記録するための永
続ストレージを自動的に設定します。
• 自動ノード再接続：一時的に切断されたサーバインスタンスやクライアントを、稼働を中断せ
ずにクラスタへ再接続（rejoin）します。
44.1.1 BigMemory Max 4.0 の新機能 TSA バージョン 4.0 は、メモリに記録されている全データを保持する、インメモリデータのプラッ
トフォームです。ユーザーは、整合性のあるデータを高速かつ確実に入手できます。利用可能なメ
モリサイズよりも大きなデータが入力された場合でも、リソース管理によってデータのエビクショ
ンと絞り込みを実行し、TSA が限界を超えないように調整します。そして、ほとんどの場合は自動
的に回復し、正常な稼働状態に復帰します。さらには、データを保護するために、高速再起動機能、
アクティブミラーサーバグループ、バックアップという 3 つのシステムを提供します。
データ永続性のための高速再起動
新たに提供された TSA は、BigMemory の高速再起動機能を統合しています。高速リカバリーによ
ってクラッシュから回復し、インメモリのデータセットがどれほど大きくとも、完全な整合性を保
証します。詳細は「高速再起動」を参照してください。
一時ディスク領域が不要な構成
TSA の新たな実装では、一時ディスク領域という選択肢を除外しました。TSA は、すべてのデータ
をインメモリで取り扱います。サーバ上のディスクへのオーバーフローやスワップは発生しません。
265
TSA が管理するデータセットは、常にメモリ上にあります。（ただし、クラスタ化されていない
BigMemory Go では、localTempSwap も選択可能です。）
リソース管理機能
リソース管理機能により、TSA のインメモリデータの時間、サイズ、数といった制限を細かく制御
できます。これにより、メモリが一杯になることの回避と、それに近い状態からの回復を自動化で
きます。詳細は「自動リソース管理」を参照してください。
予測可能なエビクション
メモリが一杯になると、ユーザーが設定した時間、サイズ、数などの構成情報に基づき、TSA が提
供する 3 種類のエビクション方法の 1 つが自動的に働きます。詳細は「エビクション」を参照して
ください。
途切れないアップタイム
柔軟なサーバ起動手順、ミラーやミラーグループの効率的な活用、バックアップの複数分割などに
よりデータの可用性を高め、連続した運用を可能にしています。さらに、現在の TSA では Oracle Berkeley データベースへの依存をやめたため、計画的な再起動や障害による再起動のあとも、イン
メモリのデータをすばやく利用できるようになりました。
Terracotta 管理コンソール（TMC）
デベロッパーコンソールとオペレーションセンターに代わり、拡張された TMC を提供します。新
しい TMC は、システムの監視と管理、Terracotta のデプロイメントの管理などを統合したプラッ
トフォームです。詳細は「Terracotta 管理コンソール」を参照してください。
強化されたセキュリティ機能
Terracotta サーバは、AD（アクティブ・ディレクトリ）と LDAP（ライトウェイト・ディレクト
リ・アクセス・プロトコル）をサポートします。Terracotta クライアント上のカスタム
SecretProvider も、これらのプロトコルを同様にサポートします。これらの機能の詳細は
「Terracotta クラスタのセキュリティ設定」と「LDAP による認証の設定」を参照してください。
DSO を使用しない簡素化された構成設定
DSO 構成設定は廃止されました。代わりに tc-config.xml を使用して構成情報を設定します。ほとん
どの要素は同じですが、階層構造が刷新されました。詳細は「Terracotta 構成情報リファレンス」
を参照してください。
44.2 機能と用語の解説
Terracotta をインストールすることで利用できる主な機能は以下のとおりです。
266
• クラスタ：すべての Terracotta サーバインスタンスとクライアントが連携し、アプリケーショ
ンの状態やデータセットを共有します。
• Terracotta クライアント： Terracotta クライアントは、Terracotta によってクラスタ化され
たアプリケーションと共に、アプリケーションサーバ上で動作します。クライアントは稼働中
の共有オブジェクトグラフを管理します。
• Terracotta サーバインスタンス： 1 つの Terracotta サーバです。「アクティブ」なサーバイ
ンスタンスは、Terracotta クライアントの管理、共有オブジェクトの連携、データの永続化を
行います。サーバインスタンスは、Terracotta クライアント上のクラスタアプリケーションの
動作を検出しません。一方の「ミラー」サーバインスタンスは、即時稼働可能なバックアップ
として機能します。「ホットスタンバイ」とも呼ぶこともあります。ミラーは、アクティブサ
ーバインスタンスの共有データのレプリケーションを記録し続けます。そして、アクティブサ
ーバで障害が発生した場合は、瞬時にアクティブサーバと入れ替わります。各ミラーサーバは、
それぞれのミラーグループにおいて、フェイルオーバーを保証します。
• Terracotta ミラーグループ： Terracotta サーバアレイの構成単位です。「ストライプ」とも
呼びます。1 つのミラーグループは、アクティブな Terracotta サーバインスタンスが 1 つと、
1 つ以上の Terracotta ミラーサーバで構成されます。アクティブサーバインスタンスは、ミラ
ーグループに割り当てられた共有データの断片を永続化します。ミラーグループ内の各ミラー
サーバは、アクティブサーバが管理する共有データのレプリケーションを行います（つまりデ
ータを複製します）。ミラーグループはクラスタの容量を増加させます。ミラーサーバは必須
ではありません。しかし、フェイルオーバーを実現するためにも、できる限り設置することを
お勧めします。
• Terracotta サーバアレイ： 1 つのクラスタに属する全 Terracotta サーバによって構成される
プラットフォームです。アクティブな Terracotta サーバの各インスタンスは、クラスタ化され
たデータ（つまりインメモリのデータ、あるいは共有データ）を均等に分割し、データの管理
や永続化を行います。
このドキュメントでは、Terracotta クライアント（業務用アプリケーションが動作するノード）を
「L1」、Terracotta サーバインスタンスを「L2」と表記する場合があります。これは、Terracotta構成情報ファイルで使用する略称です。
ヒント：呼称について
図 1 に、3 つのミラーグループを持つ Terracotta クラスタを示します。各ミラーグループにはアク
ティブサーバとミラーサーバがあり、クラスタ上の共有データの 3 分の 1 ずつを管理しています。
267
Terracotta クラスタには以下の特徴があります。
• 各ミラーグループは、Terracotta サーバインスタンスの 1 つを自動的に選択し、そのインスタ
ンスをアクティブ化します。1 つのミラーグループで複数のサーバインスタンスがアクティブ
化されることはありません。なお、ミラーグループには、サーバインスタンスをいくつでも登
録できます。しかし、サーバインスタンスを増やしすぎると、パフォーマンスのオーバーヘッ
ドが大きくなります。これは、インスタンスが増えると、アクティブサーバと各ミラーとが同
期するための負荷も大きくなるからです。
• サーバをクラスタ化して利用するには、各ミラーグループ内の中から、それぞれ 1 つの
Terracotta サーバインスタンスをアクティブにする必要があります。
• クラスタ内の共有データは、自動的に分割（パーティション化）されます。これらは、各ミラ
ーグループが分散管理します。共有データのパーティション数は、ミラーグループの数と同じ
です。図 1 では、各ミラーグループが、クラスタ内の共有データの 3 分の 1 ずつを管理して
います。
• ミラーグループは、異なるミラーグループに対するフェイルオーバー機能を提供しません。フ
ェイルオーバーは、同一のミラーグループの中でのみ機能します。別のミラーグループには影
響しません。ミラーグループには、クラスタ内の共有データの一部の範囲だけが割り当てられ
ます。この範囲は、別のグループが管理するデータとは重複しません。つまり、1 つのミラー
グループには、別のミラーグループのレプリケーションが存在しません。図 1 の環境でミラー
グループ 1 がダウンした場合、クラスタは一時停止します（つまり機能しなくなります）。ミ
ラーグループ 1 が、完全なデータを維持した状態で復帰するまで、クラスタは使用できません。
• アクティブサーバには自己調整機能が備わっています。アクティブサーバインスタンスを調整
するための構成設定は不要です。
268
• サーバアレイのうち、ホットスワップが可能なのはミラーサーバインスタンスだけです。図 1のうち、L2 の「ミラー」サーバは、シャットダウンや入れ替えを行っても、クラスタの動作
は影響を受けません。しかし、ミラーグループ全体の追加や削除を行うには、クラスタ全体を
停止させる必要があります。なお、Terracotta 構成情報ファイルを更新しない限り、新規サー
バを追加しても、元の構成のままで機能します。ミラーサーバを入れ替える際は、入れ替え前
のサーバと同じアドレス（ホスト名または IP アドレス）を使用してください。異なる構成情
報を持つミラーサーバに入れ替える必要がある場合は、「稼働中のクラスタのトポロジ変更」
を参照してください。
44.3 詳細情報のリンク
より詳しく知りたいこと リンク先
アーキテクチャー 「Terracotta サーバアレイのアーキテクチャー」
高可用性 「Terracotta クラスタの可用性を高めるための構成設定」
構成情報設定 「Terracotta 構成情報ファイルの設定方法」
リソース管理 「Terracotta サーバアレイのオペレーション」
稼働中のデータのバックアップ 「Terracotta サーバアレイのオペレーション」
45 Terracottaサーバアレイのアーキテクチャー TSA（Teracotta サーバアレイ）は、2 つのノードによる基本的な並列構成から、多重ノードによる
アレイ構成まで、さまざまな形態で利用できます。Terracotta クラスタは、デプロイメントの段階
から本番運用まで、幅広い用途に対応しています。このページでは、クラスタの信頼性、可用性、
拡張性を高めるための方法を紹介します。
45.1 開発用のTerracottaクラスタ
永続性：なし | フェイルオーバー：なし | 拡張性：なし
ほとんどの開発環境では、共有データの永続化が不要です。むしろ邪魔な場合があります。したが
って、永続化を利用しない単一サーバ構成の Terracotta クラスタが、開発環境に最適なソリューシ
ョンだと考えられます。
269
デフォルトでは、Terracotta サーバの高速再起動機能が無効化されています。つまり、再起動する
と共有データが復元されません。この場合の構成情報は以下のようになります。
<?xml version="1.0" encoding="UTF-8" ?> <tc:tc-config xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd"> <servers> <server name="Server1"> <data>/opt/terracotta/server1-data</data> <tsa-port>9510</tsa-port> </server> <servers> ... </tc:tc-config>
サーバがダウンすると、共有ヒープ上にあるアプリケーションの状態（つまり、すべてのクラスタ
化されたデータ）は、すべて消失します。また、クラスタを再接続するには、サーバ起動後にクラ
イアントを再起動する必要があります。
45.2 信頼性を高めるためのTerracottaクラスタ
永続性：あり | フェイルオーバー：なし | 拡張性：なし
270
直前のセクションでは、開発に好都合な構成を紹介しました。もし、インメモリの共有データを永
続化したいと考えるなら、サーバのローカルディスクを使用する構成に変更する必要があります。
Terracotta サーバは、高速再起動機能を利用して、データの永続化を実現します。
45.2.1 高速再起動 高速再起動は、インメモリデータをリアルタイムに記録し、完全な整合性を保証します。提供され
る障害回復能力は、エンタープライズレベルの業務でも利用可能です。シャットダウン（計画的シ
ャットダウンと障害によるシャットダウンを含む）後にアプリケーションを再起動すると、それま
での BigMemory Max のデータはすでに用意されています。直ちにアプリケーションからアクセス
可能です。
高速再起動機能は、サーバのローカルディスクに高速再起動ストアを用意し、そこにインメモリの
データのリアルタイムな記録を永続化します。再起動後、それまでインメモリ（ヒープ領域とオフ
ヒープ領域の両方）にあったデータを、自動的に高速再起動ストアから復旧します。それまで接続
していたクライアントも、クラスタに再接続できます。再接続のタイムアウトは<client-reconnect-window>要素で設定します。
高速再起動は、構成情報ファイルの tc-config.xml に、<restartable>要素と<offheap>要素を追加する
ことで有効化します。
<?xml version="1.0" encoding="UTF-8" ?> <tc:tc-config xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd"> <servers> <server name="Server1">
271
<data>/opt/terracotta/server1-data</data> <tsa-port>9510</tsa-port> <offheap> <enabled>true</enabled> <maxDataSize>2g</maxDataSize> </offheap> </server> <!-- Fast Restartability must be added explicitly. --> <restartable enabled="true"/> <!-- By default the window is 120 seconds. --> <client-reconnect-window>120</client-reconnect-window> </servers> ... </tc:tc-config>
高速再起動を利用するには、<offheap>の有効化も必要です。maxDataSize に割り当てる値の最小値
は 512MB です。ストアのサイズについては、以下の表を参照してください。
オフヒープ設定時の領域 ヒープの必要最小領域
1-10 GB 1 GB
10-100 GB 2 GB
100 GB - 1 TB + 3 GB +
（オフヒープ領域の構成情報は tc-config.xml で設定します）
（ヒープ領域の構成情報は-Xmx Java オ
プションを使って設定します）
また、高速再起動を利用するには、一意のパスを明示的に指定する必要があります。デフォルトの
パスは、Terracotta サーバのホームディレクトリです。パスを変更するには<data>要素を使用しま
す。
TSA は検索可能なキャッシュを保有しつつ再起動ができるように設定できますが、これらの機能は
共にディスク容量を必要とします。この両機能を有効化する場合は、十分なディスク容量が利用で
きることを確認してください。検索可能な属性の数によっては、必要とされるディスク容量がイン
メモリデータの 1.5 倍になることもあります。
注意：検索と高速再起動を有効化したディスク使用
<client-reconnect-window>のデフォルト値の変更が不要な場合は、この要素を省略できます。なお、
<client-reconnect-window>が有効化されるのは、再起動モードが有効化されている場合のみです
（<restartable enabled="true"/>）。
272
45.3 可用性の高いTerracottaサーバアレイ
永続性：あり | フェイルオーバー：あり | 拡張性：なし
直前のセクションでは、信頼性を高めたクラスタの構成を紹介しました。しかし、クラスタの可用
性は高くありません。サーバが停止すると、クラスタも停止します。フェイルオーバーに必要な冗
長性を備えていないからです。可用性を高めるにはミラーサーバを追加します。ミラーサーバは、
アクティブサーバに障害が発生したときに利用される「ホットスタンバイ」として機能します。
このサーバアレイでは、アクティブなサーバインスタンスが停止したとき、直ちにミラーが処理を
引き継ぎます。したがって、クラスタは停止しません。データも消失しません。
2 つのサーバでサーバアレイを構築するための Terracotta 構成情報ファイルの例を、以下に示しま
す。
<?xml version="1.0" encoding="UTF-8" ?> <tc:tc-config xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd"> <servers> <server name="Server1"> <data>/opt/terracotta/server1-data</data> <tsa-port>9510</tsa-port> <tsa-group-port>9530</tsa-group-port> <offheap>
273
<enabled>true</enabled> <maxDataSize>2g</maxDataSize> </offheap> </server> <server name="Server2"> <data>/opt/terracotta/server2-data</data> <tsa-port>9510</tsa-port> <tsa-group-port>9530</tsa-group-port> <offheap> <enabled>true</enabled> <maxDataSize>2g</maxDataSize> </offheap> </server> <restartable enabled="true"/> <client-reconnect-window>120</client-reconnect-window> </servers> ... </tc:tc-config>
ミラーサーバの数を増やすには、<server>セクションの数を増やします。しかし、サーバインスタ
ンスを増やしすぎると、パフォーマンスのオーバーヘッドが大きくなります。これは、インスタン
スが増えると、アクティブサーバと各ミラーとが同期するための負荷も大きくなるからです。
注意：Terracotta サーバインスタンスのデータディレクトリは、共有しないでください。各サーバ
の<data>要素には、ローカルディスク上の一意のディレクトリを指定します。
45.3.1 サーバの起動 サーバインスタンスの起動時の動作は、インスタンス起動時のクラスタの稼働状況によって異なり
ます。
単一サーバを利用する構成の場合、サーバは起動時に起動ルーチンを実行し、クラスタを利用可能
な状態にします（ステータス「ACTIVE」）。複数のサーバインスタンスを同時に起動すると、1 つ
がアクティブサーバに設定され（ステータス「ACTIVE-COORDINATOR」）、ほかのサーバはミラー
に設定されます（ステータス「PASSIVE-STANDBY」）。アクティブとミラーの選択状況は、サーバ
のログに記録されます。
アクティブサーバのインスタンスが稼働しているときに、別のサーバインスタンスを起動すると、
起動したサーバは最初に同期処理を行います。それが完了してからミラーになります。ミラーサー
バがいつでもアクティブサーバになれるよう、アクティブサーバとミラーサーバは、常に同期して
いる必要があります。ミラーサーバのステータスには以下のものがあります。
274
1. PASSIVE-UNINITIALIZED：ミラーサーバが起動シーケンスを実行している状態です。フェイ
ルオーバーの準備もできていないため、アクティブサーバの障害やシャットダウンに対応でき
ません。TMC（Teracotta 管理コンソール）でサーバステータスを示すライトは、赤からオレ
ンジに変わります。
2. INITIALIZING：ミラーサーバが同期処理を実行している状態です。フェイルオーバーの準備
もできていないため、アクティブサーバの障害やシャットダウンに対応できません。TMC（Teracotta 管理コンソール）のサーバステータスを示すライトはオレンジになります。
3. PASSIVE-STANDBY：ミラーサーバの同期が完了した状態です。フェイルオーバーの準備も完
了しているため、アクティブサーバの障害やシャットダウンにも対応できます。TMC（Teracotta 管理コンソール）のサーバステータスを示すライトはシアンです。
同期処理の実行中は、同期のための送信処理が発生するため、アクティブサーバインスタンスにも
負荷がかかります。同期処理に要する時間は、クラスタ化されたデータの量と、そのときのクラス
タの負荷によって変わります。全体のスループット向上のためには、同じような性能の構成をアク
ティブとミラーのサーバインスタンスに割り当ててください。また、無駄な同期処理を防ぐために
も、アクティブサーバとミラーサーバは同時に起動してください。
どのようなシーケンスでサーバを起動しても、データの内容は変わりません。それまでミラーサー
バとして使用されていたサーバインスタンスがアクティブサーバより先に起動したとしても、ミラ
ーサーバのデータは消失しません。アクティブサーバの起動が完了する前にミラーサーバがオフラ
インになった場合でも、そのサーバインスタンスは自分がミラーだったことを記録しています。再
びオンラインに復帰した場合は、ミラーとして正常に機能します。ミラーサーバが復帰した時点で
アクティブサーバがオフラインになっている場合、ミラーサーバはアクティブサーバに変化しませ
ん。そのままアクティブサーバが復帰するのを待ちます。この間、サーバはクライアントからのデ
ータ更新要求をブロックします。アクティブが復帰したら、ミラーは正常に稼働を開始します。こ
のあと、ミラーのデータオブジェクトとインデックスは、「dirty-objectdb-backup」ディレクトリ
に移動されます。そして、アクティブはミラーとデータを同期します。
45.3.2 フェイルオーバ 2 つ以上のミラーサーバインスタンスが使用可能なときにアクティブサーバインスタンスが使用不
能になると、ミラーの 1 つが新しいアクティブになります。少なくとも 1 つ以上のミラーサーバが
アクティブサーバと完全に同期していないと、フェイルオーバーによる新しいサーバへの切り替え
は成功しません。クライアントのフェイルオーバー（新しいアクティブサーバへの切り替え）が正
しく実行されるのは、アクティブサーバのフェイルオーバーが正しく実行されたときに限ります。
同期の完了したミラーが存在しないうちにアクティブサーバがシャットダウンすると、そのクラス
タ全体が利用できなくなります。
ミラーサーバの maxDataSize がアクティブサーバよりも小さい場合、ミラーサーバは正しく起動し
ません。この場合は、構成情報が不正であることを示すアラートがユーザーに通知されます。複数
のミラーサーバがあり、それぞれのオフヒープストアのサイズが異なる場合は、maxDataSize に最
275
も小さい値が指定されている（かつ、アクティブサーバの maxDataSize 以上の値が指定されている）
ミラーサーバが新しいアクティブサーバになります。
ミラーサーバインスタンスは、ホットスワップが可能です。ただし、Terracotta 構成情報に定義さ
れている元のミラーの<server>ブロックと同じ構成である必要があります。例えば、新しいミラー
は、元のミラーと同じホスト名または IP アドレスを利用している必要があります。異なる構成情
報を持つミラーに入れ替える必要がある場合の操作方法は、「稼働中のクラスタのトポロジ変更」
を参照してください。
ヒント：ミラーサーバのホットスワップ
ミラーとして機能している Terracotta サーバインスタンスは、再起動モードを有効にしても無効に
してもかまいません。再起動モードが有効なサーバ（<restartable enabled="true"/>）がダウンして、
それをミラーが引き継いだとします。この場合、ダウンしたサーバは、データディレクトリをクリ
アしてからクラスタに再接続します。データディレクトリは、必ずクリアされます。サーバがダウ
ンしてからも、クラスタ上の情報は変化しているからです。サーバが再起動するとき、サーバは新
しいアクティブサーバインスタンスからのデータを使用して同期を行います。
クラスタデータが永続化されているときに両方のサーバがダウンした場合は、自動的にアクティブ
になるサーバが最初に起動します。これは、データの不整合や消失を防ぐためです。
データを永続化しない、つまり再起動モードが無効な場合、データは保存されません。また、どの
サーバを先に起動してもかまいません。
45.3.3 安全なフェイルオーバー手順 クラスタ稼働中に、クライアントを安全にミラーサーバへ接続するには、以下の手順に従ってくだ
さい。
1. ミラーサーバが稼働していない場合は、start-tc-server スクリプトを使用してミラーサーバを
起動します。あらかじめ、Terracotta 構成情報ファイルにミラーサーバの構成情報を定義して
おいてください。
2. ミラーサーバのステータスを確認します。フェイルオーバー準備が整っていること（PASSIVE-STANDBY）を確認してください。TMC（Terracotta 管理コンソール）のステータスを示すライ
トはシアンになっているはずです。
3. stop-tc-server スクリプトを使用して、アクティブサーバをシャットダウンします。
注意：スクリプトが STANDBY ステータスのミラーサーバを検出できなかった場合、このスク
リプトは警告を出力します。アクティブサーバのシャットダウンも実行しません。フェイルオ
ーバーが目的でない場合は、--force を使用して、アクティブサーバを強制的にシャットダウ
ンできます。
276
クライアントは新しいアクティブサーバに接続します。
4. <client-recconect-window>で設定した時間内に再接続できなかったクライアントは再起動が必
要です。
以上の操作で、それまでアクティブサーバとして接続していたインスタンスを、ミラーサーバとし
てクラスタに再接続できます。再起動モードが有効化されていた場合、再接続したサーバのデータ
はクリアされ、新しいアクティブサーバから最新のデータを読み込みます。
45.3.4 安全なクラスタのシャットダウン手順 クラスタを安全にシャットダウンする手順は以下のとおりです。
1. stop-tc-server スクリプトを使用して、すべてのミラーサーバをシャットダウンします。
2. クライアントをシャットダウンします。利用中のアプリケーションをシャットダウンすれば、
Terracotta クライアントもシャットダウンします。
3. stop-tc-server スクリプトを使用して、アクティブサーバをシャットダウンします。
クラスタを再起動するときは、それまでのアクティブサーバを最初に起動してください。ただし、
クラスタデータを永続化していない場合は、データの不整合が発生しません。したがって、どのサ
ーバを先に起動してもかまいません。
45.3.5 スプリットブレイン（ネットワークパーティション問題） Terracott クラスタにおける「スプリットブレイン」とは、2 つ以上のサーバが自身をアクティブサ
ーバとして認識する（ステータスが ACTIVE-COORDINATOR になる）ことを指します。この現象は、
アクティブサーバとミラーサーバ間のネットワークが切断されたときに発生します。両方がアクテ
ィブサーバになり、それぞれが<client-reconnect-window>で指定された時間を利用してクライアン
トとの再接続を行います。
これら 2 つのサーバ間の接続が切断されたままならば、2 つの独立したクラスタとして、そのまま
稼働を続けます。この状態は、まだ「スプリットブレイン」ではありません。しかし、サーバ間の
接続が再開すると、以下のシナリオの 1 つが発生します。
• 新しいアクティブサーバにクライアントが接続していなかった場合：元のアクティブサーバが、
新しいアクティブサーバを再起動します。新しいアクティブサーバはミラーとして再起動し、
データベースをクリアし、再びミラーとして同期を行います。
• 新しいアクティブサーバに乗り換えたクライアント数のほうが少ない場合：新しいアクティブ
サーバに接続しているクライアントに対し、元のアクティブサーバが再接続タイムアウト処理
を開始します。同時に、元のアクティブサーバは、新しいアクティブサーバの再起動を開始し
ます。新しいアクティブサーバはミラーとして再起動し、データベースをクリアし、再びミラ
ーとして同期を行います。新しいアクティブサーバに乗り換えたクライアントは、元のアクテ
277
ィブサーバに再接続します。サーバのパラメーターに指定されている時間内に再接続できなか
った場合、そのクライアントは再起動が必要になります。
• 新しいアクティブサーバに乗り換えたクライアント数のほうが多い場合：新しいアクティブサ
ーバが、元のアクティブサーバの再起動を開始します。元のアクティブサーバはミラーとして
再起動し、データベースをクリアし、新たにミラーとして同期を行います。<client-reconnect-window>で設定した時間内に新しいアクティブサーバへ接続できなかったクライアントは、再
起動が必要になります。
• 新しいアクティブサーバに乗り換えたクライアントの数と、元のクライアントに接続している
クライアントの数が同じ場合：これは、本当に半分のクライアントだけが新しいアクティブサ
ーバに乗り換えるという珍しいシナリオです。どちらのサーバが最新のトランザクションを保
持しているのか（あるいは新しいデータを保持しているのか）を判断する必要があります。ア
クティブサーバになるのは、より新しい情報を保持しているサーバです。このアクティブサー
バは、もう一方のサーバを再起動します。クライアントは、上に紹介したシナリオと同様の動
作になります。この競合の解決に時間がかかる場合は、手動操作によるサーバのシャットダウ
ンも考慮に入れてください。
Terracotta クラスタは、共有データを破損または消失することなく、ほとんどのスプリットブレイ
ン現象を解決できます。ただし、こうした現象の発生後は、できる限り共有データの完全性の確認
を推奨します。
45.4 拡張性を備えたTerracottaサーバアレイ
永続性：あり | フェイルオーバー：あり | 拡張性：あり
2 つのサーバ（アクティブとミラー）による構成では、容量に関する需要に応えられない場合があ
ります。このような場合は、Terracotta クラスタをミラーグループ構成にします。ミラーグループ
は、Terracotta サーバアレイに高いスケーラビリティをもたらします。ミラーグループでは、複数
のアクティブな Terracotta サーバインスタンスが協調して動作します。
278
ミラーグループは、Terracotta 構成情報ファイルの<servers>セクションで定義します。ミラーグル
ープでは、各 Terracotta サーバインスタンスを、グループのメンバーとして設定します。4 つのサ
ーバを利用するミラーグループの構成情報の例を以下に示します。
... <servers> <mirror-group election-time="10" group-name="groupA"> <server name="server1"> ... </server> <server name="server2"> ... </server> </mirror-group> <mirror-group election-time="15" group-name="groupB"> <server name="server3"> ... </server> <server name="server4"> ... </server> </mirror-group> <restartable enabled="true"/> </servers> ...
279
この例では、アクティブサーバを 2 つ設定し、それぞれに 1 つずつミラーサーバを割り当てていま
す。サーバ 1 がグループ A のアクティブサーバになった場合、サーバ 2 はミラーサーバになりま
す。サーバ 3 がグループ B のアクティブサーバになった場合、サーバ 4 はミラーサーバになりま
す。サーバ 1 とサーバ 3 は、クラスタ内の Terracotta クライアントと共有データとの管理を行うよ
う自動的に設定されます。
複数のアクティブなサーバインスタンスが存在する Terracotta クラスタを設計した場合は、すべて
のミラーグループのサーバインスタンスがアクティブサーバの候補になります。すべてのミラーグ
ループで 1 つのサーバインスタンスがアクティブになると、これらのアクティブサーバインスタン
スが協調してクラスタを管理します。アクティブとして選出されなかったサーバインスタンスは、
ミラーグループ内のアクティブサーバインスタンスのミラーとして機能します。ミラーグループ内
のアクティブサーバがダウンした場合は、ミラーグループ内から新しいアクティブサーバが選出さ
れます。サーバがダウンしても、クライアントは通常どおり稼働し続けます。
1 つの<servers>セクションには、複数の<server>または<mirror-group>を指定できます。ただし、
これらは同時に指定できません。<servers>下のすべての<server>構成情報はひとつのミラーグルー
プとして機能します。そのうち、ひとつはアクティブサーバ、残りはミラーサーバとなります。複
数のストライプを作成するには<servers>下の<mirror-group>構成情報を使用します。こうすること
により、そのミラーグループの構成情報には複数の<server>構成情報が含まれるようになります。
注意：サーバとミラーグループ
ミラーグループを持つ Terracotta クラスタでは、各グループまたは「ストライプ」が、アクティブ
サーバとミラーサーバの 2 台を利用した構成（詳細は「可用性の高い Terracotta サーバアレイ」を
参照）と同様に動作します。例えば、ストライプを利用する環境の場合、アクティブサーバインス
タンスが存在する状態で別のサーバインスタンスが起動すると、起動したサーバはアクティブサー
バの状態を同期してからミラーとして機能します。ミラーサーバは、同期が完了するまでアクティ
ブサーバインスタンスになりません。再起動モードが有効（）なアクティブサーバインスタンスが
ダウンして、ミラーが引き継いだ場合、データディレクトリをクリアしてからダウンしたサーバを
再起動します。
45.4.1 アクティブサーバ選出時間 構成情報の<mirror-group>では、アクティブサーバの選出に費やす時間（選出時間）を指定できま
す。その選出時間を利用して、接続されているサーバの数を調査し、アクティブサーバを決定しま
す。選出時間の単位は秒で、デフォルト値は 5 秒です。選出時間を決める際は、ネットワーク遅延
時間や、サーバ負荷を考慮してください。
上に示した例では、groupA が新しいアクティブサーバの選出に費やす時間は 10 秒です。その一方
で、groupB は 15 秒を費やします。
280
45.4.2 ストライプとクラスタ障害 ミラーグループのアクティブサーバで障害や切断が発生した場合、ミラーサーバがアクティブサー
バになる（つまり ACTIVE-COORDINATOR ステータスに変わる）まで、クラスタは動作を停止しま
す。
ただし、1 つのストライプ全体で障害が発生した場合は、クラスタは再稼働できません。ストライ
プ全体に障害が発生したあと、アクティブサーバ選出時間内にミラーグループのアクティブサーバ
が選出されなかった場合、クラスタ全体を再起動する必要があります。
46 Terracotta構成情報ファイルの編集
46.1 はじめに
Terracotta の構成情報は XML 形式のファイルです。このファイルを使用して、Terracotta のサーバ
インスタンスやクライアントの属性や動作を定義します。Terracotta BigMemory Max キットに同梱
のサンプル構成情報ファイルをコピーして、自分の環境に合わせて編集するのが、最も簡単な
Terracotta 構成情報のカスタマイズ方法です。
Terracotta 構成情報ファイルの保存場所や、そのファイルを Terracotta サーバやクライアントがロ
ードするタイミングなどは、ユーザーのプロジェクトの段階や、利用しているアーキテクチャーに
よって異なります。このドキュメントでは、以下のステージをカバーしています。
• 開発ステージ（1 つの Terracotta サーバ）
• 開発ステージ（2 つの Terracotta サーバ）
• デプロイメントステージ
このドキュメントでは、Terracotta サーバアレイによるクラスタの構成方法にも触れます。
Terracotta サーバインスタンスの詳細は「Terracotta サーバアレイのアーキテクチャー」を参照し
てください。
また、注釈付きの構成情報ファイルのサンプルは、Terracotta キット内の config-samples/tc-config-express-reference.xml を参照してください。
46.2 構成情報設定のヒント
Terracotta 構成情報ファイルを利用して Terracotta サーバアレイを構築するには、以下の点に注意
が必要です。
• Terracotta 構成情報ファイルには、2 つ以上の<servers>セクションを定義する必要があります。
• Terracotta サーバ同士の通信に使用するポートは、<tsa-group-port>で設定します。
281
• 1 つの<servers>セクションには、複数の<server>または<mirror-group>を指定できます。ただ
し、これらは同時に指定できません。指定できるのは、複数のサーバだけ、あるいは複数のミ
ラーグループだけです。<servers>セクションに指定した<server>インスタンスは、1 つのミラ
ーグループとして機能します。複数のストライプを作成するには<mirror-group>を使用します。
• Terracotta サーバインスタンスのデータディレクトリは、共有しないでください。各サーバの
<data>要素には、ローカルディスク上の一意のディレクトリを指定します。
• データを永続化するには、高速再起動を有効化します。<restartable>を有効化すると、インメ
モリの共有データのバックアップが作成されます。障害発生時には、それらが自動的に復旧し
ます。データの永続化を利用しない場合は、<restartable>に"false"を設定するか、
<restartable>要素そのものを省略します。
• <offheap>を有効化すると、すべてのデータをインメモリに記録します。記録できるデータの
量は、サーバのメモリ容量によって異なります。高速再起動を利用するには、<offheap>の有
効化も必要です。<maxDataSize>には、サーバのメモリ容量のうち、利用可能なサイズを指定
します。
• すべてのサーバとクライアントで、同じバージョンの Terracotta と Java を使用してください。
46.3 Terracottaサーバの構成情報ファイルの指定方法
Terracotta サーバ起動時には、以下のソースから構成情報ファイルをロードします。
• Terracotta キットに含まれているデフォルトの構成情報
• ローカルまたはリモートの XML ファイル
以下は、これらのソースの説明です。
46.3.1 デフォルト構成 構成情報を明示的に指定せず、Terracotta インスタンスを起動したディレクトリにも tc-config.xmlが存在しない場合、構成情報のすべての値にデフォルト値を割り当てます。
46.3.2 ローカルXMLファイル（デフォルト） 構成情報を明示的に指定しなかった場合は、Terracotta インスタンスの起動ディレクトリに存在す
る tc-config.xml を使用します。
46.3.3 ローカルまたはリモートの構成情報ファイル Terracotta サーバの起動スクリプトに「-f」オプションを使用すると、構成情報ファイルを明示的
に指定できます。UNIX/Linux で Terracotta サーバを起動する例を以下に示します。
start-tc-server.sh -f <path_to_configuration_file>
282
<path_to_configuration_file>には、構成情報ファイルの URL または相対パスを指定します。
Microsoft Windows の場合は、start-tc-server.bat を使用します。
46.4 Terracottaクライアントの構成情報ファイルの指定方法
Terracotta クライアント起動時には、以下のソースから構成情報ファイルをロードします。
• 「ローカルまたはリモートの XML ファイル」
• 「Terracotta サーバ」
• Enterprise Ehcache および Enterprise Ehcache for Hibernate が使用する Ehcache 構成情報ファ
イル（「<terracottaConfig>」要素）。
• Quartz Scheduler が使用する Quartz プロパティファイル（org.quartz.jobStore.tcConfigUrl プロ
パティ）。
• Terracotta Web Sessions が使用する web.xml 内の filter 要素の値。
• Terracotta ツールキットを使用してプログラムからクライアントをインスタンス化するときに
使用するクライアントのコンストラクタ（TerracottaClient()）。
Terracotta クライアントは、<client>および<application>構成を指定するためにカスタマイズされた
設定ファイルをロードすることができます。ただし、クラスタ内の各クライアントの<servers>ブロ
ックは、クラスタ内のサーバの<servers>ブロックと完全に一致させる必要があります。一致しない
箇所があると、クライアントはエラーを通知し、起動に失敗します。
Terracotta クライアントが使用する<servers>ブロックの内容が、サーバ側の情報と一致しない場
合、Terracotta クライアントの起動時に configuration-mismatch エラーが発生します。しかし、あ
る特定の条件下では、これらの情報が一致していても、同じエラーが発生します。このエラーを防
ぐには、以下を試してください。
- 互換性オプションの-Djava.net.preferIPv4Stack を指定します。このオプションをクライアント側
で明示的に指定する場合は、サーバ側でも明示的に指定する必要があります。
- etc/hosts ファイルで、Terracotta サーバが稼働するホストのエントリーが重複していないことを
確認します。
- Terracotta サーバが稼働しているホストのアドレスとして、常に同じ値を DNS が返すことを確認
します。
注意：構成情報ファイルの不一致によるエラー
283
46.4.1 ローカルまたはリモートのXMLファイル 「Terracotta サーバの構成情報ファイルの指定方法」のローカル XML ファイル（デフォルト）の解
説を参照してください。
Terracotta クライアントの構成情報ファイルを指定する場合は、「開発用のクライアント」を参照
してください。
Terracotta クライアントの起動時には、一部の構成情報を Terracotta サーバから取得する必要があ
ります。クライアントは、最初に自分自身の構成情報をロードし、そこで取得した Terracotta サー
バ名を利用して接続を行います。この構成情報で指定されたサーバ名に接続できなかった場合、ク
ライアントは起動処理を完了できません。
注意：サーバから構成情報を取得する場合
46.4.2 Terracottaサーバ Terracotta サーバから Terracotta クライアントに構成情報をロードするには、Terracotta サーバの
ホスト名とポート番号を指定します。詳細は「本番業務用のクライアント」を参照してください。
46.5 開発環境の構成設定
開発環境では、構成情報そのもののテストやチューニングを行うためにも、個々の Terracotta クラ
イアントに独自の構成情報ファイルを用意したほうがよいでしょう。このほうが、使用するアプリ
ケーションを Terracotta でクラスタ化するための最善策を発見しやすくなります。
46.5.1 1 つのサーバを使用する開発環境 Terracotta サーバが 1 つだけの場合は、デフォルトの構成情報で十分です。
284
デフォルト構成設定を使用するには、tc-config.xml ファイルのないディレクトリから start-tc-server.sh スクリプト（または start-tc-server.bat)を実行して Terracotta サーバを起動します。
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.sh
構成情報ファイルを指定する方法は「Terracotta サーバの構成情報ファイルの指定方法」を参照し
てください。
46.5.2 2 つのサーバを使用する開発環境 2 つのサーバを利用する開発環境では、1 つがアクティブサーバインスタンスとして機能し、もう
1 つが「ホットスタンバイ（ミラー）」として機能します。このため、「アクティブ－ミラー構成」
と呼ぶこともあります。この構成では、2 つのサーバが全く同じ構成情報を使用します。
285
この構成では 2 つのサーバを使用します。したがって、Teracotta サーバがロードする構成情報フ
ァイルにも、2 つの<server>要素を定義します。以下に例を示します。
<tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-5.xsd" xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... <!-- Use an IP address or a resolvable host name for the host attribute. --> <server host="123.456.7.890" name="Server1"> ... <server host="myResolvableHostName" name="Server2"> ... </tc:tc-config>
アクティブサーバが Server1 だとすると、Server2 に全く同じ構成情報を指定します。これにより、
Server2 はフェイルオーバに備えたホットスタンバイとして機能します。両方の Terracotta サーバ
を同じホストで実行する場合は、ポート番号を示す構成情報として<tsa-port>だけを指定します。
<jmx-port>と<l2-group-port>の値は自動的に設定されます。
286
1 台のマシン上で複数のサーバを実行する場合は、<tsa-port>や<server-logs>といった<server>セク
ションの要素に対し、サーバごとに異なる値を設定する必要があります。
注意：同じホストで 2 つのサーバを実行する場合
起動に使用するサーバ名
複数の<server>要素を定義するときは、name 属性が必須になる場合があります。これは、サーバ
起動時の曖昧さを回避するためです。
start-tc-server.sh -n Server1 -f <path\_to\_configuration\_file>
Microsoft Windows の場合は、start-tc-server.bat を使用します。
例えば、同一ホスト上で Terracotta サーバインスタンスを実行する場合、スクリプトは起動対象の
サーバを明示する必要があるため、name 属性が必須になります。
ただし、name 属性を指定しなくとも、Terracotta サーバインスタンスを明示的に指定することも
可能です。そのような場合は name 属性を省略できます。例えば、Terracotta 構成情報ファイルに
は、それぞれのサーバに対して異なる IP アドレスを指定できます。そうすれば、スクリプトは、
その IP アドレスに対応するローカル IP アドレスを持つサーバを起動できるようになります。
46.5.3 開発用のクライアント クライアント用の Terracotta 構成ファイルを明示的に指定するには、Terracotta クライアントでア
プリケーションを起動するときに-Dtc.config=path/to/my-tc-config.xml を指定します。
-Dtc.config=path/to/my-tc-config.xml -cp classes myApp.class.Main
myApp.class.Main には、アプリケーションを起動するためのクラスを指定します。こうして起動し
たアプリケーションが、Terracotta によってクラスタ化されます。
Java を実行したディレクトリに tc-config.xml ファイルが存在する場合は、-Dtc.config を指定しなく
ても、そのファイルがロードされます。
287
46.6 本番業務環境の構成設定
本番環境を効率よく保守するには、1 つの Terracotta 構成情報ファイルだけで運用することを推奨
します。このファイルを Terracotta サーバ（サーバ群）がロードし、クライアントに配布します。
複数のファイルを使うことも可能ですが、1 ファイルにまとめたほうが集中管理できるため、保守
しやすくなります。
Terracotta 構成情報ファイルがホスト名に"%i"を指定している場合、本番環境では実際のホスト名
に変更してください。例えば、開発環境の構成情報が次のようになっていたとします。
<server host="%i" name="Server1">
本番環境のホスト名が「myHostName」に決定した場合は、この属性の値を"myHostName"に変更
します。
<server host="myHostName" name="Server1">
46.6.1 本番業務用のクライアント 本番業務のクライアントでは、アプリケーションを起動する前に Terracotta 環境をセットアップし
ます。
Terracotta 環境のセットアップ
288
Terracotta クライアントでアプリケーションを起動する際は、そのアプリケーション用のスクリプ
トを使用します。その際、以下の環境変数を設定します。
TC_INSTALL_DIR=<path_to_local_Terracotta_home> TC_CONFIG_PATH=<path/to/tc-config.xml>
あるいは
TC_CONFIG_PATH=<server_host>:<tsa-port>
<server_host>:<tsa-port>には、実行中の Terracotta サーバのホスト名とポート番号を指定します。
Terracotta クライアントは、ここで指定した Terracotta サーバから構成情報を受信します。
ほかに、システムプロパティの「tc.config」を使用する方法もあります。クライアントは、このプ
ロパティで指定した Terracotta サーバから構成情報を受信します。
-Dtc.config=serverHost:tsaPort
複数のサーバを指定する場合は、カンマで区切ります。
TC_CONFIG_PATH=<server_host1>:<tsa-port>,<server_host2>:<tsa-port>
こうすると、<server_host1>が利用できないときは<server_host2>を利用するようになります。
Terracotta 製品
Terracotta 製品は、製品ごとの構成情報ファイルを使用して、Terracotta サーバの構成情報のパス
を設定できます。
BigMemory Max および Enterprise Ehcache は、Ehcache の構成情報ファイル（デフォルトでは
ehcache.xml）の<terracottaConfig>要素で指定します。
<terracottaConfig url="localhost:9510" />
Quartz は、Quartz プロパティファイル（デフォルトでは quartz.properties）の
org.quartz.jobStore.tcConfigUrl プロパティで指定します。
org.quartz.jobStore.tcConfigUrl = /myPath/to/tc-config.xml
Web Sessions は、web.xml または context.xml の要素で指定します。詳細は「Web Sessions のイン
ストール」を参照してください。
46.7 インターフェースに対するポートのバインド
通常、Terracotta 構成情報でサーバのポートを指定する際は、そのサーバのホストに関連付けられ
たインターフェースにポートをバインドします。例えば、サーバの IP アドレスが「12.345.678.8」
289
の場合（IP アドレスではなくホスト名での指定も可能）、サーバのポートも同じインターフェース
にバインドします。
<server host="12.345.678.8" name="Server1"> ... <tsa-port>9510</tsa-port> <jmx-port>9520</jmx-port> <tsa-group-port>9530</tsa-group-port> </server>
しかし、サーバのポートに異なるインターフェースを指定する必要が生じる場合もあります。この
場合は bind 属性を使用します。この属性を利用すれば、異なるインターフェースにポートをバイ
ンドできます。例えば、JMX クライアントが、あるホスト上の特定のインターフェースにしかアク
セスできない場合もあります。ホストのインターフェースと異なるポートに JMX をバインドする場
合の例を以下に示します。
<server host="12.345.678.8" name="Server1"> ... <tsa-port>9510</tsa-port> <jmx-port bind="12.345.678.9">9520</jmx-port> <tsa-group-port>9530</tsa-group-port> </server>
46.8 利用中の構成情報の確認
各サーバと各クライアントは、それぞれ独自のログディレクトリを使用するよう設定します。デフ
ォルトでは、サーバのログは%(user.home)/terracotta/server-logs に、クライアントのログ
は%(user.home)/terracotta/client-logs に出力されます。
クライアントやサーバが、利用している構成情報を確認するには、ログファイル中から
「Configuration loaded from」というテキストを含む INFO メッセージを探してください。
47 Terracottaクラスタの可用性を高めるための構成設定
47.1 はじめに
高可用性（HA）とは、アップタイム（つまりシステムの実稼働状態）を維持し、コンポーネントの
負荷が高いときや障害が発生したときでもサービスにアクセスできることを目指した実装のことで
す。Terracotta クラスタでは、Terracotta サーバアレイを利用すれば、スケーラブルな高可用性の
実装を簡単に設定できるようになっています。詳細は「Terracotta サーバアレイのアーキテクチャ
ー」を参照してください。
290
Terracotta の高可用性を支えるアーキテクチャーによって提供される機能は以下のとおりです。
• ホットスタンバイあるいは複数のアクティブサーバを利用したフェイルオーバ機能：アップタ
イムが継続するため、サービスの提供も途切れません。
• カスタマイズ可能なノード間自動監視機能： Terracotta「ヘルスチェッカー」と呼びます。
• 最新の共有されたインメモリデータに対する自動永続ストレージ機能：すべてのサーバインス
タンスが利用できます。アプリケーションの状態を損なうことがありません。
• 一時的に切断されたサーバインスタンスやクライアントの自動再接続機能：オペレーターによ
る介在なしでホットスタンバイからの復帰と、切断されたクライアントの再接続が可能です。
クライアントの再接続とは、まだ Terracotta サーバアレイのクラスタから切り離されていないクラ
イアントが対象です。クラスタから切り離されてしまった BigMemory Max クライアントを再接続
する方法は、「Terracotta クライアントへの自動再接続（rejoin）」を参照してください。
このドキュメントでは、Terracotta クライアント（業務用アプリケーションが動作するノード）を
「L1」、Terracotta サーバインスタンスを「L2」と表記する場合があります。これは、Terracotta構成情報ファイルで使用する略称です。
ヒント：呼称について
本番運用を開始する前に、可用性に関する設定内容には十全なテストを行ってください。可用性を
高めるための構成設定に対するテストの概要は、このページの「配備済み環境の可用性のテスト」
セクションを参照してください。
47.2 可用性を高めるための基本的な構成設定
可用性を高めるために必要な最小限の構成は以下のとおりです。
• 2 つ以上のサーバインスタンス
可用性を高めるためには、構成情報の<server>または<mirror-group>を利用します。<server>で指定したインスタンスはミラーグループとして動作します。しかし、2 つ以上のストライプ
を利用する場合や、アクティブサーバの選出時間を設定する場合は、<mirror-group>を使用し
ます。複数の Terracotta サーバインスタンスによるクラスタの設定方法は、「Terracotta サー
バアレイのアーキテクチャー」を参照してください。
• サーバとサーバの再接続
291
Terracotta クラスタのアクティブサーバインスタンスとミラーサーバインスタンスの接続を再
開できるようにするには、再接続の仕組みを利用します。詳細は「サーバインスタンスの自動
再接続」を参照してください。
• サーバとクライアントの再接続
Terracotta クラスタのクライアントとサーバインスタンスの接続を再開できるようにするには、
再接続の仕組みを利用します。詳細は「クライアントの自動再接続」を参照してください。
47.3 高可用性に関する機能
ここでは、可用性を高めるための機能を紹介します。これらの機能を利用することで、Terracottaクラスタの信頼を高めることが可能です。これらの機能のプロパティは、Terracotta 構成情報ファ
イルの先頭の<tc-properties>セクションで設定します。
<tc:tc-config xmlns:tc="http://www.terracotta.org/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-8.xsd"> <tc-properties> <property name="some.property.name" value="true"/> <property name="some.other.property.name" value="true"/> <property name="still.another.property.name" value="1024"/> </tc-properties> <!-- The rest of the Terracotta configuration goes here. --> </tc:tc-config>
詳細は、「Terracotta 構成情報リファレンス」の「tc.properties のオーバーライド」を参照してく
ださい。
47.3.1 ヘルスチェッカー ヘルスチェッカーは、TCP キープアライブ（TCP keep-alive）とよく似た接続モニタです。ヘルス
チェッカーは、高可用性環境の Terracotta サーバインスタンスどうしの間や、Terracotta サーバイ
ンスタンスとクライアントの間で機能します。ヘルスチェッカーを使用すると、通信相手のノード
に接続できるか、正常に稼働しているか、GC（ガーベジコレクション）が発生しているか、などを
確認できます。Terracotta ノードがヘルスチェッカーを利用していれば、相手ノードがダウンして
いるなどの理由で接続できない場合の対処を設定できるようになります。デフォルトでは、ヘルス
チェッカーが有効化されています。
292
ヘルスチェッカー構成情報の設定には、Terracotta のプロパティを使用します。このプロパティは
3 つのカテゴリに分類できます。
• Terracotta サーバ -> Terracotta クライアント
• Terracotta サーバ -> Terracotta サーバ（高可用性モードのみ）
• Terracotta クライアント -> Terracotta サーバ
プロパティのカテゴリは、プレフィックスで区別できます。
• 「l2.healthcheck.l1」は「L2 -> L1（サーバ ->クライアント)」
• 「l2.healthcheck.l2」は「L2 -> L2（サーバ ->サーバ)」
• 「l1.healthcheck.l2」は「L1 -> L2（クライアント ->サーバ)」
例えば、プロパティに l2.healthcheck.l2.ping.enabled と記述すると、「L2 -> L2（サーバ ->サーバ）」
に適用されます。
Terracotta 構成情報ファイルの\セクションに記述できるヘルスチェッカー関連のプロパティは以
下のとおりです。
プロパティ 定義内容
l2.healthcheck.l1.ping.enabled l2.healthcheck.l2.ping.enabled l1.healthcheck.l2.ping.enabled
ping テストを有効化（True）あるいは無効化（False）し
ます。ping テストは、相手ノードがリクエストに応答で
きるかどうかを調査するための高レベルなテストです。過
負荷や障害によって一時的にノードが無応答になっている
かどうかを診断します。相手ノードで長い GC（ガーベジ
コレクション）が発生している場合、ping テストは不合
格（つまり「無応答」）になります。
l2.healthcheck.l1.ping.idletime l2.healthcheck.l2.ping.idletime l1.healthcheck.l2.ping.idletime
相手ノードの無応答（ネットワークトラフィックがない）
状態の最大許容時間を指定します。単位は「ミリ秒」で
す。この時間を過ぎると、ヘルスチェッカーは ping テス
トを実行し、相手ノードが稼働中かどうかを確認します。
l2.healthcheck.l1.ping.interval l2.healthcheck.l2.ping.interval l1.healthcheck.l2.ping.interval
ping テストの再試行間隔を指定します。単位は「ミリ
秒」です。ping テストが不合格（無応答）になると、ヘ
ルスチェッカーは、このプロパティで指定された時間だけ
待機し、再び ping テストを実行します。
l2.healthcheck.l1.ping.probes l2.healthcheck.l2.ping.probes l1.healthcheck.l2.ping.probes
ping テストの再試行回数の最大値を、整数で指定しま
す。ヘルスチェッカーは、このプロパティで指定された回
数の ping テストを実行します。
l2.healthcheck.l1.socketConnect l2.healthcheck.l2.socketConnect l1.healthcheck.l2.socketConnect
ソケット接続テストを有効化（True）あるいは無効化
（False）します。ソケット接続テストは、相手ノードへ
の接続と、相手ノードによるネットへのアクセスを確認す
るための、低レベルな接続テストです。ソケット接続テス
293
トは GC（ガーベジコレクション）の影響を受けません。
l2.healthcheck.l1.socketConnectTimeout l2.healthcheck.l2.socketConnectTimeout l1.healthcheck.l2.socketConnectTimeout
相手ノードの応答の待ち時間（最大合計時間）を計算する
ための係数を、整数で指定します。最大合計時間を過ぎる
と、それまでのソケット接続テストの結果にかかわらず、
ヘルスチェッカーは相手ノードがダウンしていると判断し
ます。最大合計時間は、このプロパティで指定した係数
（整数）と、ping.interval で指定した値（時間）の乗算結
果です。
l2.healthcheck.l1.socketConnectCount l2.healthcheck.l2.socketConnectCount l1.healthcheck.l2.socketConnectCount
ping テストが不合格（無応答）であるにもかかわらず、
ソケット接続テストは合格（接続中）、と判断される回数
の最大値を整数で指定します。この値を超えると、ヘルス
チェッカーは相手ノードがダウンしていると判断します。
l1.healthcheck.l2.bindAddress 設定された IP アドレスにクライアントをバインドしま
す。ホストがクライアントに対して複数の IP アドレスを
許可している環境で使用します。デフォルト値は"0.0.0.0"です。これは、1 つの IP アドレスだけを割り当てるとい
う意味です。
l1.healthcheck.l2.bindPort クライアントのコールバックポートを指定します。ヘルス
チェッカーはクラスタ内の通信を受信するためのポートを
クライアントに割り当てる必要があります。しかし、
Terracotta 構成情報では、このポートを割り当てていませ
ん。デフォルト値は"0"です。これは、システムにポート
の割り当てを許可するという意味です。クライアントのコ
ールバックポートを割り当てない場合は"-1"を設定しま
す。
ヘルスチェッカーがどのように機能するのかを、以下の図に示します。
294
ヘルスチェッカーによる最大時間の計算
ヘルスチェッカーが「リモートノードがダウンしている」と判断するのに要する最大時間は、以下
の式で計算できます。
Max Time = (ping.idletime) + socketConnectCount * [(ping.interval * ping.probes) + (socketConnectTimeout * ping.interval)]
この計算式を利用する際は、以下の注意が必要です。
• ソケット接続テストの回数に対するレスポンス時間は「(socketConnectTimeout * ping.interval)」以下です。所要時間が計算上の最大値となる最悪のシナリオを計算するには、この値を使用し
ます。現実には、ソケット接続テストのレスポンス時間は限りなく 0 に近いため、ほとんど無
視できます。したがって、前述の計算式は以下のように簡略化できます。
Max Time = (ping.idletime) + [socketConnectCount * (ping.interval * ping.probes)]
295
• ヘルスチェッカーのプロセスのトリガになる ping.idletime は、プロセスが起動するときに 1回だけ使用されます。したがって、この値がカウントされるも 1 回だけです。
• socketConnectCount は乗算に使用されます。これは、ソケット接続テストに対する受信があれ
ば、ヘルスチェッカーはプロセスを繰り返すからです。
• 実際のテストでは、環境によって応答時間が異なります。したがって、アイドル時間
（ping.idletime）には誤差があることを見込んでください。
• 計算式による最大時間が、「L2 -> L2（サーバ ->サーバ）」よりも「L1 ->L2（クライアント ->サーバ）」のほうが 8 から 12 秒ほど長くなるようにプロパティを設定してください。これは、
ミラーサーバとクライアントの両方からアクティブサーバが一時的に切断されたとき、クライ
アントが短時間でサーバと切断してしまうのを防止するためです。「L1 -> L2」と「L2 -> L2」の値が近すぎると、アクティブサーバがミラーを停止し、さらにクライアントからの再接続を
拒否する場合があります。
構成情報のサンプル
ここでは「L1 -> L2（クライアント ->サーバ）」で使用するヘルスチェッカー構成情報の例を紹介
します。「L2 -> L2」や「L2 -> L1」も同様に設定できます。
厳格な設定
以下は、厳格な設定の例です。短時間のネットワーク切断や長い GC（ガーベジコレクション）が
発生すると、ヘルスチェッカーは早い段階で障害が発生したと判断します。
<property name="l1.healthcheck.l2.ping.enabled" value="true" /> <property name="l1.healthcheck.l2.ping.idletime" value="2000" /> <property name="l1.healthcheck.l2.ping.interval" value="1000" /> <property name="l1.healthcheck.l2.ping.probes" value="3" /> <property name="l1.healthcheck.l2.socketConnect" value="true" /> <property name="l1.healthcheck.l2.socketConnectTimeout" value="2" /> <property name="l1.healthcheck.l2.socketConnectCount" value="5" />
「相手ノードがダウンしている」とヘルスチェッカーが判断するまでに要する時間を、前述の「最
大時間」の式で計算してみます。
2000 + 5 [( 3 * 1000 ) + ( 2 * 1000)] = 27000
最初のアイドル時間は 2 秒です。このあとの ping テストに相手ノードは応答しないものの、すべ
てのソケット接続テストには応答します。したがって、物理的にはノードが接続されていているも
のの、機能していない（指定された時間内に応答しない）、あるいは GC に時間がかかっていると
判断できます。このヘルスチェッカーの構成設定（厳格な設定）では、最長で 27 秒後に「ノード
がダウンしている」と判断されます。
296
ソケット接続テストの結果が不合格だった場合（つまり、未接続と判断された場合）、ヘルスチェ
ッカーはもっと早い時点でノードがダウンしていると判断します。最初のソケット接続テストが不
合格だった場合、ノードがダウンしていると判断されるまでの時間は、次のように短くなります。
2000 + 1[3 * 1000) + ( 2 * 1000 ) = 7000
以上のように、ヘルスチェッカーは遅くとも 7 秒後に、ノードがダウンしていると判断します。
緩い設定
以下は、緩い設定の例です。ネットワーク切断や GC（ガーベジコレクション）が発生したときで
も、ヘルスチェッカーはそれほど早い段階で障害が発生したとは判断しません。
<property name="l1.healthcheck.l2.ping.enabled" value="true" /> <property name="l1.healthcheck.l2.ping.idletime" value="5000" /> <property name="l1.healthcheck.l2.ping.interval" value="1000" /> <property name="l1.healthcheck.l2.ping.probes" value="3" /> <property name="l1.healthcheck.l2.socketConnect" value="true" /> <property name="l1.healthcheck.l2.socketConnectTimeout" value="5" /> <property name="l1.healthcheck.l2.socketConnectCount" value="10" />
「相手ノードがダウンしている」とヘルスチェッカーが判断するまでに要する時間を、前述の「最
大時間」の式で計算してみます。
5000 + 10 [( 3 x 1000 ) + ( 5 x 1000)] = 85000
最初のアイドル時間は 5 秒です。このあとの ping テストに相手ノードは応答しないものの、すべ
てのソケット接続テストには応答します。したがって、物理的にはノードが接続されていているも
のの、機能していない（指定された時間内に応答しない）、あるいは GC の時間が極端に長いと判
断できます。このヘルスチェッカーの構成設定（緩い設定）では、最長で 85 秒後に「ノードがダ
ウンしている」と判断されます。
ソケット接続テストの結果が不合格だった場合（つまり、未接続と判断された場合）、ヘルスチェ
ッカーはもっと早い時点でノードがダウンしていると判断します。最初のソケット接続テストが不
合格だった場合、ノードがダウンしていると判断されるまでの時間は、次のように短くなります。
5000 + 1[3 * 1000) + ( 5 * 1000 )] = 13000
以上のように、ヘルスチェッカーは遅くとも 13 秒後に、ノードがダウンしていると判断します。
ガーベジコレクションやネットワーク障害を許容するためのヘルスチェッカーのチューニング
ソケット接続テストは、ノードで GC（ガーベジコレクション）が発生しても合格します（「接続
中」と診断されます）。しかし、ネットワーク障害が発生した場合は不合格になります（「未接続」
と診断されます）。この違いを利用してヘルスチェッカーをチューニングすれば、クラスタで発生
297
する問題を効率よく診断できるようになります。一方の現象を敏感に検出するには、次のように設
定します。
• ネットワーク障害に敏感な設定が好ましい場合は、socketConnectCount の値を小さくします
（ネットワーク障害が発生すると、ソケット接続テストが不合格になる確率が高いからです）。
こような設定にすると、ヘルスチェッカーはネットワーク障害の発生したノードの切断を、よ
り早く判断できます。
• GC による無応答に敏感な設定が好ましい場合は、socketConnectCount の値を大きくします
（GC による無応答が発生しても、ソケット接続テストには合格する確率が高いからです）。
このような設定にすると、ネットワーク切断が発生しにくいクラスタでは、ノードが除外され
にくくなります。
「ping.interval」の値を大きくすると、ソケット接続テストを開始するまでの時間も長くなります。
ping.interval の値を下げると、上に記述した現象の両方を、敏感に検出するようになります。値を
上げると、検出基準は緩くなります。
47.3.2 サーバインスタンスの自動再接続 自動再接続を利用していれば、ホットスタンバイが有効な Terracotta サーバアレイで一時的なネッ
トワーク障害が発生しても、サーバインスタンスの再起動が不要になります。HA（高可用性）モー
ドが有効化されているクラスタでは、自動再接続機能もデフォルトで有効化されています。
自動再接続機能に対するタイムアウト値を設定すると、フェイルオーバが発生するまでの時間が長
くなります。
注意：フェイルオーバ発生までの時間
この機能は、イベント発生に合わせて動作します。また、ヘルスチェッカーとは同時に動作しませ
ん。ヘルスチェッカーが起動済みの場合、同一ノードではこの機能が起動しません。逆に、
Terracotta の内部イベントによって、この機能のほうが先に起動した場合、同一ノードではヘルス
チェッカーが起動しません。この機能を起動するイベントは、API に公開されていません。しかし、
ログには記録されます。
再接続機能を使用するには、以下のプロパティを設定します。
• l2.nha.tcgroupcomm.reconnect.enabled： "true"を設定した場合は、切断が検出されたときに、
そのサーバインスタンスとペアになるサーバインスタンスに対する再接続が試行されます。デ
フォルト値は"false"です。ほとんどの事例では、この機能を有効化（"true"）したほうがよい
でしょう。
298
• l2.nha.tcgroupcomm.reconnect.timeout：l2.nha.tcgroupcomm.reconnect.enabled に"true"を設定
したときに利用されるプロパティです。再接続のタイムアウト値を指定します。単位は「ミリ
秒」です。デフォルト値は 2000 です。この値を大きくすると、ネットワーク切断の許容時間
も長くなります。
47.3.3 クライアントの自動再接続 通常、Terracotta クラスタから切断されたクライアントをクラスタに再接続するには、そのクライ
アントを再起動する必要があります。自動再接続機能を利用すれば、短時間のネットワーク障害に
よって Terracotta クラスタからクライアントが切断された場合でも、クライアントを再起動する必
要がなくなります。
この機能を有効化した場合、再接続を待っているクライアントによるロックも解放されません。し
たがって、再接続を待っている間は、一部のアプリケーションのスレッドがブロックされる場合も
あります。
注意：クライアント自動再接続のパフォーマンスに対する影響
この機能は、イベント発生に合わせて動作します。また、ヘルスチェッカーとは同時に動作しませ
ん。ヘルスチェッカーが起動済みの場合、同一ノードではこの機能が起動しません。逆に、
Terracotta の内部イベントによって、この機能のほうが先に起動した場合、同一ノードではヘルス
チェッカーが起動しません。この機能を起動するイベントは、API に公開されていません。しかし、
ログには記録されます。
再接続機能を使用するには、以下のプロパティを設定します。
• l2.l1reconnect.enabled： "true"を設定した場合は、切断が検出されたときに、そのクライアン
トに対する再接続が試行されます。デフォルト値は"false"です。クライアントの再接続の有効
化／無効化は、サーバインスタンスのプロパティとして設定します。サーバインスタンス側の
設定値が、クライアントに転送されます。クライアント側では、この設定を上書きできません。
クライアントの設定とサーバインスタンスの設定が一致しない場合で、クライアントがクラス
タへの再接続を実行した場合、クライアントは不整合エラーを起こして終了します。ほとんど
の事例では、この機能を有効化（"true"）したほうがよいでしょう。
• l2.l1reconnect.timeout.millis：l2.l1reconnect.enabled に"true"を設定したときに利用されるプロ
パティです。再接続のタイムアウト値を指定します。単位は「ミリ秒」です。クライアントの
再接続のタイムアウト値は、サーバインスタンスのプロパティとして設定します。サーバイン
スタンス側の設定値が、クライアントに転送されます。クライアント側では、この設定を上書
きできません。デフォルト値は 2000 です。この値を大きくすると、ネットワーク切断の許容
時間も長くなります。
299
47.3.4 特殊なクライアント接続プロパティ 以下の特殊なケースに該当するクライアント接続もチューニング可能です。
• サーバ障害発生後のクライアントのフェイルオーバ
• 最初のクライアント接続
これらのケースに該当する接続プロパティは、すでに最適化されています。こうしたプロパティを
変更する際は、新しい設定値を利用して十分にテストを実施してください。
サーバ障害発生後のクライアントのフェイルオーバ
ミラーサーバが利用できる状態のときにアクティブな Terracotta サーバインスタンスで障害が障害
が発生すると、ミラーサーバがアクティブになります。Terracotta クライアントは、それまでのア
クティブサーバから新しいアクティブサーバに接続を切り替えます。ただし、こうしたクライアン
ト側のフェイルオーバ処理は、所要時間が制限されています。
単一の Terracotta サーバだけを利用したクラスタでサーバが再起動するときにも、再接続の所要時
間が適用されます。この所要時間を単一サーバのクラスタで利用するには、そのクラスタの
<restartable>を有効化しておく必要があります。
ヒント：単一サーバのクラスタ
所要時間は Terracotta 構成情報ファイルの<client-reconnect-window>要素で設定します。
<servers> ... <client-reconnect-window>120</client-reconnect-window> <!-- The reconnect window is configured in seconds, with a default value of 120. The default value is "built in," so the element does not have to be explicitly added unless a different value is required. --> ... </servers>
新しいアクティブサーバに再接続できなかったクライアントをクラスタに再接続するには、そのク
ライアントを再起動する必要があります。
最初のクライアント接続
Terracotta クライアントを初めて（または再起動後に）Terracotta サーバインスタンスへ接続する
際には、以下のプロパティに従った接続処理が実行されます。
300
# -1 == retry all configured servers eternally. l1.max.connect.retries = -1 # Must the client and server be running the same version of Terracotta? l1.connect.versionMatchCheck.enabled = true # Time (in milliseconds) before a socket connection attempt is timed out. l1.socket.connect.timeout=10000 # Time (in milliseconds; minimum 10) between attempts to connect to a server. l1.socket.reconnect.waitInterval=1000
l1.max.connect.retries に正の整数を設定すると、そのクライアントの再接続試行回数は、指定され
た整数値に制限されます。指定された回数内に接続を確立できなかった場合、そのクライアントは
処理を中断します。
プロパティの l1.max.connect.retries が使用されるのは、サーバからの構成情報の「受信後」です。
構成情報の「受信前」の接続試行回数を変更するには、クライアント側で以下のプロパティを設定
します。
-Dcom.tc.tc.config.total.timeout=5000
このプロパティは、クライアントの初期接続に要する時間を制限します。単位は「ミリ秒」です。
47.3.5 Terracottaクライアントへの自動再接続（rejoin） Enterprise Ehcache を利用している Terracotta クライアントがクラスタから強制的に切断されるこ
とを「eject」と呼びます。クラスタの HA（高可用性）関連の構成情報で設定したタイムアウト値
よりも、ネットワーク通信からの切断時間が長くなったときに、この状態が発生します。ほかにも、
クライアントマシン上で長時間の GC（ガーベジコレクション）が発生した場合も、この状態が発
生します。
構成情報を設定することで、クライアントが eject で切断したあと、クラスタに自動再接続できる
ようになります。このような再接続を「rejoin」と呼びます。ノンストップキャッシュの構成を設
定しておけば、eject による切断のあとも、クラスタは処理を継続できます。そして、clusterOnlineイベントを検出したら、rejoin による再接続の処理を開始します。
rejoin 機能を使用する際は、以下の注意が必要です。
• クライアントは、新しいメンバーとしてクラスタに再接続します。このとき、クラスタ上のキ
ャッシュとの不整合やキャッシュの無応答を防止するため、キャッシュの内容をすべてクリア
します。
• Clients cannot rejoin a new cluster; if the TSA has been restarted and its data has not been persisted, the client can never rejoin and must be restarted.
• rejoin の処理が完了する前に開始した（かつ完了していない）ノンストップキャッシュ関連の
処理は、失敗するかもしれません。このとき、NonStopCacheException が発生します。
301
• rejoin を有効化していないクライアントの JVM 上で、rejoin を有効化した Terracotta クライア
ントが動作している場合、rejoin を有効化したクライアントだけが再接続の対象になります。
この場合、rejoin を有効化していないクライアント上で動作しているアプリケーションの動作
は保証されません。
• rejoin によってクライアントが再接続すると、そのクライアント内で clusterRejoined イベント
の通知が発行されます。
rejoin の構成設定
デフォルト状態では、rejoin 機能が無効化されています。Enterprise Ehcache クライアントの rejoin機能は、クライアントの<terracottaConfig>要素の rejoin 属性で有効化します。
<terracottaConfig url="myHost:9510" rejoin="true" />
<terracottaConfig>の構成設定の詳細は、「BigMemory Max 分散構成設定ガイド」を参照してくだ
さい。
Rejoin による再接続時の例外
アプリケーションがロックを行っている場合、rejoin による再接続の処理中、または再接続完了後
に「InvalidLockAfterRejoinException」例外が発生する場合があります。この例外は、rejoin による
再接続処理が完了する前に設定したキャッシュのロックを解放するときに発生します。
確実にロックを解放するため、アプリケーションのコードでは、ロックの設定と解除（lock-unlock）を try-finally ブロック内に記述してください。
myLock.acquireLock(); try { // Do some work. } finally { myLock.unlock(); }
47.4 効果的なクライアントとサーバの再接続設定：サンプル
本来は不要なはずの接続切り替え（アクティブサーバが切り替わったと判断して、クライアントが
別サーバに接続を切り替えること）を防止するには、高可用性に関連する設定と、クラスタ環境の
設定との関係が複雑になりすぎないように注意する必要があります。環境に合わない設定は、不要
な接続切り替えの原因になります。
一般的に、「L1-L2（クライアントとサーバ間）」のヘルスチェッカーのタイムアウトと、「L2-L2（サーバとサーバ間）」のヘルスチェッカーのタイムアウト値の関係は、以下の不等式で表現でき
ます。
302
L2-L2 HealthCheck + Election Time < L1-L2 HealthCheck < L2-L2 HealthCheck + Election Time + Client Reconnect Window
このような値を設定しておけば、クライアント再接続の所要時間の計測が始まる前に、クラスタの
L1（クライアント）のサーバが切り替わる現象を防止できます。また、所要時間の計測を開始する
前の状態（つまり、元のアクティブ L2 が機能している状態）でのサーバ切り替えも防止できます。
アクティブサーバ選出時間とクライアント再接続時間は、Terracotta 構成情報ファイルで設定しま
す。これらのデフォルト値は、それぞれ 5 秒と 120 秒です。
例えば、「L2-L2」のヘルスチェッカーが 55 秒で障害と判断した場合、クラスタのミラーL2 への
切り替えは 180 秒後になります（55＋5＋120）。「L1-L2」のヘルスチェッカーが 180 秒以上経過
してから障害と判断した場合、再接続時間が完全に経過し終えてからでないとクライアントは再接
続を試行しません。
「L1-L2」のヘルスチェッカーが 60 秒未満で障害と判断した場合（つまり、「L2-L2」ヘルスチェ
ッカーの期間＋サーバ選出時間）、クライアントは、サーバの障害の判断が下される前にアクティ
ブ L2 からの接続切り替えを行います。この状態でサーバ選出が実行され、現在のアクティブ L2 が
そのままアクティブ L2 になった場合、すでに接続切り替えを終えた L1 は、接続が遮断された状態
になります。
Terracotta 3.6.1 以降は、「L1-L2」ヘルスチェッカーに対して有効な時間が設定されていることを、
サーバ起動時に確認するようになりました。無効な値が設定されている場合は、対処方法を示す警
告が出力されます。
47.5 配備済み環境の可用性のテスト
このセクションでは、障害に強いクラスタの設計と、そのテスト方法を紹介します。ここで紹介す
る設定はテスト済みで、特定の環境では効果的であることが確認されています。しかし、実際の業
務では、システムの負荷などの要因が複雑に関連してきます。したがって、実際の環境を利用した
再テストが必要不可欠です。
47.5.1 ネットワークの可用性のテスト Terracotta のアクティブサーバとミラーサーバを利用した構成の優位性を活かすには、適切なネッ
トワークの構築が不可欠です。障害発生時に Terracotta クライアント（L1）とサーバインスタンス
（L2）が正しく動作してスプリットブレインを防止するためにも、適切なネットワーク設定が重要
です。障害の種類が、ネットワーク、マシン、あるいは他の要素によるものだったとしても、同じ
ことがいえます。
このセクションでは、Terracotta のフェイルオーバの仕組みが正しく動作するネットワーク構成の
概要を 2 つ紹介します。ほかのネットワーク構成でも Terracotta のフェイルオーバは正しく機能し
303
ますが、このドキュメントで紹介する構成は十分にテストされています。もちろんサポート対象と
なっています。
47.5.2 配備環境の構成：冗長性のないネットワーク（シンプル）
説明
これは最もシンプルなネットワーク構成です。このネットワークは冗長性を設けていません。した
がって、ネットワークで障害が発生すると、クラスタの一部または全体が機能を停止する可能性が
あります。Terracotta ソフトウェアが、フェイルオーバに関連するすべての処理を実行します。
この図の IP アドレスは単なるサンプルですが、L1（L1a と L1b）と L2（TCserverA と TCserverB）が別のサブネットに登録されていることを示しています。環境を構築する際は、実際のネットワー
ク構成に合わせたアドレスを割り当ててください。単一スイッチのネットワークなので、このスイ
ッチが壊れるとネットワーク全体が止まります。
追加の構成
この構成の場合、追加のネットワークやオペレーティングシステムの構成は不要です。各マシンは、
適切なネットワーク構成情報（IP アドレス、サブネットマスク、ゲートウェイ、DNS、NTP、ホス
ト名）を設定したうえで、ネットワークに接続します。
テスト計画：ネットワーク障害テスト（冗長性のないネットワーク）
304
正しく構成されていることを確認するには、以下のテストを実行し、すべての障害シナリオにおけ
る動作が期待どおりであることを確認してください。
テスト ID 障害内容 期待される結果
FS1 L1a を切断（断線またはシステ
ムダウン） L1b だけを使用して、クラスタが正常に稼働
FS2 L1b を切断（断線またはシステ
ムダウン） L1a だけを使用して、クラスタが正常に稼働
FS3 L1a と L1b を切断 クラスタの機能が停止
FS4 スイッチを切断 クラスタの機能が停止
FS5 アクティブ L2 を切断（断線ま
たはシステムダウン） ミラーL2 が新しいアクティブ L2 に昇格。すべての
L1 は、新しいアクティブ L2 にフェイルオーバ
FS6 ミラーL2 を切断 Terracotta による冗長性なしで、クラスタが正常に
稼働
FS7 TCserverA と TCserverB を切断 クラスタの機能が停止
テスト計画：ネットワーク動作確認テスト（冗長性のないネットワーク）
ネットワークを構築したら、シンプルな ping テストを利用して構成のテストを行います。
テスト ID ホスト 動作 期待される結果
NT1 すべて すべてのホストに対する ping ping 成功
NT2 すべて ping の連続実行中にネットワー
クケーブルを切断（抜く） 再接続するまで ping が失敗する
NT3 スイッチ リロード リロードが完了して接続が再確立する
まで ping が停止
305
47.5.3 配備環境の構成：完全な冗長化
説明
これは完全に冗長化されたネットワーク構成です。Terracotta、スイッチ、およびオペレーティン
グシステムによってフェイルオーバがサポートされています。このシナリオでは、複数の障害が発
生した場合でも、クラスタが正常稼働する可能性があります。
この図の IP アドレス構成は単なるサンプルですが、L1（L1a と L1b）と L2（TCserverA と
TCserverB）を、それぞれ異なるサブネットに登録できることを示しています。環境を構築する際
は、実際のネットワーク構成に合わせたアドレスを割り当ててください。すべてを同一サブネット
内に配置する場合は、VRRP/HSRP が不要です。この場合でも、1 つの VLAN（例：VLAN 1）を構
成し、そこにすべての TC クラスタマシンを登録する必要があります。
この図の構成では、スイッチが 2 つ使用されています。これらは、冗長性を確保するためにトラン
クリンクで接続されています。こうして VRRP（仮想ルータ冗長プロトコル）または HSRP を実装
することで、スイッチの障害に備えます。さらに、すべてのサーバは、プライマリおよびセカンダ
リの両ネットワークに接続するよう構成されています。これらはオペレーティングシステムが制御
します。一方の接続で NIC 障害や接続障害が発生した場合、オペレーティングシステムはフェイル
306
オーバー機能によって即座にバックアップ接続を有効化します。システム（L1 や L2）の Java プロ
セスには影響しません（再起動も不要です）。
Terracotta のフェイルオーバーが機能する仕組みは、前述の「シンプル」なネットワーク構成と全
く同じです。ただし、1 つのホストに搭載された 2 つの NIC の両方に障害が発生しないと、
Terracotta ソフトウェアのフェイルオーバーは実行されません（不要です）。
追加の構成
• スイッチ：各サブネットに対して冗長なゲートウェイを提供するため、スイッチには VRRP ま
たは HSRP の実装が必要です。また、それぞれのスイッチどうしを複数の経路でトランクリン
ク接続しておく必要があります。単一の経路でしか接続しないと、その経路に問題が生じたと
き、2 つの仮想ルータが分離してしまいます。
• オペレーティングシステム：各ホストには複数のボンディングネットワークインターフェース
を用意し、2 つの異なるスイッチに接続します。Linuxの場合は「モード 1」を設定してくださ
い。Linuxのチャンネルボンディングの詳細は、RedHat Linux Reference Guideを参照してくだ
さい。実装されたVRRPやHSRPが、リカバリー後の再接続にかかる時間がどれくらいになるの
か、特に注意してください。スイッチのLANトラフィック通信準備が完了する前に、NICがス
イッチの接続を切り替えてしまう場合もあります。各ボンディングの構成情報を利用して設定
してください。
テスト計画：ネットワーク障害テスト（冗長性のあるネットワーク）
以下のテストは、「ネットワーク障害テスト（冗長性のないネットワーク）」のテスト計画に追加
して実施してください。これらのテストを使用して、ネットワーク構成が正しく設定されているこ
とを確認します。
テスト ID 障害内容 期待される結果
FS8 プライマリネットワーク接
続の一部を切断 スタンバイリンクにフェイルオーバ
FS9 プライマリリンク全体を切
断 すべてのノードが、スタンバイリンクにフェイルオーバ
FS10 一方のスイッチを切断 正常なスイッチが VRRP アドレスを保持。必要であれ
ば、NIC がフェイルオーバ
FS11 L1 のいずれかを切断（断線
またはシステムダウン） 正常な L1 を使用して、クラスタが正常に稼働
FS12 アクティブ L2 を切断 ミラーL2 が新しいアクティブ L2 に昇格。すべての L1は、新しいアクティブ L2 にフェイルオーバ
FS13 ミラーL2 を切断 Terracotta による冗長性なしで、クラスタが正常に稼働
307
FS14 両方のスイッチを切断 クラスタの機能が停止
FS15 スイッチのトランク接続の
一方を切断 トランク機能による冗長性なしで、クラスタが正常に稼
働
FS16 トランク接続の両方を切断 クラスタの機能が停止（ただし、VRRP または HSRP の
実装によって結果が異なります）
FS17 L1 の両方を切断 クラスタの機能が停止
FS18 L2 の両方を切断 クラスタの機能が停止
テスト計画：ネットワーク動作確認テスト（冗長性のあるネットワーク）
ネットワークを構築したら、シンプルな ping テストと障害テストを実施することで動作確認テス
トが出来ます。
ネットワーク動作確認テストのテストケースは以下のとおりです。
テスト ID ホスト 動作 期待される結果
NT4 任意 すべてのホストに対す
る ping ping 成功
NT5 任意 任意のホストに対する
ping の連続実行中に、
プライマリ接続を切断
ネットワーク接続障害を一切起こさずに、スタ
ンバイリンクにフェイルオーバ
NT6 任意 任意のホストに対する
ping の連続実行中に、
スタンバイリンクを切
断
影響なし
NT7 アクティ
ブ L2 ネットワーク接続の両
方を切断 ミラーL2 がアクティブに昇格。すべての L1は、新しいアクティブ L2 にフェイルオーバ
NT8 ミラーL2 ネットワーク接続の両
方を切断 影響なし
NT9 スイッチ
A リロード 各ノードが接続の障害（ダウン）を検出し、ス
タンバイリンクにフェイルオーバ。VRRP 切り替
えが発生した場合は短時間のネットワーク遮断
が発生
NT10 スイッチB
リロード VRRP 切り替えが発生した場合は短時間のネット
ワーク遮断が発生
NT11 スイッチ 一方のトランク接続を
切断 影響なし
47.5.4 Terracottaクラスタのテスト ここで紹介するテストは、すべてのネットワーク動作確認テストに合格してから実行してください。
308
テスト計画：アクティブ L2 システムの障害テスト（ミラーへの切り替え確認）
ミラーへの切り替え確認のテストケースは以下のとおりです。
テスト ID テスト セットアップ 手順 期待される結果
TAL1 アクティブ
L2 の切断
（kill によ
る強制終
了）
L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステ
ムを正常稼働させ、
通信可能な状態にす
る。
1.アプリケーションを実
行する。 2.L2a（アクテ
ィブ）を「kill -9 <TerracottaPID>」で強
制終了する。
L2b（ミラー）がア
クティブに昇格。
それまでの処理は
継続。フェイルオ
ーバ時も TPS は低
下しない。
TAL2 アクティブ
L2 の切断
（正常な手
順でシャッ
トダウン）
L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステ
ムを正常稼働させ、
通信可能な状態にす
る。
1.アプリケーションを実
行する。2.L2a（アクテ
ィブ）を「~/bin/stop-tc-server.sh」で終了す
る。
L2b（ミラー）がア
クティブに昇格。
それまでの処理は
継続。フェイルオ
ーバ時も TPS は低
下しない。
TAL3 アクティブ
L2 の切断
（電源の切
断）
L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステ
ムを正常稼働させ、
通信可能な状態にす
る。
1.アプリケーションを実
行する。2.L2a（アクテ
ィブ）の電源を落と
す。
L2b（ミラー）がア
クティブに昇格。
それまでの処理は
継続。フェイルオ
ーバ時も TPS は低
下しない。
TAL4 アクティブ
L2 の切断
（再起動）
L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステ
ムを正常稼働させ、
通信可能な状態にす
る。
1.アプリケーションを実
行する。2.L2a（アクテ
ィブ）を再起動する。
L2b（ミラー）がア
クティブに昇格。
それまでの処理は
継続。フェイルオ
ーバ時も TPS は低
下しない。
TAL5 アクティブ
L2 の切断
（電源ケー
ブルを抜
く）
L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステ
ムを正常稼働させ、
通信可能な状態にす
る。
1.アプリケーションを実
行する。2.L2a（アクテ
ィブ）の電源ケーブル
を抜く。
L2b（ミラー）がア
クティブに昇格。
それまでの処理は
継続。フェイルオ
ーバ時も TPS は低
下しない。
テスト計画：ミラーL2 システムの障害テスト
システム障害テストでは、システムの 1 つで障害が発生しても可用性を保つことを確認します。こ
のセクションでは、Terracotta ミラーサーバで障害が発生した場合のテストの概要を紹介します。
Terracotta ミラーサーバの障害テスト計画で実行するテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
309
TPL1 ミラーL2 の切
断（kill による
強制終了）
L2a をアクティブ
に、L2b をミラー
に設定する。すべ
てのシステムを正
常稼働させ、通信
可能な状態にす
る。
1.アプリケーションを実
行する。2.L2b（ミラ
ー）を「kill -9」で強制
終了する。
データディレクトリの内
容がクリアされる。L2bが再起動したら、アクテ
ィブサーバとの同期が始
まる（同期状態にな
る）。
TPL2 ミラーL2 の切
断（正常終了
とデータのク
リア）
L2a をアクティブ
に、L2b をミラー
に設定する。すべ
てのシステムを正
常稼働させ、通信
可能な状態にす
る。
1.アプリケーションを実
行する。2.L2b（ミラ
ー）を「~/bin/stop-tc-server.sh」で終了す
る。
データディレクトリの内
容がクリアされる。L2bが再起動したら、アクテ
ィブサーバとの同期が始
まる（同期状態にな
る）。
TPL3 ミラーL2 の切
断（電源の切
断）
L2a をアクティブ
に、L2b をミラー
に設定する。すべ
てのシステムを正
常稼働させ、通信
可能な状態にす
る。
1.アプリケーションを実
行する。2.L2b（アクテ
ィブ）の電源を落と
す。
データディレクトリの内
容がクリアされる。L2bが再起動したら、アクテ
ィブサーバとの同期が始
まる（同期状態にな
る）。
TPL4 ミラーL2 の切
断（再起動） L2a をアクティブ
に、L2b をミラー
に設定する。すべ
てのシステムを正
常稼働させ、通信
可能な状態にす
る。
1.アプリケーションを実
行する。2.L2b（ミラ
ー）を再起動する。
データディレクトリの内
容がクリアされる。L2bが再起動したら、アクテ
ィブサーバとの同期が始
まる（同期状態にな
る）。
TPL5 ミラーL2 の切
断（電源ケー
ブルを抜く）
L2a をアクティブ
に、L2b をミラー
に設定する。すべ
てのシステムを正
常稼働させ、通信
可能な状態にす
る。
1.アプリケーションを実
行する。2.L2b（ミラ
ー）の電源ケーブルを
抜く。
データディレクトリの内
容がクリアされる。L2bが再起動したら、アクテ
ィブサーバとの同期が始
まる（同期状態にな
る）。
テスト計画：フェイルオーバとフェイルバックのテスト
このセクションでは、Terracotta ミラーサーバへのフェイルオーバとフェイルバックにおけるクラ
スタの性能を確認するテストの概要を紹介します。
フェイルオーバとフェイルバックのテスト計画で実行するテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
TFO1 フェイルオ L2a をアクテ 1.アプリケーションを実行す 最初のフェイルオーバ
310
ーバ/フェ
イルバック ィブに、L2bをミラーに設
定する。すべ
てのシステム
を正常稼働さ
せ、通信可能
な状態にす
る。
る。2.L2a（アクティブ）を
「kill -9」または stop-tc-server で終了する。3.L2b が
アクティブに昇格してから、
start-tc-server で L2a を起動
する（L2a がミラーとして起
動します）。4.L2b（アクテ
ィブ）を「kill -9」または
stop-tc-server で終了する
（L2a が再びアクティブにな
ります）。
（L2a -> L2b）で、トラン
ザクションは継続する。
L2a の Terracotta サーバ
が再起動したとき、L2aのデータはクリアされ、
ミラーとして起動する。2回目のフェイルオーバ
（L2b -> L2a）では、L2aがトランザクションを継
続する。
テスト計画：スイッチ切断のテスト
このテストは、冗長性のあるネットワークだけが対象です。
このセクションでは、冗長性のあるネットワークでスイッチ（ハブ）が切断され状況でもサービス
が中断しないことを確認するためのテストの概要を紹介します。
1 つのスイッチで障害が発生した状況のテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
TSL1 1 つのスイ
ッチの切断 2 つのスイッチを利用し
た、冗長性のあるネットワ
ークを構成する。L2a をア
クティブに、L2b をミラー
に設定する。すべてのシス
テムを正常稼働させ、通信
可能な状態にする。
1.アプリケーション
を実行する。2.スイ
ッチの電源を落と
す、または電源ケー
ブルを抜く。
すべてのネットワーク
トラフィックが、遮断
されることなく透過的
にもう 1 つのスイッ
チへ移行する。
テスト計画：ネットワーク接続の切断
このセクションでは、ネットワーク接続が切断された状況に対するテストの概要を紹介します。
ネットワーク接続が切断された状況のテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
TNL1 NIC ケーブ
ルの切断
（アクティ
ブ）
L2a をアクティブに、L2bをミラーに設定する。すべ
てのシステムを正常稼働さ
せ、通信可能な状態にす
る。
1.アプリケーショ
ンを実行する。
2.L2a のネットワ
ークケーブルを外
す。
すべてのネットワーク
トラフィックが、遮断
されることなく透過的
に L2b へ移行する。
TNL2 NIC ケーブ
ルの切断
（ミラー）
L2a をアクティブに、L2bをミラーに設定する。すべ
てのシステムを正常稼働さ
せ、通信可能な状態にす
1.アプリケーショ
ンを実行する。
2.L2b のネットワ
ークケーブルを外
クラスタの動作は何も
影響を受けない。
311
る。 す。
テスト計画： Terracotta クラスタの障害
このセクションでは、Terracotta クラスタ上で障害が発生した状況でも、オペレーションを正しく
処理できることを確認するためのテストの概要を紹介します。
Terracotta クラスタの障害テスト計画で実行するテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
TF1 プロセス障
害の回復 L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステムを
正常稼働させ、通信可能
な状態にする。
1.アプリケーションを実
行する。 2.L1 と L2 の
すべてを落とす。 3.すべての L2 を開始し、そ
れからすべての L1 を開
始する。
クラスタが機能し始
め、トランザクショ
ンの処理を再開す
る。
TF2 サーバ回復
の処理 L2a をアクティブに、
L2b をミラーに設定す
る。すべてのシステムを
正常稼働させ、通信可能
な状態にする。
1.アプリケーションを実
行する。2.すべてのマシ
ンの電源を落とす。3.すべての L2 を開始し、そ
れからすべての L1 を開
始する。
すべてのサーバが機
能し始めたら、アプ
リケーションを実行
できるようになる。
クライアント障害のテスト
このセクションでは、Terracotta クライアントで障害が発生した状況でも、オペレーションを正し
く処理できることを確認するためのテストの概要を紹介します。
Terracotta クライアントの障害テスト計画で実行するテストケースは以下のとおりです。
テスト
ID テスト セットアップ 手順 期待される結果
TCF1 L1 の障害 L2a をアクティブに、
L2b をミラーに設定す
る。2 L1s L1-A and L1-Bすべてのシステムを正常
稼働させ、通信可能な状
態にする。
1.アプリケーショ
ンを実行する。
2.L1a を「kill -9」で強制終了す
る。
L1b が、すべての通信トラ
フィックを処理する。L1 の
フェイルオーバ発生時、い
くつかのトランザクション
でタイムアウトが発生する
可能性がある。
312
48 クラスタのセキュリティ
48.1 はじめに
Terracotta のエンタープライズ版キットは、Terracotta サーバへのアクセスを制御するための標準
認証メソッドを提供します。これらのメソッドを有効にすると、JMX 接続を続行するには、
Terracotta サーバが認証情報を要求するようになります。
サーバのセキュリティは、以下のオプションから一つを選択します。
• SSL を基盤としたセキュリティ：すべてのノード（クライアントを含む）について認証を行な
います。暗号化された接続により、クラスタ全体へのアクセスを確保します。ロールベースの
認証も含みます。
• LDAP ベースの認証：所属する組織の認証データベースを使用し、Terracotta サーバへのアク
セスを確保します。
• JMX ベースの認証：シンプルな認証スキームを提供し、Terracotta サーバへのアクセスを保護
します。
サーバに対し、「認証情報をスクリプトに渡さずに」 Terracotta スクリプトを使用することはでき
ません。
48.2 SSLを使ったセキュリティの構成設定
セキュア･ソケット･レイヤー（SSL）暗号化通信や証明書を使った認証によって Terracotta クラス
タのエンタープライズ版へアクセスする場合は、「セキュリティに関する詳細」を参照してくださ
い。
48.3 LDAP (JAAS経由）を使ったセキュリティの構成設定
ライトウェイト・ディレクトリ・アクセス・プロトコル（LDAP）によるセキュリティは JAAS を経
由し、Java 1.6 が必要です。古いバージョンの Java を使用しても Terracotta サーバの運用に支障を
きたすことはありませんが、セキュリティは有効になりません。
LDAP を使ったセキュリティの構成設定は次の手順で行ないます。
1. 以下の構成情報を.java.login.config ファイルに保存します。
Terracotta { com.sun.security.auth.module.LdapLoginModule REQUIRED java.naming.security.authentication="simple" userProvider="ldap://orgstage:389"
313
authIdentity="uid={USERNAME},ou=People,dc=terracotta,dc=org" authzIdentity=controlRole useSSL=false bindDn="cn=Manager" bindCredential="****" bindAuthenticationType="simple" debug=true; };
userProvider（LDAP サーバ）、authIdentity（ユーザーID）、および bindCredential（暗号化
されたパスワード）の値を編集し、ご使用の環境の値と合わせます。
2. .java.login.config ファイルを Java プロパティの user.home で指定したディレクトリに保存しま
す。
3. 以下の構成情報を Terracotta 構成ファイルの各<server>ブロックに追加します。
<server host="myHost" name="myServer"> ... <authentication> <mode> <login-config-name>Terracotta</login-config-name> </mode> </authentication> ... </server>
4. Terracotta サーバを起動し、「INFO - Credentials: loginConfig[Terracotta]」という情報を含む
ログメッセージを検索します。LDAP によるセキュリティが有効であることを確認します。
セキュリティが正しくセットアップされていなくても、Terracotta サーバを起動することはできま
す。ただし、シャットダウンスクリプト（stop-tc-server によるサーバのシャットダウンができな
くなる可能性があります。
注意：正しくないセットアップ
48.4 JMX認証を使ったセキュリティの構成設定
Terracotta では、JMX 認証の標準的な Java のセキュリティ機構を使用することもできます。この場
合、正しい権限セットを備えた.access ファイルと.password ファイルを生成する必要があります。
314
JDK 1.5 以上の場合、これらのファイルはデフォルトで$JAVA_HOME/jre/lib/management にありま
す。
JMX 認証を使ったセキュリティの構成設定は次の手順で行なってください。
1. 対象サーバへのアクセスに使用するユーザー名とパスワードが、JMX パスワードファイルの
jmxremote.password にあることを確認します。また、使用するロールが JMX アクセスファイ
ルの jmxremote.access にあることを確認します。
2. jmxremote.access と jmxremote.password の両方が規定の場所
（$JAVA_HOME/jre/lib/management）にある場合、以下の構成情報を Terracotta 構成ファイ
ルの各<server>ブロックに追加します。
<server host="myHost" name="myServer"> ... <authentication /> ... </server>
3. jmxremote.password が規定の場所にない場合は、以下の構成情報を Terracotta 構成ファイル
の各<server>ブロックに追加します。
<server host="myHost" name="myServer"> ... <authentication> <mode> <password-file>/path/to/jmx.password</password-file> </mode> </authentication> ... </server>
4. jmxremote.access が規定の場所にない場合は、以下の構成情報を Terracotta 構成ファイルの各
<server>ブロックに追加します。
<server host="myHost" name="myServer"> ... <authentication> <mode> <password-file>/path/to/jmxremote.password</password-file> </mode> <access-file>/path/to/jmxremote.access</access-file> </authentication>
315
... </server>
「File Not Found」エラー
サーバ起動時に JMX パスワードファイルが見つからない場合、パスワードファイルが存在しないと
いう内容のエラーがログに記録されます。
48.5 認証を必要とするサーバに対するスクリプト使用
セキュリティで保護された Terracotta サーバにアクセスするスクリプトは、正しいログイン証明書
を使用する必要があります。セキュリティで保護されたサーバに対し、backup-data や server-stat といった Terracotta スクリプトを実行する場合、-u（続いてユーザー名）オプションと-w（続
いてパスワード）オプションを使用して証明書を渡します。
例えば、「Server1」のユーザー名が「user1」でパスワードが「password」の場合、以下を入力し
て, server-stat を実行します。
UNIX/LINUX
[PROMPT]${TERRACOTTA_HOME}/bin/server-stat.sh -s Server1 -u user1 -w password
MICROSOFT WINDOWS
[PROMPT]%TERRACOTTA_HOME%\bin\server-stat.bat -s Server1 -u user1 -w password
48.6 サーバのセキュリティを拡張する
JMX メッセージは暗号化されていないため、待ち受け中のクライアントから有効な認証情報が提供
されると、サーバ認証はセキュアなメッセージ送信を提供しません。ログイン以外の方法も利用し
てセキュリティを強化する必要がある場合は、以下の方法を考慮してください。
• Terracotta サーバを、プライベートなネットワーク上のセキュリティ保護されている場所に置
く。
• リモートクエリのアクセスを、SSH や stunnel が提供する暗号化通信に制限する。
• パブリックまたは外部のネットワークを使用している場合は、クラスタ内のすべての通信に対
して VPN を使う。
• Ehcache を使用している場合は、独自の暗号化機能や復号化機能を実装したキャッシュをキャ
ッシュ Decorator に追加する。
316
49 Terracottaクラスタのセキュリティ設定
49.1 はじめに
認証、承認、暗号化を使ったセキュリティにより、Terracotta クラスタを保護することができます。
ビルトインの認証および承認機能は、外部ディレクトリサービスに対するサポートと同じように利
用可能です。さらに、証明書を使ったセキュア・ソケット・レイヤー（SSL）方式の暗号化機能に
より、ノード間の通信もセキュリティで保護できます。
Terracotta クラスタにおけるセキュリティは、サーバ・サーバ間の接続とクライアント・サーバ間
の接続の両方を保護します。セキュリティで保護されたクラスタ内のすべての接続が保護下にある
必要があります。つまり、セキュリティで保護されていない接続は承認されません。セキュリティ
は、「Terracotta 管理サーバ」を含むクラスタ全体で有効化されていなくてはならないのです。特
定のノードに対してのみセキュリティを有効化するということはできません。
49.2 概要
セキュリティは、Terracotta キットが提供する Terracotta の構成情報やツール、Java の標準ツール、
公開鍵インフラストラクチャー（標準である X.509 デジタル証明書使用）を使ってセットアップし
ます。
49.2.1 セキュリティ関連のファイル Terracotta サーバはそれぞれ、以下の種類のファイルを活用してセキュリティを実装します。
• Java キーストア：サーバの秘密鍵および公開鍵の証明書を保有しています。キーストアまたは
証明書のエントリーのパスワードによって保護されています。
• トラストストア：証明書の公開鍵のみを保有しているキーストアです。認証局（CA）発行の
証明書ではなく、自己署名証明書のみを使用している場合に必要です。
• キーチェーン：サーバのキーストアや他のファイルへのパスワードを格納します。Terracottaのキーチェーンファイルを作成、管理するツールは Terracotta のキットに含まれています。
• 承認ファイル：パスワードで保護されたユーザーアカウントと、サーバおよびサーバに接続す
るクライアントでのロールを備えた「.ini」ファイルです。 「Microsoft Active Directory と LDAP の標準的な認証および承認機能」をご利用できます。
デフォルトで${JAVA_HOME}java.home/lib/securityにあるJavaの標準cacertsファイルは、JDKに含ま
れているCAのルート証明書のためのシステム全体のリポジトリです。これらの証明書は、証明書チ
ェーンの一部として役割を担います。Javaのドキュメントでは、デフォルトのパスワードとファイ
ルパーミッションを変更することでcacertsファイルを保護するよう推奨しています。
317
ヒント：Secure cacerts ファイルをセキュリティ保護しましょう。
各 Terracotta クライアントには、キーチェーンファイルが存在します。キーチェーンファイルは、
サーバへのアクセス時の認証に使用するパスワードを格納します。
すべてのファイルは起動時に読み取りが行なわれるため、起動後の変更を読み取りません。起動後
の変更を読み取るには、クラスタを再起動してください。
49.2.2 プロセス図 下図は、クラスタとの最初の接続時におけるセキュリティ情報の流れとその情報の起点と上述のフ
ァイルの関連性を示しています。
Terracotta サーバから見た場合、セキュリティチェックが行なわれるのは、起動時およびクラスタ
内の他のノードとの接続時となります。
318
1. 「server1」が起動プロセスを完了するには、起動時にコンソールからパスワードを直接入力
する必要があります。手動入力を避けたい場合、パスワードは「ファイルから読み取る」こと
も可能です。
2. 「server2」からの接続リクエストにより、SSL を使ってセキュリティ保護された接続の確立プ
ロセスが開始されます。
3. 「server1」が格納してある認証情報を使って「server2」の認証を行ないます。この認証情報
は、「server2」を認証するロールとも関連付けられています。また、このプロセスは対称型
のため、「server2」も「server1」の認証および承認を行ないます。
4. Terracotta クライアントからの接続リクエストにより、SSL を使ってセキュリティ保護された
接続の確立プロセスが開始されます。
5. 「server1」は格納してある認証情報および関連付けされたロールを使ってクライアントの認
証と承認を行ないます。クライアントは活動期間中にクラスタ内のあらゆるアクティブサーバ
と通信する可能性があるため、すべてのアクティブサーバと認証を行なえる必要があります。
アクティブサーバは常にミラーサーバへとフェイルオーバする可能性があるため、クライアン
トはクラスタ内のすべてのサーバに対して認証を行なえるべきです。
Terracotta クライアントから見た場合、セキュリティチェックが行なわれるのは、クライアントが
クラスタ内のアクティブサーバに接続しようとした時です。
1. クライアントは、ユーザー名を含むサーバ URI を使用します。
典型的な（セキュリティ保護されていない）URI に<server-address>:<port>があります。セキ
ュリティ保護された接続を確立する URI の形式は<client-username>@<server-address>:<port>です。
2. これにより、サーバとの接続は、SSL を使ってセキュリティ保護された状態で確立します。
3. クライアントは、ローカルのキーチェーンファイルから取得したパスワードを送信します。こ
のパスワードはクライアントのユーザー名と関連付けらます。
49.2.3 構成情報のサンプル 以下の構成情報の抜粋は、上図のサーバにおけるセキュリティのセットアップ例を示しています。
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"> ... <servers secure="true"> <server host="172.16.254.1" name="server1"> ... <security> <ssl>
319
<certificate>jks:server1alias@/the/path/keystore-file.jks</certificate> </ssl> <keychain> <class>com.terracotta.management.keychain.FileStoreKeyChain</class> <url>file:///%(user.dir)/server1keychain.tkc</url> </keychain> <auth> <realm>com.tc.net.core.security.ShiroIniRealm</realm> <url>file:///%(user.dir)/myShiroFile.ini</url> <user>server1username</user> </auth> </security> ... </server> <server host="172.16.254.2" name="server2"> ... <security> <ssl> <certificate>jks:server2alias@/the/path/keystore-file.jks</certificate> </ssl> <keychain> <class>com.terracotta.management.keychain.FileStoreKeyChain</class> <url>file:///%(user.dir)/server2keychain.tkc</url> </keychain> <auth> <realm>com.tc.net.core.security.ShiroIniRealm</realm> <url>file:///%(user.dir)/myShiroFile.ini</url> <user>server2username</user> </auth> </security> ... </server> ... </servers> ... </tc:tc-config>
以上のサンプルの構成情報の要素については、「構成情報の設定のセクション」を参照してくださ
い。
320
49.3 サーバのセキュリティのセットアップ
Terracotta サーバのセキュリティをセットアップするためには、以降の手順に従ってください。
注意：下のサンプルにあるスクリプト名は*NIX システムを対象としたものです。同じ場所に、対
応する Microsoft Windows 用のスクリプトもあります。以下において、拡張子「.sh」を「.bat」に
置換し、パスの区切り文字を適切に変換してください。
49.3.1 サーバ証明書を作成し、キーストアに追加する Terracotta サーバにはそれぞれ、デジタル証明書と関連する秘密鍵を保有するキーストアファイル
が必要です。所属される組織には、デジタル証明書や証明書チェーンの作成および使用、CA が証
明した証明書の使用などについて、独自のポリシーや手続きがあるかもしれません。
このドキュメントは、自己署名証明書を使用する場合を想定しています。自己署名証明書とは、公
的な CA によるデジタル署名を持たない証明書のことです。自己署名証明書は第三者機関による身
分証明を行なっていないため、CA に署名された証明書と比べて安全性が劣ることがあります。と
はいえ、自己署名証明書の使用自体は可能です。デジタル証明書の使用について、所属される組織
のポリシーや手続きを遵守する場合は、このドキュメントで説明する手順にしたがってください。
Terracotta サーバで使用する場合、証明書やそのキーストアについては、以下の条件を満たす必要
があります。
• キーストアは JDK 1.6 以上と互換性のある Java キーストア（JKS）でなくてはなりません。
• 証明書は、「サーバのセキュリティの構成設定」の<certificate>要素の値で指定したエイリア
スと関連付けてください。
• 識別名のコモンネーム（CN）の項目には、「サーバのセキュリティの構成設定」で設定した
サーバのホスト名を指定してください。
• 証明書を保護するパスワードはキーストアのメインパスワードに合わせてください。つまり、
ストアのパスワードとキーのパスワードは同じでなくてはなりません。
• （信頼できる CA が署名した証明書ではなく）自己署名証明書を使う場合は、「カスタムのト
ラストストア」を作成し、公開鍵を格納してください。
キーストアはあるものの、サーバ証明書がそのキーストアに格納されていない場合はすぐに格納し
てください。キーストア自体がまだ存在しない場合は、「キーストアを作成」してください。
Java の「鍵と証明書の管理ツール（Keytool）」を使った自己署名証明書の作成
テスト目的または実際に「自己署名証明書」を使用する場合、Java の keytool コマンドを使って公
開鍵と秘密鍵のペアを作成します。このコマンドはキーストアやトラストストアを作成する際にも
使用します。ただし、キーストアとトラストストアには論理的な違いしか存在しないため、keytoolはトラストストアを「キーストア」と呼びます。
321
「cacerts」を使わない場合、デフォルトの Java のトラストストアおよびカスタムのトラストスト
アはシステムプロパティの javax.net.ssl.trustStore で指定してください。この場合、
javax.net.ssl.trustStorePassword でカスタムのトラストストアのデフォルトパスワードをリセットで
きます。
カスタムのトラストストアを指定する
上の構成情報の設定サンプルにある「server1」というサーバの公開鍵と秘密鍵（証明書を含む）と
キーストアファイルの作成方法を以下に示します。
keytool -genkey -keystore keystore-file.jks -dname "CN=172.16.254.1, OU=Terracotta, O=SAG, L=San Francisco, S=California, C=US" -alias server1alias -storepass server1pass -keypass server1pass
-storepass と-keypass に渡した値が同じであることに注目してください。また、コモンネーム（CN）
を指定する項目の内容とサーバのホスト名は同じものにしてください。ホスト名はサーバの構成情
報で入力した値と同じものです。このホスト名には、IP アドレスや解決可能なドメイン名を指定し
ます。-dname オプションを省略すると、キーストアにサーバのエントリーを作成する時に一連の
ID プロンプト（X.500 標準規格を基にした識別名の項目）が表示されます。CN プロンプトは以下
のように表示されます。
What is your first and last name? [Unknown]:
他にも、-keyalg（暗号アルゴリズム。デフォルトは DSA）や-validity（証明書が期限切れになるま
での日数。デフォルトは 90）などの keytool のオプションについて考慮します。これらのオプショ
ンは、構成の環境やセキュリティ要件に左右されます。keytool の使用については、JDK のドキュ
メントを参照してください。
それぞれの Terracotta サーバにキーストアとエントリーを作成します。
証明書のエクスポートとインポート
各サーバのトラストストアに、他のサーバの公開鍵の証明書のコピーを格納しておくべきです。
上の構成情報の設定サンプルにある「server1」というサーバの証明書をエクスポートする方法を以
下に示します。
keytool -export -alias server1alias -keystore keystore-file.jks -file server1SelfSignedCert.cert
この「cert」ファイルを使うと、「server1」の証明書を他のサーバのトラストストアにインポート
できます。例えば、トラストストアを作成して「server1」の証明書を「server2」にインポートす
322
るには、「cert」ファイルを「server2」の作業ディレクトリにコピーし、次のコマンドを実行しま
す。
keytool -import -alias server1alias -file server1SelfSignedCert.cert -keystore truststore.jks
パスワードの入力プロンプトの後に、証明書情報が表示され、信頼するかどうかをプロンプトで確
認します。クラスタ内にある、自サーバ以外のすべてのサーバの公開鍵の証明書を持ったトラスト
ストアが全サーバに存在するようになるまで、このプロセスを繰り返します。
すべてのサーバで毎回トラストストアを作成する代わりに、全サーバの公開鍵を格納しているトラ
ストストアを一つ作成し、それを各サーバにコピーしましょう。「クライアント」.についても、同
じトラストストアを使うことができます。
ヒント：各サーバで使うトラストストアは、単一のものにしましょう。
49.3.2 サーバのキーチェーンをセットアップする キーストアと各証明書エントリーは、サーバのキーチェーンファイルに格納されているパスワード
で保護されています。キーチェーンの場所は、「サーバのセキュリティの構成設定」にある
<keychain>要素の下の<url>要素の値で指定します。キーチェーンファイルは、サーバ起動時にユー
ザー（プロセス所有者）のホームディレクトリ内で検索されます。
上の構成情報の設定サンプルでは、server1keychain.tkc というキーチェーンファイルが「server1」の起動時に検索されます。
キーチェーンファイルには、以下のエントリーがあるはずです。
• ローカルサーバのキーストアのエントリーに対するエントリー。
• ローカルサーバの接続先となるすべてのサーバに対するエントリー。
エントリーは、Terracotta のキットの bin ディレクトリにある keychain スクリプトを使って作成し
ます。
ローカルサーバのエントリーを作成する
ローカルサーバのキーストアのパスワードに対するエントリーを作成します。
bin/keychain.sh <keychain-file><certificate-URI>
<keychain-file>は、サーバの構成設定の<keychain>/<url>要素で指定したファイルです。また、
<certificate-URI>はサーバの構成設定の<ssl>/<certificate>要素の URI 値です。
キーチェーンファイルが存在しない場合は、-c オプションを追加して作成します。
323
bin/keychain.sh -c <keychain-file><certificate-URI>
キーチェーンファイルのパスワードのプロンプトが表示されます。その後に、URI のパスワードの
プロンプトが表示されます。URI のパスワードには、キーストア内のサーバの証明書を保護する際
に使用したパスワードを入力してください。
例えば、上の構成情報の設定サンプルの「server1」のエントリーを作成する場合は、以下のように
入力します。
bin/keychain.sh server1keychain.tkc jks:[email protected] Terracotta Management Console - Keychain Client Open the keychain by entering its master key: xxxxxxx Enter the password you wish to associate with this URL: server1pass Confirm the password to associate with this URL: server1pass Password for jks:[email protected] successfully stored
リモートサーバのエントリーを作成する
リモートサーバのエントリーは tc://<user>@<host>:<group-port>の形式になっています。<user>の値は、各サーバの構成設定の<security>/<auth>/<user>で指定します。ユーザーがプロセス所有者
として操作することとは関係ありません。<security>/<auth>/<user>の値を指定しないと、デフォ
ルトで「terracotta」というユーザー名が使用されます。
例えば、「server1」のキーチェーンに「server2」のエントリーを作成する場合は以下を使用しま
す。
bin/keychain.sh server1keychain.tkc tc://[email protected]:9530
キーチェーンファイルが存在しない場合は、-c オプションを使用します。
bin/keychain.sh -c server1keychain.tkc tc://[email protected]:9530
キーチェーンファイルのパスワードのプロンプトが表示されます。その後に、エントリーである
[email protected]:9530 のパスワードのプロンプトが表示されます。
「server1」のエントリーを「server2」のキーチェーンに追加してください。<
bin/keychain.sh server2keychain.tkc tc://[email protected]:9530
49.3.3 認証および承認をセットアップする セキュリティで保護されたサーバに接続するクライアントやサーバには、認証情報（ユーザー名と
パスワード）とロール（承認）の設定が必要になります。このセクションでは、「.ini」ファイルを
使った認証と承認について説明します。「.ini」ファイルではなく、LDAP または Microsoft Active Directory を使用する場合は、「LDAP/AD の設定ページ」を参照してください。
324
Terracotta のキットの bin ディレクトリにある「usermanagement」スクリプトを使って認証と承認
の設定をします。また、このスクリプトは、必要なユーザー名とロールを保有する「.ini」ファイル
（対応するパスワードはキーチェーンファイルに格納されています）を作成します。
セキュリティで保護された Terracotta クラスタのすべてのノードの「.ini」ファイルにエントリー
がなくてはなりません。
• ローカルサーバ自身
• その他すべてのサーバ
• すべてのクライアント
「usermanagement」スクリプトは以下の形式で使います。
bin/usermanagement.sh -c <file><username> terracotta
-c は、ファイルが存在しない場合のみ必要となります。サーバでは、<username>は<security>/<auth>/<user>で構成設定した値として使われます。クライアントのパスワードは、そ
のクライアントの起動時に使用したものと同じパスワードを使用してください。ロールの
terracotta は、Terracotta サーバとクライアントに適しています。
以下に例を示します。
# Create the .ini file and add a server username and role. bin/usermanagement.sh -c my_auth.ini server1username terracotta # Add another server. bin/usermanagement.sh my_auth.ini server2username terracotta # Add a client. bin/usermanagement.sh my_auth.ini client1username terracotta # Add a user with an "admin" (read/write) role. bin/usermanagement.sh my_auth.ini admin1username admin # Add a user with a "terracotta" (read) role. bin/usermanagement.sh my_auth.ini console1username operator
「サーバのセキュリティの構成設定」で、「.ini」ファイルへのパスと共に、正しい Shiro レルムを
指定してください。
... <auth>
325
<realm>com.tc.net.core.security.ShiroIniRealm</realm> <url>file:///%(user.dir)/myShiroFile.ini</url> <user>server1username</user> </auth> ...
49.3.4 サーバのセキュリティの構成を設定する サーバアレイのセキュリティは、Terracotta 構成設定ファイル（デフォルトで tc-config.xml）で設
定します。以下に、セキュリティの構成情報の設定サンプルを示します。
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"> ... <servers secure="true"> <server host="172.16.254.1" name="server1"> ... <security> <ssl> <certificate>jks:server1alias@/the/path/keystore-file.jks</certificate> </ssl> <keychain> <class>com.terracotta.management.keychain.FileStoreKeyChain</class> <url>file:///%(user.dir)/server1keychain.tkc</url> </keychain> <auth> <realm>com.tc.net.core.security.ShiroIniRealm</realm> <url>file:///%(user.dir)/myShiroFile.ini</url> <user>server1username</user> </auth> </security> ... </server> ... </servers> ... </tc:tc-config>
SSL を使ったセキュリティで保護されているクラスタでは、セキュリティ関連情報が格納、定義さ
れている<security>ブロックがすべてのサーバに対して必要です。構成設定のキーストア、キーチ
ェーン、「.ini」ファイルは、クラスタ内のすべてのサーバで有効である必要があります。ファイル
を使った認証および承認の代わりに、「LDAP または Microsoft Active Directory」を設定することも
できます。
326
下表は、構成情報の設定サンプルにあるセキュリティ関連の要素と属性を定義しています。
名称 記述 説明
secure <servers>要素の属性で、クラスタの SSL セキュリティを有
効化します。デフォルトは「false」です。 SSL を使ったセキュリテ
ィを包括的に有効化およ
び無効化します。
certificate サーバの認証で使う証明書とそれを含むキーストアファイ
ルの場所を指定する要素です。証明書を含むキーストアの
場所は「location is jks:alias@/path/to/keystore」の形式を
使用します。「alias」はキーストアファイルに証明書を格
納した際に使った値と同じものを指定してください。
JKS タイプのキーストア
のみがサポートされてい
ます。
class キーチェーンファイルを定義するクラスを指定する要素で
す。クラスが指定されていない場合は、
com.terracotta.management.keychain.FileStoreKeyChain が使
われます。
url キーチェーンファイル（<keychain>下の場合）または認証
および承認のメカニズム（<auth>下の場合）の URI です。
これらの URI はキーチェーンや認証体系のクラスに渡さ
れ、キーチェーンファイルまたは認証／承認ソースをそれ
ぞれ指定します。
これらのファイルは
「keychain」スクリプト
と「usermanagement」usermanagement スクリ
プトを使って作成、管理
します。Microsoft Active Directory や LDAP を使用
する場合は、LDAP また
は LDAPS 接続が指定され
ます。
realm ファイル使用（.ini）、Microsoft Active Directory、または
標準 LDAP など、使用する認証および承認スキームの種類
を決定する Shiro セキュリティレルムです。
この要素の値は、選択し
た認証および承認スキー
ムのセットアップ時に指
定します。
user このサーバを表すユーザー名です。他のサーバによって認
証されます。この名前は、サーバ証明書の一部です。デフ
ォルトは「terracotta」です。
49.4 TerracottaクライアントでSSLを有効化する
Terracotta クライアントが Terracotta サーバアレイへ SSL 接続を有効化する際には、特別な構成設
定は必要ありません。
注意：下のサンプルにあるスクリプト名は*NIX システムを対象としたものです。同じ場所に、対
応する Microsoft Windows 用のスクリプトもあります。以下において、拡張子「.sh」を「.bat」に
置換し、パスの区切り文字を適切に変換してください。
クライアントで SSL セキュリティを有効化するには、以下を確認します。
327
• クライアントがクラスタに接続する際に使用するアドレスの先頭に、クライアントのユーザー
名を追加します。
認証対象となるユーザー名の後に、「@」マークとセキュアモードで稼働中のアクティブサー
バのアドレスが続くようにします。形式は、<client-username>@<host>:<tsa-port>となります。
このようにユーザー名を自動的にアドレスの先頭に追加することで、クライアントの SSL 接続
を開始します。
例えば、クライアントが client1 というユーザー名で、上の構成設定サンプルのサーバに接続
する場合、アドレスは次のようになります。
[email protected]:9510
この RI は、SSL を使用しないクラスタでクライアントを起動する<host>:<tsa-port>というアド
レス部分を置換します。
• クライアントのユーザー名と対応するパスワードは、「サーバの「.ini」ファイル」のユーザ
ー名とパスワード、または「LDAP や Active Directory」の証明書と同じでなければなりません。
ユーザー名は URI に含まれていますが、パスワードは作成した「ローカルのキーチェーンエ
ントリー」と同じものを使います。
クライアントの証明書は、「terracotta」または「admin」というロールと関連付けてください。
• Terracotta サーバが（信頼できる CA が署名した証明書ではなく）自己署名証明書を使用して
いる場合、クラスタ内のすべてのサーバの公開鍵を格納している「クライアントのトラストス
トアを指定」してください。
49.4.1 キーチェーンエントリーを作成する Terracotta クライアントには、クラスタ内のすべての Terracotta サーバに対するエントリーを持つ
キーチェーンファイルが必要です。エントリーの形式には、「tc」スキームを使います。
tc://<client-username>@<host>:<tsa-port>
上の構成情報の設定サンプルにあるサーバのエントリーは以下のようになります。
tc://[email protected]:9510
Terracotta キットの keychain スクリプトを使い、エントリーを追加します。
bin/keychain.sh clientKeychainFile tc://[email protected]:9510
キーチェーンファイルが存在しない場合は、-c フラグを使って作成します。
bin/keychain.sh -c clientKeychainFile tc://[email protected]:9510
328
キーチェーンファイルの作成中に、マスタパスワードの入力プロンプトが表示されます。マスタパ
スワードの自動入力については、「クライアントによるキーチェーンパスワードの自動読み取り」
を参照してください。
クライアントのキーチェーンファイルにあるこのエントリーは、クライアントのパスワードの鍵と
して機能し、クライアントのユーザー名（上のサンプルでは「client1」）と共にサーバに提供され
ます。これらの証明書は、「サーバの「.ini」ファイル」また「LDAP や Active Directory」の証明書
と同じでなくてはなりません。
Terracotta クライアントは、以下の場所でキーチェーンファイルを検索します。
• %(user.home)/.tc/mgmt/keychain
• %(user.dir)/keychain.tkc
• システムプロパティの com.tc.security.keychain.url で指定したパス
keychain スクリプトの使用例
keychain スクリプトを実行すると、以下のメッセージが表示されます。
Terracotta Management Console - Keychain Client KeyChain file successfully created in clientKeychainFile Open the keychain by entering its master key:
このメッセージに対し、マスターキーを入力します。次に、サーバの URI に割り当てるパスワード
を入力します。
Enter the password you wish to associate with this URL: Password for tc://[email protected]:9510 successfully stored
スクリプトが証明書やサーバのアドレスを検証することはありません。
49.4.2 クライアントのトラストストアを使用する Terracotta サーバが（信頼できる CA が署名した証明書ではなく）自己署名証明書を使用している
場合は、クライアントにトラストストアを作成し、各サーバの公開鍵の証明書をそのトラストスト
アにインポートします。
TSA のサーバに「トラストストアを作成済みの場合」は、まずそのサーバの公開鍵の証明書をトラ
ストストアにインポートしてから、そのファイルを各クライアントにコピーします。
クライアントがトラストストアを見つけることができるように、該当するトラストストアファイル
の場所に Java のシステムプロパティの javax.net.ssl.trustStore を設定してください。この場合、ト
ラストストアをオープンして各証明書にアクセスするための既存の秘密鍵を保存しておいてくださ
い。
329
トラストストアの既存のマスタパスワードを変更するには、Java のシステムプロパティの
javax.net.ssl.trustStorePassword を使います。
ヒント：トラストストアのパスワードの変更
49.5 Terracotta管理サーバのセキュリティ
Terracotta 管理サーバ（TMS）と一緒にセキュアな TSA を使用するには、構成情報の追加設定が必
要です。
49.5.1 IDアサーションの構成情報を設定する 各サーバの<security>ブロックに以下を追加します。
<security> ... <management> <ia> https://my-tms.mydomain.com:9443/tmc/api/assertIdentity</ia> <timeout>10000</timeout> <hostname>my-l2.mydomain.com</ hostname > </management> </security>
各ブロックの説明：
• <timeout>は、サーバから TMS への接続におけるタイムアウト値（ミリ秒）です。
• <ia>は、TMS のドメインの HTTPS （または HTTP）の URL です。URL の後にポート番号の
「9443」と/tmc/api/assertIdentity というパスが続きます。
HTTPS（推奨）を使用する場合は、TMS から公開鍵をエクスポートし、サーバのトラストス
トアにインポートします。同様に、サーバの公開鍵もエクスポートし、TMS のトラストスト
アにインポートしてください。または、（ローカルサーバの公開鍵を含んだ）サーバのトラス
トストアを TMS にコピーしてください。
• <management><hostname>は、サーバの DNS ホスト名が証明書で使用されているサーバのホ
スト名と一致しない場合のみ使います。不一致があった場合、サーバの DNS アドレスをここ
に入力します。
TMS から公開鍵をエクスポートしてください。
330
49.5.2 キーチェーンを使ったJMX認証 サーバ-クライアント間の REST エージェント認証を使用するには、以下が必要です。クラスタ内の
すべてのノードのキーチェーンに次のエントリーを入れ、同一の秘密鍵でロックします。
jmx:net.sf.ehcache:type=RepositoryService
また、jmx://<user>@<host>:<group-port>>形式のキーチェーンエントリーを使用して、サーバ間の
REST エージェント通信を承認してください。<user>の値は、各サーバの構成設定の
<security>/<auth>/<user>で指定します。ユーザーがプロセス所有者として操作することとは関係
ありません。
例えば、「server1」のキーチェーンに「server2 」のエントリーを作成する場合は以下を使用しま
す。
bin/keychain.sh server1keychain.tkc jmx://[email protected]:9530
各サーバに、そのサーバ自身のエントリーおよび TSA の他のサーバのエントリーが必要です。
49.5.3 TMSのセキュリティをセットアップする TMS がセキュリティで保護されていない場合、保護されている TSA に接続することはできません。
TMS のセキュリティのセットアップについては、「このページ」を参照してください。
49.5.4 特定のサーバに対するクライアント制限 デフォルトでは、クライアントが REST リクエスト応答時に特定のサーバに対してのみ認証を行な
うような制限はありません。ただし、Ehcache の構成情報にある<managementRESTService>要素の
securityServiceLocation 属性を使うと、クライアントが応答するサーバを明示的に制限することが
できます。
この属性が空である（または見つからない）場合、そのような制限はなく、クラスタ内のセキュリ
ティ要件を満たしたいかなるサーバに対しても認証を行ないます。SSL 接続と認証／承認メカニズ
ムは十分なセキュリティを提供するため、制限のない設定が推奨されます。
クライアントの REST サービスにさらなるセキュリティが必要な場合、以下のように許可したサー
バのリストを構成設定します。
<managementRESTService ... securityServiceLocation=" https://my-l2-node1/tmc/api/assertIdentity , https://my-l2-node2/tmc/api/assertIdentity ">
「my-l2-node1」と「my-l2-node2」はサーバのホスト名です。クライアントが存在するクラスタ内
のすべてのサーバは REST リクエストをそのクライアントに転送できます。そのため、この機能を
使用する際は、すべてのサーバをリストに含めるようにしてください。
331
49.6 セキュリティで保護されたサーバの運用
start-tc-server スクリプトを使い、セキュリティで保護された Terracotta クラスタのサーバを起動
します。最初の起動メッセージの後に、サーバのキーチェーンに対するマスタパスワードを求める
プロンプトが表示されます（または「サーバがパスワードを自動取得する」ように設定することも
可能です）。パスワードを入力すると、サーバは通常どおり起動を続行します。
49.6.1 キーチェーンのマスタパスワードをファイルから読み取る 起動時にキーチェーンのマスタパスワードを手動で入力しなくとも、サーバがパスワードを自動的
に読み取るように設定できます。
1. パスワードを任意のファイルから読み取るように設定するには、（JAR の
com.terracotta:security-keychain にある）
com.terracotta.management.security.SecretProviderBackEnd インターフェースを実装します。
以下に例を示します。
package com.foo; import com.terracotta.management.security.SecretProviderBackEnd; import java.io.ByteArrayOutputStream; import java.io.FileInputStream; import java.io.IOException; public class MySecretProvider implements SecretProviderBackEnd { private byte[] bytes; // This method reads the password into a byte array. @Override public void fetchSecret() { try { bytes = readPasswordFile("password.pw"); } catch (IOException ioe) { throw new RuntimeException("Cannot read password from file", ioe); } } private byte[] readPasswordFile(String filename) throws IOException { FileInputStream fis = new FileInputStream(filename); try { byte[] buffer = new byte[64];
332
ByteArrayOutputStream baos = new ByteArrayOutputStream(); while (true) { int read = fis.read(buffer); if (read == -1) { break; } baos.write(buffer, 0, read); } return baos.toByteArray(); } finally { fis.close(); } } // This method returns the byte array containing the password. @Override public byte[] getSecret() { return bytes; } }
2. 実装（MySecretProvider）を含む JAR を作成し、BigMemory Max の server/lib ディレクトリに
コピーします。
3. ここでは、新しく作成した JAR ファイルが my-secret-provider.jar という名前だと仮定します。
BigMemory Max の server/bin にある start-tc-server スクリプトを以下のように編集します。
UNIX/LINUX -cp "${TC_INSTALL_DIR}/lib/tc.jar" \の部分を次のように変更します。 -cp "${TC_INSTALL_DIR}/lib/tc.jarr:${TC_INSTALL_DIR}/lib/my-secret-provider.jar" \
MICROSOFT WINDOWS set CLASSPATH=%TC_INSTALL_DIR%\lib\tc.jar の部分を次のように変更します。 `set CLASSPATH=%TCINSTALLDIR%\lib\tc.jar;%TCINSTALLDIR%\lib\my-secret-provider.jar
4. ユーザ実装を指定する<secret-provider>要素が、サーバの構成情報の設定に含まれていること
を確認します。
<security> ...
333
<keychain> <url>/path/to/my/keychain</url> <secret-provider>com.foo.MySecretProvider</secret-provider> </keychain> ... </security>
サーバが起動時に、実装で指定したファイルからキーチェーンパスワードを読み取るようになりま
す。
さらにシンプルな方法として、パスワードをハード･コード化することもできます。
package com.foo; import com.terracotta.management.security.SecretProviderBackEnd; public class MySecretProvider implements SecretProviderBackEnd { // This method returns the byte array containing the password. @Override public byte[] getSecret() { return new byte[] {'p', 'a', 's', 's', 'w', 'o', 'r', 'd'}; } @Override public void fetchSecret() { } }
クライアントによるキーチェーンパスワードの自動読み取り
サーバー同様に、Terracotta クライアントがキーチェーンのマスタパスワードを自動的に読み取る
よう設定することもできます。org.terracotta.toolkit.SecretProvider をインポートし、fetchSecret()と getSecret()を上述のようにオーバーライドします。
実装を JAR にパッケージ化する代わりに、システムプロパティの
com.terracotta.express.SecretProvider を使って実装するクラスを指定します。
49.6.2 セキュリティが有効化されていることを確認する サーバのセキュリティが有効化されていることを確認するには、以下の方法があります。
• 起動メッセージの Security enabled, turning on SSL を見つけて確認する。
334
• 「SSL keystore」、「HTTPS Authentication enabled」、「Security enabled, turning on SSL」と
いう情報を含むログメッセージを探す。
• サーバへの JMX 接続を試みる。セキュリティが有効化されていれば、この接続は失敗します。
49.6.3 トラブルシューティング 起動時に以下のようなエラーが発生する可能性があります。
RuntimeException:Couldn't access a Console instance to fetch the password from!
起動時に「nohup」を使用することで発生します。起動プロセスでは、コンソールでパスワードの
入力を読み取る必要があります。パスワードを手動入力する場合は、起動プロセスをバックグラウ
ンドで実行できません。キーチェーンのマスタパスワードを手動入力しない方法は、「キーチェー
ンのマスタパスワードをファイルから読み取る」を参照してください。
TCRuntimeException: Couldn't create KeyChain instance ...
Terracotta の構成情報の設定で指定したキーチェーンファイルが見つかりません。
<keychain>/<url>で指定した場所にファイルが存在するか確認してください。
RuntimeException: Couldn't read from file ...
キーチェーンファイルのパスワードが正しくない場合に表示されるエラーです。
RuntimeException: No password available in keyChain for ...
サーバの証明書に対するキーチェーンのパスワードエントリーが見つからない場合に表示されるエ
ラーです。キーチェーンファイルに「証明書のパスワードを明示的に格納」してください。
このエラーは、解決したホスト名や IP アドレスがキーチェーンのエントリーと一致しない場合に
も表示されます。
• tc://terracotta@localhost:9530 is the entry, but when the server configuration is read then localhost is resolved to an IP address. The entry searched for becomes tc://terracotta@<a.certain.ip.address>:9530.
• tc://terracotta@<a.certain.ip.address>:9530 is the entry, but when the server configuration is read then <a.certain.ip.address> is resolved to a host name. The entry searched for becomes tc://[email protected]:9530.
Two Active Servers (Split Brain)
アクティブとミラーの並列構成下で、起動時に両サーバがアクティブ状態を宣言した場合に発生し
ます。このエラーは、SSL のハンドシェイクの失敗によって発生します。下記のようなエントリー
がサーバログに現われる場合があります。
335
2013-05-17 12:10:24,805 [L2_L2:TCWorkerComm # 1_W] ERROR com.tc.net.core.TCConnection - SSL handshake error: unable to find valid certification path to requested target, closing connection.
各サーバにおいて、すべてのキーチェーンエントリーが精確で、必要な証明書が適切なトラストス
トアで利用可能であることを確認します。
No Messages Indicating Security Enabled
サーバ起動時にエラーは発生しないものの、セキュリティが有効化されているというメッセージが
表示されない場合は、secure="true"が<servers>要素に含まれていることを確認してください。
50 LDAPを使った認証のセットアップ
50.1 はじめに
Terracotta サーバアレイ（TSA）では、「ビルトインのユーザー管理システム」ではなく、ライト
ウェイト・ディレクトリ・アクセス･プロトコル（LDAP）を使った認証および承認をセットアップ
できます。 LDAP を使うと、既存のセキュリティ・インフラストラクチャーを使って、Terracottaクラスタへのアクセスを制御することができるようになります。
サポートされている LDAP を使った認証には Microsoft Active Directory と標準 LDAP の 2 種類があ
ります。他には LDAPS（SSL over LDAP）がサポートされています。
注意: Active Directory や標準 LDAP を使う前に、Terracotta サーバが「SSL を使うように設定」し
てください。
50.2 Configuration Overview Active Directory and standard LDAP are configured in the <auth> section of each server's configuration block:
<servers secure="true"> <server host="172.16.254.1" name="server1"> ... <security> ... <auth> <realm>...</realm> <url>...</url> <user>...</user> </auth> </security>
336
... </server>
Active Directory と標準 LDAP の構成情報は、<realm>要素と<url>要素を使って設定します。<user>要素は「Terracotta サーバ同士の接続」に使い、LDAP 関連の構成には必要ありません。
このドキュメントでは、表示上の理由で URL に改行を使用しています。ただし、実際に構成情報
を設定される際は、URL に改行を使用しないでください。
50.2.1 レルムとロール LDAP ベースの認証や承認の設定は、Shiro レルムを使ってユーザーグループを以下のロールのうち
の一つにマッピングします。
• admin – サーバのシャットダウンや構成情報の再読み込みなど、システム上の動作を司る管理
者のロールです。
• terracotta – サーバのシャットダウンや構成情報の再読み込みなど、システム上の動作に対す
る権限を持たないオペレーターのロールです。重複することはありますが、Terracotta のロー
ルは admin のロールのサブセットではありません。
50.2.2 URLのエンコーディング LDAP の URL で使用する文字のいくつかは、「CDATA コンストラクタでラップ」していないかぎ
り、エンコーディングを必要とします。LDAP の URL で必要になる可能性のある文字は以下のとお
りです。
• & (アンパサンド) – %26 としてエンコードします。
• { (左の中括弧) – %7B としてエンコードします。
• } (右の中括弧) – %7D としてエンコードします。
• スペース – %20 としてエンコードします。CDATA でラップしていても、スペースは常にエン
コードしてください。
• = (等号) – エンコードの必要はありません。
50.3 Active Directoryの構成設定
以下のように、Terracotta の構成情報の<security>セクションにレルムと URI を指定します。
<auth> <realm>com.tc.net.core.security.ShiroActiveDirectoryRealm</realm> <url>ldap://admin_user@server_address:server_port/searchBase=search_domain%26 groupBindings=groups_to_roles</url>
337
<user></user> </auth>
<realm>要素の値には、Active Directory の正しいクラス（または Shiro セキュリティレルム）を指
定してください。URL の構成要素は、以下の表で定義されています。
構成要素 説明
ldap:// スキームには、ldap://または ldaps://を使用します。
admin_user searchBase に指定されたドメインで検索を行なう権限を持つ、Active Directory のユーザーの名前です。このユーザーのパスワードは
Terracotta サーバにより使用される Terracotta キーチェーンに格納し
てください。鍵には、LDAP の URI のルートである
ldap://admin_user@server_name:server_port を使用し、最後のスラッ
シュ記号（「/」）は付けません。
server_address:server_port サーバの IP アドレスまたは解決可能な完全修飾ドメイン名と Active Directory のポートです。
searchBase 検索対象の Active Directory のドメインを指定します。例えば、Active Directory のドメインが「reggae.jamaica.org」の場合、形式は
searchBase=dc=reggae,dc=jamaica,dc=org となります。
groupBindings Active Directory のグループと Terracotta のロールの間のマッピングを
指定します。例えば、
groupBindings=Domain%20Admins=admin,Users=terracotta は、Active Directory のグループである「Domain Admins」と「Users」をそれぞれ
Terracotta のロールである「admin」と「terracotta」にマッピングし
ます。上述の Active Directory のグループをマッピングするには、これ
らのグループが「searchBase」で指定したドメインに属している必要
があります。他のドメインにあるこれら以外のすべてのグループ（指
定された名前も含める）は無視されます。
以下に例を示します。
<auth> <realm>com.tc.net.core.security.ShiroActiveDirectoryRealm</realm> <url>ldap://[email protected]:389?searchBase=dc=reggae,dc=jamaica,dc=org%26 groupBindings=Domain%20Admins=admin,Users=terracotta</url> <user></user> </auth>
50.4 標準LDAPの構成設定
以下のように、Terracotta の構成情報の<security>セクションにレルムと URL を指定します。
<auth> <realm>com.tc.net.core.security.ShiroLdapRealm</realm>
338
<url>ldap://directory_manager@myLdapServer:636? userDnTemplate=cn=%7B0%7D,ou=users,dc=mycompany,dc=com%26 groupDnTemplate=cn=%7B0%7D,ou=groups,dc=mycompany,dc=com%26 groupAttribute=uniqueMember%26 groupBindings=bandleaders=admin,bandmembers=terracotta</url> <user></user> </auth>
<realm>要素の値には、Active Directory の正しいクラス（または Shiro セキュリティレルム）を指
定してください。URL の構成要素は、以下の表で定義されています。
構成要素 説明
ldap:// スキームには、ldap://または ldaps://を使用します。
directory_manager LDAP サーバ上で検索を行なう権限を持つユーザーの名前です。匿名
検索が許可されている場合は、特にユーザーを必要としません。ユー
ザーを必要とする場合は、このユーザーのパスワードを Terracotta の
キーチェーンに格納してください。鍵には、LDAP の URL のルートで
ある ldap://admin_user@server_name:server_port を使用し、最後のス
ラッシュ記号（「/」）は付けません。
server_address:server_port サーバの IP アドレスまたは解決可能な完全修飾ドメイン名と LDAP サ
ーバのポートです。
userDnTemplate ユーザーテンプレート値を指定します。以下の例を参照してくださ
い。
groupDnTemplate グループテンプレート値を指定します。以下の例を参照してくださ
い。
groupAttribute ユーザーを一意に識別する LDAP のグループ属性を指定します。デフ
ォルトは「uniqueMember」です。以下の例を参照してください。
groupBindings LDAP のグループと Terracotta のロールの間のマッピングを指定しま
す。例えば、
groupBindings=bandleaders=admin,bandmembers=terracotta は、LDAPのグループである「bandleaders」と「bandmembers」をそれぞれ
Terracotta のロールである「admin」と「terracotta」にマッピングし
ます。
以下に例を示します。
<auth> <realm>com.tc.net.core.security.ShiroLdapRealm</realm> <url>ldap://[email protected]:636? userDnTemplate=cn=%7B0%7D,ou=users,dc=mycompany,dc=com%26 groupDnTemplate=cn=%7B0%7D,ou=groups,dc=mycompany,dc=com%26 groupAttribute=uniqueMember%26
339
groupBindings=bandleaders=admin,bandmembers=terracotta</url> <user></user> </auth>
これは LDAP のディレクトリ構造が以下のように設定されていることを示します。
+ dc=com + dc=mycompany + ou=groups + cn=bandleaders | uniqueMember=dizzy | uniqueMember=duke + cn=bandleaders | uniqueMember=art | uniqueMember=bird
ただし、LDAP のディレクトリ構造が以下のように設定されている場合は、
+ dc=com + dc=mycompany + ou=groups + cn=bandleaders | musician=dizzy | musician=duke + cn=bandleaders | musician=art | musician=bird
groupAttribute の値は「musician」になります。
50.5 CDATAコンストラクタを使う
URL がエンコードされるのを防ぐには、CDATA で以下のようにラップします。
<url><![CDATA[ldap://[email protected]:636? userDnTemplate=cn={0},ou=users,dc=mycompany,dc=com& groupDnTemplate=cn={0},ou=groups,dc=mycompany,dc=com& groupAttribute=uniqueMember& groupBindings=bandleaders=admin,bandmembers=terracotta]]></url>
340
51 Terracottaサーバアレイの運用
51.1 自動リソース制御
Terracotta サーバアレイのリソース管理では、自己監視機能と集計機能を使い、データセットのリ
アルタイム測定とユーザー設定により制限されるメモリ残量の評価を行ないます。インメモリデー
タは 3 通りの方法で管理できます。
1. Time： TTI および TTL の構成情報で、エントリーの有効期限を設定し、新しい TSA のエビク
ション実装によるエビクション対象に指定します。また、キャッシュの構成情報で、エントリ
ーを永続化したり、エントリーやキャッシュをピンニングしてエビクションによる破棄の対象
にしないように設定することも可能です。
2. Size：「tc-config.xml」ファイルの maxDataSize 属性を使用し、TSA が管理する BigMemory の
サイズを設定します。
3. Count：「tc-config.xml」ファイルの maxEntriesInCache 属性を使用し、TSA が管理する
BigMemory のエントリーの数を設定します。
51.1.1 エビクション すべてのデータはメモリに保存されます。TSA はバックグラウンドでエビクションを実行し、デー
タセットを制限内のサイズに抑えます。エビクションによりエントリーをデータセットから破棄す
ることで、メモリが一杯になる前にデータ量を減らします。エントリーがエビクション対象となる
条件は以下になります。
• エントリーが Terracotta クライアント（L1）上に存在しないこと。
• エントリーが Terracotta サーバにピンニングされていないこと。
• エントリーが System of Record（SOR)にバックアップされたキャッシュ内にあること。
BigMemory のインメモリデータは、BigMemory がデータを所有する場合は「ストア」として扱わ
れ、データが System of Record（SOR）に常駐する場合「キャッシュ」として扱われます。
BigMemory が作成するデータや、ユーザーが使用するアプリケーションが作成する実行時のデータ
はストアとして扱われるデータの一例です。データストアは唯一かつ主要なレコードであるため、
TSA がエビクションにより破棄する対象にはなりません。キャッシュに記録されたデータは SORにバックアップされているため、TSA のエビクションにより破棄されます。（データ構造の区別は
自動的に処理されます。Terracotta ツールキットが提供する API を使って、カスタマイズされたデ
ータ構造の構成情報を設定することもできます。）
ストアとキャッシュ
341
エビクションには以下の種類があり、これらはすべてバックグラウンドで行なわれます。
1. 定期的なエビクションは、必要に応じて有効化されます。TTI と TTL の設定に基づいて期限切
れのエントリーを破棄します。定期的なエビクションのアクティビティは、TMC の「Server Expiration Rate」グラフに表示されます。
1. リソースに基づくエビクションは、定期的な TTI と TTL エビクションのスケジューラによっ
て有効化されます。また、リソース監視イベントによっても有効化されます。リソースに基づ
くエビクションは常にヒープとオフヒープのストアを確認し、リソースの使用状況をチェック
します。「tc-config.xml file」で設定した maxDataSize の 10%が使用された時点で、TTI とTTL で期限切れになった破棄対象の要素を探し始めます。90%が使用されると、期限切れの要
素だけでなく、有効期限内の要素もエビクションによって破棄します。監視対象のリソースが
臨界閾値を超えると、リソースに基づくエビクションは監視対象のリソースがこの閾値を下回
るまで、エビクションによる破棄を継続的に行ないます。
監視対象の閾値は、使用している領域と未使用の領域に対する 2 種類です。いずれの領域が閾値を
超えても、リソースに基づくエビクションが発動します。リソースに基づくエビクションが一度発
342
動すると、使用している領域と未使用の領域の両方が閾値を下回るまでエビクションは終了しませ
ん。
TMC の「Offheap Usage」グラフでは、以下の情報を確認できます。
* 「Off-heap Max」は設定した maxDataSize です。 * 「Off-heap Reserved」はシステムで未使用の領域の使用状況を表します。 * 「Off-heap Used」は BigMemory で使用中の領域を表します。
1. 容量に基づくエビクションは、キャッシュが maxEntriesInCache で設定した最大数を超えると
発動します。また、最大数を超えた回数でも発動し、キャッシュの容量を最大にしようとしま
す。Ehcache の構成情報の設定に maxEntriesInCache 属性が存在している必要があります。
（容量に基づくエビクションを実行しない場合は、構成情報の設定に maxEntriesInCache が含
まれないようにします。）maxEntriesInCache の設定を省略すると、デフォルト値の「0」が
指定されます。これは、キャッシュが無制限となり、容量に基づくエビクションを行なわない
ことを意味します（ただし、定期的なエビクションとリソースに基づくエビクションは行なわ
れます）。
リソースに基づくエビクションと容量に基づくエビクションのアクティビティは、TMC の「Server Eviction Rate」グラフに表示されます。
51.1.2 エビクション方式をカスタマイズする 以上の三種類のエビクションに基いた以下のエビクション設定方法を利用し、TSA のデータセット
のサイズを制御します。
1. データセットのエントリーに「Time To Idle（TTI）」または「Time to Live（TTL）」のオプシ
ョンを設定します。有効期限が切れた時点で、定期的なエビクションによってエントリーが破
棄されます。
343
2. maxDataSize 属性を設定し、BigMemory の使用量を制御します。この設定で指定した値を超え
ると、リソースに基づくエビクションが発動します。
3. maxEntriesInCache 属性で、容量に基づくエビクションの発動を設定します。
51.2 メモリが一杯になる直前の状態
メモリが一杯になる直前の状態では、エビクションが追いつかずに、データセットを BigMemoryのサイズ制限内に維持することが難しくなります。そのような場合、TSA はオペレーションに対し
て一時的なスロットルをかけ、バックグラウンドでの自動回復を試みます。回復が見込めない場合、
TSA はメモリ不足によるエラーの発生を防ぐために、「制限モード」に移行します。TSA が制限モ
ードに移行すると、Terracotta 管理コンソール（TMC）はその旨通知するので、追加の回復対策を
実行してください。
メモリが一杯になる直前の状態における TSA の動作の概要を以下に示します。
• 使用量が臨界閾値（T1）に達すると、TSA は「スロットルモード」に移行します。スロット
ルモードでは、書き込み速度が減少し、TSA は対象となるキャッシュエントリーをエビクショ
ンによって破棄し、メモリ使用量を設定範囲内に戻そうとします。
• 使用量が停止閾値（T2）に達すると、TSA は「制限モード」に移行します。制限モードでは、
書き込みはブロックされ、例外がスローされます。オペレーターによるメモリ使用量の削減が
必要です。
• 使用量が T1 を下回った段階で、TSA は通常運用に戻ります。
スロットルモード 制限モード
移行のタ
イミング 使用領域または未使用領域のメモリ使用
量が臨界閾値を越えた時点 使用領域または未使用領域のメモリ使用
量が停止閾値を越えた時点
オペレー
ターイベ
ント
“TPS seems really low; marking us as being throttled” “W
e’re in restricted mode; waiting a while and retrying”
データへ
のアクセ
ス
インメモリデータへの変更速度が減少 インメモリデータへの変更速度はブロッ
クされる
実行可能
なオペレ
ーション
すべてのキャッシュオペレーションが実
行可能 get、remove、および config の変更のみ
実行可能
アクショ
ン エビクションはバックグラウンドで自動
継続 追加のエビクションを行なうには、オペ
レーターの介入が必要
データの
状態 エビクション対象のデータが存在 エビクション対象のデータは、メモリ内
に存在しない（すべてのキャッシュがピ
344
ンニングされる）
回復処理 自動 TMC またはプログラムによる回復。キャ
ッシュのクリアまたはデータセットから
の削除。
通常運用
に戻るタ
イミング
バックグラウンドのエビクションが追い
つき、データセットのサイズを制限値よ
り小さくした時点
ユーザーの介入によりスペースが空き次
第、TSA は自動的に通常運用に移行しま
す。
51.2.1 制限モードでの運用 TSA が一時的に制限モード下にある場合、put メソッドや replace メソッドなど、リソース活用を
増加するようなデータセットへの変更は行なえません。ただし、get や remove、構成情報の設定な
どの他のオペレーションは行なえます。
51.2.2 回復処理 バックグラウンドのエビクションがデータセットの容量を制限内に縮小する時間が出来次第、TSAはスロットルモードから自動回復します。
TSA が制限モードに移行すると、オペレーターイベントは TMC のログに記録されます。ユーザー
またはプログラムによる介入が必要になります。TMC では、データセットのサイズを手動で縮小で
きます。また、オペレーターイベントを事前に予測し、プログラム論理で適切に対処することも可
能です。
データセットの縮小には以下の対処方法を推奨します。
• キャッシュをクリア（TMC からクリアまたはプログラムによるクリア）する
• プログラムを使い、エントリーをデータセットから削除する
注意：制限モード下のエビクションはリソースに基づくため、TTI、TTL、または最大容量を変更し
ても、TSA は制限モードから移行しません。
TMC からキャッシュをクリアするには、Application Data タブの Management サブタブをクリッ
クします。キャッシュにはそれぞれクリック可能な Clear Cache のオプションがあります。ピンニ
ングされているキャッシュをクリアするときは注意してください。
51.3 クラスタイベント
クラスタイベントクラスタイベントは、トポロジの変更、パフォーマンスの問題、オペレーション
のエラーを通知します。これらのイベントは、Terracotta サーバ（L2）とクライアント（L1）の両
方のログに記録されます。また、「TMC」からも確認できます。
ログや TMC から確認できるイベントの種類を、以下の表示に示します。
345
イベントカテゴ
リ種別 レベル 原因 対処 説明
ClusterStateEvents old.db
INFO アクティブな L2 が
再起動しています。
データはディスクか
ら回復します。
ClusterTopologyEvent config.reloaded
INFO クラスタの構成情報
が再ロードされたと
きのメッセージで
す。
DGCMessages dgc.started
INFO 定期 DGC が構成情
報で明示的に有効化
されています。これ
に従ってクリーンア
ップ処理が起動した
ときのメッセージで
す。
定期 DGC が不要な
場合は無効化してく
ださい。そのほう
が、クラスタ全体の
パフォーマンスが向
上します。
デフォルトでは、定期
DGC が無効化されてい
ます。ツールキットに
は分散したガーベジを
処理する機能がないた
め、定期 DGC の有効化
を検討してください。
DGCMessages dgc.finished
INFO 定期 DGC が構成情
報で明示的に有効化
されています。これ
に従って起動したク
リーンアップ処理が
終了したときのメッ
セージです。
定期 DGC が不要な
場合は無効化してく
ださい。そのほう
が、クラスタ全体の
パフォーマンスが向
上します。
デフォルトでは、定期
DGC が無効化されてい
ます。ツールキットに
は分散したガーベジを
処理する機能がないた
め、定期 DGC の有効化
を検討してください。
DGCMessages dgc.canceled
INFO 定期 DGC が構成情
報で明示的に有効化
されています。これ
に従って起動した定
期 DGC が割込み
（例：フェイルオー
バ処理など）によっ
てキャンセルされた
ときのメッセージで
す。
定期 DGC が不要な
場合は無効化してく
ださい。そのほう
が、クラスタ全体の
パフォーマンスが向
上します。
デフォルトでは、定期
DGC が無効化されてい
ます。ツールキットに
は分散したガーベジを
処理する機能がないた
め、定期 DGC の有効化
を検討してください。
DGCMessages inlineDgc.cleanup .started
INFO 既存データを利用し
て起動している L2が、インライン DGCを起動したときのメ
ッセージです。
回復可能なサーバがア
クティブとして（リカ
バリから）起動すると
きに表示されます。
DGCMessages inlineDgc.cleanup .finished
INFO インライン DGC 処
理が完了したときの
メッセージです。
DGCMessages inlineDgc.cleanup .ca
INFO インライン DGC 処
理を中断したときの
クラスタが通常とは
異なる動作をしてい
フェイルオーバ時に発
生する場合がありま
346
nceled メッセージです。 ないか、あるいはそ
の他のイベントが発
生していないかを確
認してください。
す。実際には、その他
のイベントに起因しま
す。
HAMessages node.joined
INFO 指定されたノードが
クラスタに参加した
ときのメッセージで
す。
HAMessages node.left
WARN 指定されたノードが
クラスタから除外さ
れたときのメッセー
ジです。
ノードが除外された
理由を確認してくだ
さい（例：長時間に
わたる GC、ネット
ワークの問題、ロー
カルノードのリソー
スの問題など）。
HAMessages clusterNode StateChanged
INFO L2 の状態が変化し
たとき（例：「初期
化」から「アクティ
ブ」に変わったとき
など）のメッセージ
です。
状態の変化が、期待
どおりの変化である
か確認してくださ
い。
HAMessages handshake.reject
ERROR 既にクラスタから除
外されている L1 が
クラスタへの再接続
を試行し、その再接
続に失敗したときの
メッセージです。
L1 は rejoin 処理を
実行する必要があり
ます。あるいは手動
による再起動が必要
です。
MemoryManager high.memory .usage
WARN ヒープ領域の使用量
が致命的しきい値を
超えたときのメッセ
ージです。
長時間にわたる GCと同時に発生した場
合は、L1 のメモリ
を解放する必要があ
ります。
致命的しきい値のデフ
ォルト値は 70%です。
この値は
「tc.properties」で変更
できます。
MemoryManager long.gc
WARN 実行中の完全 GC の
処理時間が、設定さ
れたしきい値を越え
たときのメッセージ
です。
L1 のキャッシュに
よるメモリ占有量を
減らしてください。
アプリケーションの
ロジックとガーベジ
発生に関する問題を
調査してください。
致命的しきい値のデフ
ォルト値は 8 秒です。
この値は
「tc.properties」の
longgc.threshhold で変
更できます。このよう
なイベントが発生した
場合は、「ヘルスチェ
ッカー」などを使って
原因を調査してくださ
い。
ResourceManagement resource.ne
WARN L2 が「スロットル
モード」になったと
詳細は、「メモリが
一杯になる直前の状
この現象が発生したあ
と、L2 が
347
arcapacity きのメッセージで
す。L1 に割り当て
られているメモリが
不足している可能性
があります。ただ
し、一括ロードなど
によって一時的に発
生する現象の場合も
あります。
態」を参照してくだ
さい。 resource.capacityrestored を発行する（つまり
通常モードに戻る）場
合と、
resource.fullcapacity を
発行する（つまり制限
モードが開始する）場
合があります。どちら
が発生するのかは、利
用可能なリソースによ
って異なります。
ResourceManagement resource.fullcapacity
ERROR L2 が「制限モー
ド」になったときの
メッセージです。L1に割り当てられてい
るメモリが不足して
いる可能性がありま
す。ただし、一括ロ
ードなどによって一
時的に発生する現象
の場合もあります。
詳細は、「メモリが
一杯になる直前の状
態」を参照してくだ
さい。
この現象が発生したあ
と、L2 が
resource.capacityrestored を発行する（つまり
通常モードに戻る）場
合があります。どちら
が発生するのかは、利
用可能なリソースによ
って異なります。
ResourceManagement resource .capacityrestored
INFO L2 が「スロットル
モード」または「制
限モード」から通常
モードに戻ったとき
のメッセージです。
SystemSetupEvent time.different
WARN 各システムの時計が
合っていないときの
メッセージです。
システムの時計を合
わせてください。 許容誤差のデフォルト
値は 30 秒です。この
値は「tc.properties」の
time.sync.threshold で
変更できます。許容誤
差を大きくしすぎる
と、予期せぬエラーや
動作の原因になりま
す。注意してくださ
い。
ZapEvents zap.received
CRITICAL
ある L2 が、他の L2に対して強制再起動
を試行したときのメ
ッセージです（これ
を「zap」と呼びま
す）。
再起動対象の L2 が
再起動しない場合
は、「スプリットブ
レイン現象（ミラー
L2 が、アクティブ
L2 として動作する
現象）」が発生して
いないか確認してく
ださい。
「zap」処理は、ミラー
グループ内でのみ発生
します。
ZapEvents zap.acc CRITIC 指定された L2 が他 再起動対象の L2 が 「zap」処理は、ミラー
348
epted AL の L2 による強制再
起動処理（zap 処
理）を受け入れたと
きのメッセージで
す。
ミラーとして再起動
することを確認して
ください。そうでな
い場合は、手動で対
象 L2 を再起動して
ください。
グループ内でのみ発生
します。
ZapEvents dirty.db
WARN ミラーL2 が、デー
タを保持したままク
ラスタに再接続した
ときのメッセージで
す。
ミラーが再起動とデ
ータの破棄を自動的
に行なわない場合、
再起動の前にそのデ
ータを手動で消去す
る必要があります。
再起動したミラーL2は、データを消去しな
い限り、アクティブ L2のデータとの同期を行
ないません。通常、こ
のような処理は自動的
に実行されるため、対
応作業が必要になるこ
とはないはずです。
51.4 分散インメモリデータのリアルタイムバックアップ
TMC バックアップ機能を使うと、Terracotta サーバアレイ内のデータセット全体をバックアップす
ることができます。この機能は、各 Terracotta サーバのデータについてタイムスタンプ付きバック
アップを作成し、TSA のインメモリデータのスナップショットを提供します。
TSA の高速再起動を有効化（「tc-config.xml」で<restartable enabled="true">を指定）すると、この
機能が利用可能になります。
バックアップ機能は、インメモリデータの整合的なスナップショットを取得するために、トランザ
クションを一時停止させることで、実行中のトランザクションを完了、その後にバックアップを書
き込みます。これにより、バックアップはインメモリのエントリーおよび検索その他のインデック
スと一致するレコードになります。
TMC で、Administration タブを選択し、Backups サブタブを選択します。Make Backup ボタンを
クリックし、バックアップを行ないます。バックアップが行なわれたことの確認と、バックアップ
のタイムスタンプ付きファイル名を通知する画面が表示されます。
51.4.1 バックアップディレクトリ バックアップは、デフォルトの data-backup ディレクトリに保存されます。保存先は、「tc-config.xml」で設定することも可能です。Terracotta は、data-backup を Terracotta サーバの構成情
報ファイルがあるディレクトリ（デフォルトで「tc-config.xml」）に自動作成します。
以下で示すように、<data-backup>プロパティを使えば、サーバの構成情報ファイルに別のバック
アップディレクトリを指定し、デフォルトディレクトリをオーバーライドできます。
<servers> <server name="Server1">
349
<data>/opt/terracotta/server1-data</data> <data-backup>path/to/my/backup/directory</data-backup> <offheap> <enabled>true</enabled> <maxDataSize>2g</maxDataSize> </offheap> </server> <restartable enabled="true"/> </servers>
51.4.2 バックアップのリストア TSA は異常終了すると、再起動時にデータディレクトリからデータを自動リストアし、アプリケー
ション状態を再現します。現在のデータファイルが破損していたり、存在しない場合は、バックア
ップからリストアできます。また、データの以前のスナップショットが必要な場合などにも、やは
りバックアップからリストアできます。以下に手順を示します。
1. Terracotta クラスタをシャットダウンします。
2. 既存のデータファイルのコピーを作成します。
3. 既存のデータファイルを削除します。
4. 元（既存）のデータファイルを削除したディレクトリに、バックアップのデータファイルをコ
ピーします。
5. Terracotta クラスタを再起動します。
51.5 サーバとクライアントの再接続
アクティブとミラーの Terracotta サーバインスタンス間で切断した接続は、再接続機能で回復しま
す。詳しくは、「サーバインスタンスの自動再接続」を参照してください。
Terracotta サーバアレイは、「ヘルスチェッカー」または「クライアントの自動再接続」機能の構
成設定に基づき、認識したクライアントの切断（例えば、ネットワーク障害、クライアント側の長
時間の GC、ノード障害など）に対処します。切断されたクライアントも、これらの機能を使って
再接続しようとします。クライアントはまず、Terracotta の構成情報でセットアップされた最初の
サーバをの再接続を試み、それから同じ構成内の他のサーバと再接続しようとします。データの完
全性を維持するため、クライアントはサーバからの確認応答を受信していないトランザクションを
再送信します。
350
51.6 稼働中のクラスタにおけるクラスタトポロジの変更
TMC では、編集済みの Terracotta 構成情報ファイルを再読み込みすることで、稼働中のクラスタ
のトポロジを変更することができます。
以下に制限事項を示します。
• Terracotta 構成情報ファイルの<servers>セクションまたは<mirror-group>セクション下の
<server>ブロックの削除または追加のみ実行可能です。
• トポロジの競合を避けるには、すべてのサーバとクライアントで同じ構成情報ファイルを読み
込んでください。
同じサーバアレイに属しながら、編集済みの構成情報ファイルを共有しないサーバについては、
以下のようにそれぞれの構成情報ファイルを編集し、再読み込みしてください。サーバから構
成情報ファイルを読み込まないクライアントについては、その構成情報ファイルがサーバの構
成情報ファイルと一致するように編集してください。
51.6.1 新規サーバの追加 Terracotta クラスタに新規サーバを追加する場合は、以下の手順に従ってください。
1. クラスタで使用する Terracotta 構成情報ファイルの<servers>セクションまたは<mirror-group>セクションに、新たに<server>ブロックを追加します。新しい<server>ブロックには、
新規サーバの構成を設定するのに必要な最低限の情報が含まれていることを確認します。以下
を参照してください。それぞれのユーザーに適した値を指定します。
<server host="myHost" name="server2" > <data>%(user.home)/terracotta/server2/server-data</data> <logs>%(user.home)/terracotta/server2/server-logs</logs> <tsa-port>9513</tsa-port> </server>
2. TMC に接続しており、また TMC が接続対象のクラスタに接続済みであることを確認します。 TMC の使用については、「TMC のドキュメント」を参照してください。
3. 対象クラスタを TMC で選択します。Administration タブをクリックし、Change Topology パ
ネルを選択します。
4. Reload をクリックします。 再読み込みの結果を含むメッセージが表示されます。オペレーションが正常に完了した場合、
以下のようなメッセージが表示されます。
2013-03-14 13:25:44,821 INFO - Successfully overridden server topology from file at '/bigmemory-max-4/tc-config.xml'.
351
5. 新規サーバを起動します。
51.6.2 既存サーバの削除 Terracotta クラスタの構成設定からサーバを削除する場合は、以下の手順に従ってください。
1. クラスタから削除するサーバをシャットダウンします。 アクティブサーバをシャットダウンする場合は、まず、バックアップサーバがオンラインでフ
ェイルオーバーを有効化できることを確認してください。
2. クラスタが使用する Terracotta 構成情報ファイルから、削除するサーバに関する<server>ブロ
ックを削除します。TMC に接続しており、また TMC が接続対象のクラスタに接続済みである
ことを確認します。 TMC の使用については、「TMC のドキュメント」を参照してください。
3. 対象クラスタを TMC で選択します。Administration タブをクリックし、Change Topology パ
ネルを選択します。
4. Reload をクリックします。 再読み込みの結果を含むメッセージが表示されます。オペレーションが正常に完了した場合、
以下のようなメッセージが表示されます。
2013-03-14 13:25:44,821 INFO - Successfully overridden server topology from file at '/bigmemory-max-4/tc-config.xml'.
TMC は、Server topology reloaded from file at '/bigmemory-max-4/tc-config.xml'というイベント
を表示します。
51.6.3 既存サーバの構成情報を編集する 既存（稼働中）のサーバの構成情報を編集し、その構成情報を再読み込みしようとすると、その再
読み込み操作は失敗します。ただし、以下の手順を実施すると、既存サーバの構成情報を編集する
ことができます。
1. 「既存サーバの削除」の手順に従いサーバを削除します。サーバの<server>ブロックを削除せ
ずに、コメントアウトします。
2. サーバの<server>ブロックを変更した値に編集します。
3. 編集した<server>ブロックを追加（またはコメントアウト解除）します。
4. TMC の Change Server Topology パネルで、Reload をクリックします。再読み込みの結果を
含むメッセージが表示されます。
注意：既存サーバの構成情報を編集するには、すべてのクライアントが Terracotta サーバアレイか
ら構成情報を読み込む必要があります。他のソースから構成情報を読み取ったクライアントは、構
成情報の不一致により、TSA への接続が切断されます。
352
51.7 プロダクションモード
プロダクションモードは、Terracotta 構成情報ファイルの Terracotta プロパティで設定します。
<tc-properties> ... <property name="l2.enable.legacy.production.mode" value="true" /> </tc-properties>
プロダクションモードで、ミラーを持たないアクティブサーバを停止するには、stop-tc-server ス
クリプトに--force オプションを指定する必要があります。
51.8 分散ガベージコレクション（DGC）
分散ガベージコレクション（DGC）には、定期的 DGC とインライン DGC の 2 種類があります。定
期的 DGC の構成情報は設定可能です。手動で実行できる DGC です（下を参照）。インライン DGCは、サーバのメモリ維持を目的として自動的に実行されるガベージコレクションのプロセスです。
インライン DGC は、定期的 DGC が無効化されている状況でも自動実行されます。
インライン DGC のアルゴリズムは、パフォーマンスを最適化する間隔で作動します。そのため、
分散ガベージを即時収集するとはかぎりません。
51.8.1 定期的DGCの実行 定期的 DGC は以下の方法で実行します。
• run-dgc shell script： run-dgc shell スクリプトを呼び出し、DGC を外部から起動します。
• JMX：サーバの JMX 管理インターフェースから DGC を起動します。
デフォルトでは、<garbage-collection>セクションの Terracotta 構成情報ファイルで DGC は無効化
されています。ただし、ガベージをクリアする必要があるのにもかかわらずインライン DGC が稼
動しない（クラッシュしたサーバがクラスタに復帰する場合など）といった、特別な状況下では、
DGC はたとえ無効化されていても自動的に実行されます。
51.8.2 DGCの監視とトラブルシューティング DGC イベント（定期的とインライン両方）は、Terracotta サーバインスタンスのログに記録されま
す。また、DGC イベントは Terracotta 管理コンソールでも監視できます。
DGC が予定通りにオブジェクトのコレクションを行なっていない場合は、以下の理由が考えられま
す。
• Java GC がオブジェクトのコレクションを実行する速度が遅い。クライアントノードにリソー
ス負荷がかかっており、GC が遅れており、それにより DGC の実行も遅れている。
353
• クライアントノードによっては、他のノードでガベージになったオブジェクトに対して参照し
続けるものもあるため、DGC がこれらのオブジェクトについてコレクションを行なえない。
可能ならば、すべての Terracotta クライアントをシャットダウンし、DGC がコレクションの対象で
あったオブジェクトを処理するか確認してください。
52 Terracotta構成情報リファレンス
52.1 はじめに
このドキュメントは Terracotta 構成情報ファイルのリファレンスガイドです。ファイル内で使用さ
れる Terracotta 構成情報のすべての要素を紹介します。Terracotta 構成情報のデフォルトのファイ
ル名は tc-config.xml です。
最初は、キットに同梱されているサンプルの構成情報をベースに、利用する Terracotta 構成情報を
作成してください。サンプルには、一部の構成要素の説明するコメントが挿入されています。独自
の構成情報を作成するには「クリーンな」ファイルを使用します。
Terracotta 構成情報ファイルは XML ドキュメントです。内容は、<servers>と<clients>という 2 つ
のセクションに大別できます。各セクションには、そのセクションに必要な構成情報オプションを
記述します。
52.2 構成情報の変数
一部の構成情報には、変数を指定できます。構成情報のサブシステムは、これらの変数をローカル
の値に置き換えて使用します。
変数 置き換え後の値
%h ホストの完全修飾名
%i IP アドレス
%o オペレーティングシステム
%v オペレーティングシステムのバージョン
%a CPU アーキテクチャー
%H アプリケーションを実行するユーザーのホームディレクトリ
%n アプリケーションを実行するユーザーのユーザー名
%o 一時ディレクトリのパス（例：*NIX の「/tmp on」）
%D タイムスタンプ（形式は「yyyyMMddHHmmssSSS」）
354
%(system property) "systemProperty"に指定した Java システムプロパティの値
以下の要素や属性に、環境に合わせた値を設定したい場合は、これらの変数を利用して値を記述し
ます。
• <server>要素の name、host、および bind 属性。
• JMX 認証で使用するパスワードファイルの場所
• クライアントログの場所
• サーバログの場所
• サーバデータの場所
変数「%i」は、ホストのネットワーク設定で決められている値に置き換えられます。hosts ファイ
ルには、さまざまなマッピングも定義できます。これらのマッピングが、「%i」の変換結果に影響
を与える場合もあります。したがって、「%i」は、実際の環境で正しく変換されることを確認して
から使用してください。
注意：「%i」の値
52.3 パスの指定方法
一部の構成要素には、値としてパスを指定するものがあります。こうした要素に相対パスを指定す
ると、現在の作業ディレクトリ（つまり、サーバを起動したディレクトリ）からの相対パスとして
解釈されます。できる限り絶対パスを使用することをお勧めします。
52.4 tc.propertiesのオーバーライド
Terracotta 製品をインストールすると、システムプロパティを記録したデフォルトの tc.propertiesもインストールされます。これらの tc.properties の内容は事前にチューニングが施されています。
したがって、修正はしないでください。
ただし、一部のプロパティは tc-config.xml でチューニングできます。このファイルに値を指定すれ
ば、tc.properties の内容をオーバーライドできます。このほうが、本番環境では効率的に機能しま
す。tc-config.xml. に定義したシステムプロパティを、クライアントにプッシュ配信できるからです。
通常、こうしたシステムプロパティは、クライアントごとに最適化した個別の値を設定する必要が
あります。
52.4.1 tc-configのシステムプロパティの設定方法 すべてのクライアントに同じ値を設定するシステムプロパティは、Terracotta サーバの tc-config.xml ファイルで設定できます。このための構成要素は、以下の形式で記述してください。
355
<property name="<tc_system_property>" value="<new_value>" />
すべての<property />タグは、tc-config.xml ファイル先頭の<tc-properties>セクションの中に記述し
ます。
例えば、システムプロパティの l1.cachemanager.enabled と l1.cachemanager.leastCount をオーバー
ライドするには、tc-config.xml の先頭に以下のプロパティを記述します。
<tc-properties> <property name="l1.cachemanager.enabled" value="false" /> <property name="l1.cachemanager.leastCount" value="4" /> </tc-properties>
52.4.2 オーバーライドの優先度 tc-config.xml で定義したシステムプロパティは、Terracotta キットに同梱されているデフォルトの
tc.properties プロパティファイルの設定をオーバーライドします。デフォルトの tc.properties ファ
イルは編集しないでください。また、移動もしないでください。
ほかに、Terracotta の lib ディレクトリにローカルの tc.properties ファイルを作成し、そこにシス
テムプロパティを指定する方法もあります。このファイルのシステムプロパティは、デフォルトの
tc.properties の設定よりも優先的に使用されます。また、このローカルの tc.properties で指定した
システムプロパティは、tc-config.xml で指定したシステムプロパティも優先的に使用されます。
Java の-D オプションで指定したシステムプロパティは、ほかのすべてのシステムプロパティより
も優先します。上に紹介したシステムプロパティに加えて、コマンドラインやスクリプトから-Dcom.tc.l1.cachemanager.leastcount=5 オプションを指定した場合、tc-config.xml と tc.properties の
両方の指定値をオーバーライドします。システムプロパティの優先度の低い順から並べると、以下
のようになります。
1. デフォルトの tc.properties
2. tc-config.xml
3. Terracotta の lib ディレクトリにユーザーが作成した、ローカルの tc.properties ファイル
4. Java 起動時に-D オプションで指定したシステムプロパティ
52.4.3 オーバーライドできない場合 tc-config.xml でデフォルトのシステムプロパティをオーバーライドできない場合、Terracotta ログ
に警告が記録されます。警告の形式は以下のとおりです。
The property <system_property_name> was set by local settings to <value>. This value will not be overridden to <value> from the tc-config.xml file.
356
Terracotta 初期化の早い段階で使用されるシステムプロパティは、オーバーライドできない場合が
あります。この場合も、Terracotta ログに警告が記録されます。警告の形式は以下のとおりです。
The property <system_property_name> was read before initialization completed.
ログの警告の直前には、<system_property_name>に割り当てられている値が記録されます。
注意：プロパティの tc.management.mbeans.enabled は、初期化が完了する前にロードされます。し
たがって、オーバーライドできません。
52.5 構成情報のセクション
servers セクションには、TSA（Terracotta サーバアレイ）そのもの構成情報と、TSA の構成要素と
して利用するサーバインスタンスの情報を記述します。
52.5.1 /tc:tc-config/servers クラスタの構成要素として利用する Terracotta サーバインスタンスを定義するセクションです。こ
のセクションには、複数のサーバインスタンス定義を記述できます。<servers>要素の直下に記述す
る場合と、「<mirror-group>（ミラーグループ）」を定義して、その中に記述する場合があります。
このセクションを省略すると、デフォルトの構成情報を利用する単一サーバインスタンスを定義し
たときと同じ構成になります。
このセクションには、すべてのサーバの動作に影響するグローバルな構成情報も設定します。この
設定には secure. が含まれます。このプロパティは、クラスタ全体に対する) 「SSL によるセキュリ
ティ設定」を有効化（"true")または無効化("false")します。デフォルト値は"false"です。
52.5.2 /tc:tc-config/servers/server <server>は、Terracotta サーバインスタンスの構成情報を設定するセクションです。<server>要素
には、3 種類の属性を指定します。以下のテーブルを参照してください。
属性 定義内容 値 デフォルト値
host Terracotta サーバのホストマシンのアド
レス。 ホストマシンの IP アドレ
ス、あるいは解決可能なホス
ト名。
ホストマシンの
IP アドレス
name Terracotta サーバ名として使用する文字
列。ここでは指定せず、start-tc-server の
-n <name>で指定する方法もあります。
ユーザーが指定した文字列 :
bind クライアントのネットワークトラフィッ
クとして Terracotta サーバが検出するネ
ットワークインターフェース。すべての
インターフェースを検出する場合は
"0.0.0.0"を指定します。
インターフェースの IP アド
レス 0.0.0.0
357
サーバを起動する前に、各 Terracotta サーバインスタンスがどの構成情報を利用するのかを決定し
ておく必要があります。サーバに割り当てた名前が、そのサーバを実行するホストの名前と同じで、
そのホストが他のサーバインスタンスを実行しない場合、サーバに対応する構成情報は自動的に決
まります。
Terracotta 構成情報ファイルのサーバ情報の指定方法は、「Terracotta 構成情報ファイルの編集」
を参照してください。
構成情報のサンプル（一部のみ）
<server> <!-- my host is '%i', my name is '%i:tsa-port', my bind is 0.0.0.0 --> ... </server> <server host="myhostname"> <!-- my host is 'myhostname', my name is 'myhostname:tsa-port', my bind is 0.0.0.0 --> ... </server> <server host="myotherhostname" name="server1" bind="192.168.1.27"> <!-- my host is 'myotherhostname', my name is 'server1', my bind is 192.168.1.27 --> ... </server>
52.5.3 /tc:tc-config/servers/server/data この要素では、データ永続化で使用するデータの格納場所（パス）を設定します。
デフォルト値： data（作業ディレクトリの下に data というディレクトリが作成されます。）
52.5.4 /tc:tc-config/servers/server/logs このセクションでは、サーバが出力するログの格納場所を設定します。
デフォルト値： logs（作業ディレクトリの下に logs というディレクトリが作成されます。）
ほかに、stderr:または stdout:も、ログメッセージの出力先に指定できます。以下に例を示します。
<logs>stdout:</logs>
ログレベルの設定方法は「FAQ」を参照してください。
52.5.5 /tc:tc-config/servers/server/index この要素では、サーバによる検索で使用するインデックスの格納場所（パス）を設定します。
デフォルト値： index（作業ディレクトリの下に index というディレクトリが作成されます。）
358
52.5.6 /tc:tc-config/servers/server/data-backup この要素では、バックアップを起動した際、サーバが作成するバックアップの格納場所（パス）を
設定します。
デフォルト値： data-backup（作業ディレクトリの下に data-backup というディレクトリが作成さ
れます。）
52.5.7 /tc:tc-config/servers/server/tsa-port このセクションでは、クライアントのネットワークトラフィックの検出のために Terracotta が使用
するポートを設定します。
「tsa-port」のデフォルト値は"9510"です。
構成情報のサンプル（一部のみ）
<tsa-port>9510</tsa-port>
52.5.8 /tc:tc-config/servers/server/jmx-port このセクションでは、Terracotta サーバの JMX コネクターが検出で使用するポートを設定します。
「jmx-port」のデフォルト値は"9520"です。「tsa-port」を設定した場合、「tsa-port」に設定した
値に 10 を加えた値が「jmx-port」のデフォルト値になります。
構成情報のサンプル（一部のみ）
<jmx-port>9520</jmx-port>
52.5.9 /tc:tc-config/servers/server/tsa-group-port このセクションでは、Terracotta サーバが別の Terracotta サーバとの通信に使用するポートを設定
します。
「tsa-group-port」のデフォルト値は"9530"です。「tsa-port」を設定した場合、「tsa-port」に設定
した値に 20 を加えた値が「tsa-group-port」のデフォルト値になります。
構成情報のサンプル（一部のみ）
<tsa-group-port>9530</tsa-group-port>
52.5.10 /tc:tc-config/servers/server/security このセクションでは、SSL、デジタル証明書、ノード認証と承認によって保護されたクラスタを運
用するために必要な情報を設定します。
構成情報のサンプルは「Terracotta クラスタのセキュリティ設定」を参照してください。
/tc:tc-config/servers/server/security/ssl/certificate
この要素では、証明書のエントリーと証明書ストアの場所を設定します。形式は以下のとおりです。
359
<store-type>:<certificate-alias>@</path/to/keystore.file>
Terracotta 3.7 以降では、JKS（Java キーストア）の型がサポートされています。
/tc:tc-config/servers/server/security/keychain
この要素には、以下の子要素を指定します。
• <class>：キーチェーンファイルを定義するクラスを設定します。このクラスを省略すると、
com.terracotta.management.keychain.FileStoreKeyChain が使用されます。
• <url>：キーチェーンファイルの URI を指定します。キーチェーンを定義するファイルに、こ
の値が渡されます。
• <secret-provider>：com.terracotta.management.security.SecretProviderBackEnd のユーザー実
装の完全修飾パスを指定します。このクラスが、キーチェーンファイルの読み込みと提供を行
います。
/tc:tc-config/servers/server/security/auth
この要素には、以下の子要素を指定します。
• <realm>セキュリティレルムを定義するクラスを設定します。このクラスを省略すると、
com.tc.net.core.security.ShiroIniRealm が使用されます。
• <url>：セキュリティレルム構成情報ファイルの URI を指定します。セキュリティレルムを定
義するファイルに、この値が渡されます。LDAP または Microsoft アクティブディレクトリを
使用するように実装した場合は、代わりにそれらの URI を設定してください。
• <user>：このサーバが他のサーバへアクセスするときに使用するユーザー名を指定します。こ
の名前は、「.ini」ファイルに保存されている認証情報と一緒に使用されます。デフォルト値
は"terracotta"です。
/tc:tc-config/servers/server/security/management
この要素には、TMS（Terracotta 管理サーバ）が TSA との接続をセキュリティで保護するために必
要な子要素を指定します。
• ia： TMS のドメインで使用する HTTPS プロトコル用の URL を指定します。URL の最後には
/tmc/api/assertIdentity を指定し、さらにポート番号「9443」を指定します。
• timeout：サーバから TMS への接続で使用するタイムアウト値を指定します。単位は「ミリ秒」
です。
• hostname：サーバの DNS ホスト名が、サーバの証明書で使用されているホスト名と一致しな
い場合に使用します。一致しない場合、ここにサーバの DNS アドレスを使用してください。
360
52.5.11 /tc:tc-config/servers/server/authentication Terracotta サーバの JMX 認証を有効化します。空のタグ（<authentication />）を指定すると、標準
Java のデフォルト JMX 認証の仕組みを利用して、$JAVA_HOME/jre/lib/management のパスワード
とアクセスファイルを参照します。
$JAVA_HOME/jre/lib/management/jmxremote.password $JAVA_HOME/jre/lib/management/jmxremote.access
これらのファイルを、以下の手順に従って編集してください（存在しない場合は新規作成してくだ
さい）。
jmxremote.password：ファイルの最後に 1 行追加し、ユーザー名とパスワードを入力します。行
の最後には、改行コードを必ず挿入してください。
secretusername secretpassword
jmxremote.access：ファイルの最後に、以下の行を挿入します。行の最後には、改行コードを必ず
挿入してください。
secretusername readwrite
ファイルには適切なアクセス権限を設定してください。「*NIX」の例を以下に示します。
$ chmod 500 jmxremote.password $ chown <user who will run the server> jmxremote.password
JMX 認証以外を利用する方法は、「クラスタのセキュリティ」を参照してください。
52.5.12 /tc:tc-config/servers/server/http-authentication/user-realm-file Terracotta 内臓の HTTP サーバの認証を有効化します。有効化した場合は、HTTP サーバへのアク
セス権を持つユーザーと、対応するパスワードを含むプロパティファイルが必要になります。
プロパティファイルの内容は、以下の形式で記述します。
username: password [,rolename ...]
サポートされているロールと保護セクションは「* statistics」です（統計情報は/statistics-gathererに記録されます）。
パスワードは、クリアテキスト、難読化テキスト、またはチェックサムで記述します。パスワード
を難読化またはチェックサム化するには、com.mortbay.Util.Password クラスを使用してください。
デフォルトでは、HTTP 認証は無効化されています。
構成情報のサンプル（一部のみ）
361
<http-authentication> <user-realm-file>/opt/terracotta/realm.properties</user-realm-file> </http-authentication>
52.5.13 /tc:tc-config/servers/server/offheap この構成情報ブロックを利用するサーバは、オフヒープの使用を明示的に有効化しておく必要があ
ります。
<offheap> <enabled>true</enabled> <maxDataSize>512m</maxDataSize> </offheap>
<maxDataSize>に指定する値の最小値は 512MB です。この値には、サーバが利用できるメモリサイ
ズ（空き領域）の最大値を指定してください。ただし、物理メモリサイズを指定するわけではあり
ません。
BigMemory と高速再起動（データ永続化）を利用するには、オフヒープを有効化しておく必要があ
ります。
52.5.14 /tc:tc-config/servers/mirror-group ミラーグループとは TSA の「ストライプ」のことです。ミラーグループは、1 つのアクティブサー
バと 1 つ以上のミラーサーバ（バックアップサーバ）で構成されます。構成情報で<mirror-group>要素を定義しなかった場合、TSA が利用するストライプの数は 1 つです。
<servers> <server name="A"> ... </server> <server name="B"> ... </server> <server name="C"> ... </server> <server name="D"> ... </server> ... </servers>
362
この構成では、定義されたサーバの 1 つ（最初に稼働を開始したサーバ、あるいはアクティブとし
て選出されたサーバ）がアクティブサーバになります。それ以外はミラーサーバになります。通常
は、1 つまたは 2 つのミラーサーバがあれば十分です。アクティブサーバはミラーサーバと同期す
る必要があります。したがって、ミラーサーバの数が増えると負荷も大きくなります。
以下に示すのは、前述のサーバを 2 つのストライプに分割する構成設定の例です。
<servers> <mirror-group group-name="team1"> <server name="A"> ... </server> <server name="B"> ... </server> </mirror-group> <mirror-group group-name="team2"> <server name="C"> ... </server> <server name="D"> ... </server> </mirror-group> ... </servers>
各ストライプは、1 つのアクティブサーバと 1 つのミラーサーバで構成されます。
1 つの<servers>セクションには、複数の<server>または<mirror-group>を指定できます。ただし、
これらは同時に指定できません。<servers>のすべての構成情報はひとつのミラーグループとして機
能します。そのうち、ひとつはアクティブサーバ、残りはミラーサーバとなります。複数のストラ
イプを作成するには<server>下の<mirror-group>構成情報を使用します。こうすることにより、そ
のミラーグループの構成情報には複数の<servers>構成情報が含まれるようになります。
注意：サーバとミラーグループ
詳細情報や追加サンプルは、「Terracotta 構成情報ファイルの編集」を参照してください。
363
52.5.15 /tc:tc-config/servers/garbage-collection TSA で定期的に実行される DGC（分散ガーベジコレクション）の構成情報を設定するセクションで
す。DGC は、Java の GC（ガーベジコレクション）によって不要になった共有データを破棄する仕
組みです。
大部分の環境では、定期的な DGC は不要です。キャッシュには、自動的に効率的な GC を実行する
インライン DGC が組み込まれていて、通常はこの機能だけで十分です。読み取り処理の負荷が高
いアプリケーションでは、ガーベジとなる共有データはほとんどありません。したがって、定期的
な DGC は全く不要です。
しかし、Terracotta ツールキットのデータ構造が使用されているなど、一部の環境では、DGC を有
効化したほうがよいでしょう。なぜなら、インライン DGC はこれらのデータ構造を対象としてい
ないからです。
DGC の仕組みは「Terracotta サーバアレイのアーキテクチャー」を参照してください。
構成情報のサンプル（一部のみ）
<garbage-collection> <!-- Default: false --> <enabled>true</enabled> <!-- If "true", additional information is logged when a server performs distributed garbage collection. Default: false --> <verbose>false</verbose> <!-- How often should distributed garbage collection be performed, in seconds? Default: 3600 (60 minutes) --> <interval>3600</interval> </garbage-collection>
52.5.16 /tc:tc-config/servers/restartable TSA の共有データを永続化するに、高速再起動を明示的に有効化しておく必要があります。有効化
するには、以下の要素を指定します。
364
<restartable enabled="true"/>
高速再起動（共有データの永続化）を有効化すると、TSA で障害が発生したとき、クラスタの共有
データが TSA に再ロードされるようになります。
なお、この機能を利用するには、各サーバの<offheap>も有効化しておく必要があります。TSA デ
ータのバックアップを作成する場合にも、高速再起動を有効化しておく必要があります。
52.5.17 /tc:tc-config/servers/client-reconnect-window サーバから切断されたクライアントが再接続する際、同じクライアントとして再接続できるように
するための待機時間（期限）を定義するセクションです。この期限を過ぎると、クライアントは新
しいクライアントとして再接続します。選出時間の単位は秒で、デフォルト値は 120 秒です。
この値で指定する時間が短すぎると、障害回復時にうまく再接続できない現象が発生しやすくなり
ます。逆に長すぎると、待機時間が長くなるため、クラスタのパフォーマンス低下の原因になりま
す。これらを考慮した上で値を設定してください。
追加情報： Terracotta クラスタのクライアントとサーバの再接続の仕組みの詳細と、高可用性環境
における再接続プロパティのチューニングの詳細は、「Terracotta クラスタの可用性を高めるため
の構成設定」を参照してください。
52.6 構成情報の<clients>セクション
clients セクションには、各クライアントの動作を定義する構成情報を記述します。
52.6.1 /tc:tc-config/clients/logs Terracotta クライアントのログの出力先を定義するためのセクションです。
構成情報のサンプル（一部のみ）
<!-- This value undergoes parameter substitution before being used; thus, a value like 'client-logs-%h' would expand to 'client-logs-banana' if running on host 'banana'. See the Product Guide for more details. If this is a relative path, then it is interpreted relative to the current working directory of the client (that is, the directory you were in when you started the program that uses Terracotta services). It is thus recommended that you specify an absolute path here.
365
Default: 'logs-%i'; this places the logs in a directory relative to the directory you were in when you invoked the program that uses Terracotta services (your client), and calls that directory, for example, 'logs-10.0.0.57' if the machine that the client is on has assigned IP address 10.0.0.57. --> <logs>logs-%i</logs>
ほかに、stderr:または stdout:も、ログメッセージの出力先に指定できます。以下に例を示します。
<logs>stdout:</logs>
ログレベルの設定方法は「FAQ」を参照してください。
第 2 部 Terracotta管理コンソール
1 Terracotta管理コンソール TMC（Terracotta 管理コンソール）は、Web を利用して管理と監視を行うアプリケーションです。
TMC には以下の特徴があります。
• SSL による機密接続を利用したマルチレベルセキュリティのアーキテクチャー
• ブラウザを利用した多機能で使いやすいインターフェース
• ネットワーク接続するだけでブラウザから使用できるリモート管理機能
• 複数種類のプラットフォームへのデプロイ機能
• ロールを使った認証と承認
• LDAP ディレクトリと Microsoft Active Directory のサポート
• 複数ノードの情報を集計する統計
• 開発環境からセキュアな業務システムへの柔軟なデプロイ方法を提供するアーキテクチャーの
プラグイン
TMC は、Terracotta 管理サーバ（TMS）を使って BigMemory ノードやクラスタを監視します。 TMS はアグリゲーターとして動作し、TMC への接続とセキュリティコンテキストの提供を行いま
す。管理サービスを提供するには、TMC から TMS への接続を確保する必要があります。
366
TMS は、BigMemory のキットの「ツール／管理コンソール」ディレクトリに格納されています。
TMS を実行して TMC を読み込むのに、追加のインストール構成情報は必要ありません。
TMC の使用方法の詳細は、以下を参照してください。
• 「BigMemory ノードによる管理を有効化」
• 「TMC UI」
• 「セキュリティの設定」
• 「REST API への直接アクセス」
1.1 TMSのインストールと構成情報の設定
TMS ファイルは、BigMemory のキットの management-console ディレクトリに格納されています。
このディレクトリとすべてのコンテンツは TMS を実行する場所にコピーできます。また、ライセ
ンスファイルのコピーを management-console ディレクトリ内に配置してください。
1.1.1 異なるコンテナでの運用 TMS は以下のコンテナを使って直接実行することができます。ご希望のアプリケーションサーバで
TMS を実行するには、ファイル management-console/webapps/tmc.war を使います。選択したアプ
リケーションサーバの仕様と要件に従い、WAR を利用したアプリケーションを配備してください。
1.1.2 更新に関する統計情報の表示 デフォルトでは、分散キャッシュ（BigMemory Max）は、要素の書き込み（put）や更新があるた
びに書き込みイベントを生成します。TMC が書き込みとは別に更新を追跡、表示するようにするに
は、Terracotta サーバアレイを起動する前に、Terracotta 構成情報ファイル（デフォルトでは tc-config.xml）のトップにある Terracotta のプロパティ ehcache.clusteredStore.checkContainsKeyOnPutを以下のように設定します。
<tc-properties> <property name="ehcache.clusteredStore.checkContainsKeyOnPut" value="true" /> </tc-properties>
このプロパティを有効化すると、パフォーマンスは低下します。実際に運用する前に、このプロパ
ティを有効化することによる影響を検証してください。
1.1.3 TMCから複数のBigMemory GoのCacheManagerを使用する方法 1 つの JVM 内で動作する TMC の REST エージェントを使って複数の CacheManager インスタンス
をロードする場合は、CacheManager は異なるクラスローダーによりロードされる必要があります。
例えば 2 つの WAR など、2 つの異なるアプリケーションは、それぞれ異なるクラスローダーでロ
ードします。
367
1.1.4 TMCのアップデートチェッカー TMC は、アップデートチェッカーを使って最新のアップデートを自動的に確認します。また、TMCの利用状況も自動的に収集します。デフォルトでは、アップデートチェッカーが有効化されていま
す。アップデートチェッカーを無効化するには、以下のシステムプロパティを設定してください。
-Dcom.terracotta.management.skipUpdateCheck=true
1.2 TMSの更新
新しいバージョンの Terracotta のキットをインストールすると、TMS の更新版もインストールされ
ます。この新しいバージョンを起動すると、TMS は<user.home>/.tc/mgmt にある既存の構成情報
をチェックし、互換性のないファイルをバックアップします（拡張子「.bak」）。この場合、以前
構成設定した接続は TMC に表示されないので、再追加してください。
2 Terracotta管理コンソールのセキュリティの設定
2.1 はじめに
TMS（Terracotta 管理サーバ）には、様々な環境を簡単に統合するために、柔軟性のあるマルチレ
ベルセキュリティのアーキテクチャーがあります。
利用可能なセキュリティレベルは以下のとおりです。
• 認証なし：セキュリティによる保護が限定されている接続、あるいは保護されていない接続で
す。TMS が起動時に Terracotta のライセンスを見つけられない場合、または明確に有効とな
っていない Terracotta のライセンスを見つけた場合、セキュリティ設定のページは表示されず、
TMS も一切の認証なく稼働しますのでご注意ください。
• ロールを利用する認証：デフォルト値です。最初に TMS に接続した際に設定されるビルトイ
ンの認証です。TMS へのアクセス管理に使用します。標準 LDAP や Microsoft Active Directoryと統合した認証を利用することも可能です。
• BigMemory ノードを利用する認証： BigMemory Go ノードや BigMemory Max ノード（この場
合、エージェントまたは管理対象エージェントと呼びます）の認証と承認を利用する基本セキ
ュリティです。また、メッセージのハッシュコード化などの対策も使ってデータをプロテクト
します。
• SSL を利用する認証：基本認証と組み合わせて利用できます。
• 証明書を利用するクライアント認証： SSL を拡張した認証方式です。この認証方式では、基本
認証は無効です。
368
特に明記される例外を除き、これらの認証方式を自由に組み合わせて利用できます。複数の方式を
組み合わせた認証は、利用している環境のセキュリティレベルの向上に役立ちます。なお、以下に
示す点を除くと、このドキュメントでは正規ライセンス版 TMS のセキュリティ保護の仕組みを説
明します。
このドキュメントでは、TMS 側からみたセキュリティの仕組みを説明します。しかし、TMS と
TMC（Terracotta 管理コンソール）は、同じセキュリティコンテキストを利用して機能します。
2.2 セキュリティ保護なし
適切なライセンスを持つ TMC に初めて接続すると、認証セットアップのページが表示されます。
このページで、TMC を利用する際の認証の有無を選択します。
TMC が起動してから認証の有効化／無効化を切り替えるには、TMC 設定パネルを使用します。認
証を有効化すると、このドキュメントで説明されているセキュリティ機能すべてが利用可能になり
ます。
認証を有効化しなかった場合は、ログイン画面でパスワード入力をしなくとも TMC に接続できる
ようになります。
セキュリティを有効化しなくても、ブラウザと TMC との接続に「SSL 接続を強制」できます。
2.3 デフォルトのセキュリティ保護
デフォルトのセキュリティ保護では、ビルトインのロールに割り当てたアカウントを利用して TMCにログインします。このセキュリティレベルでは、ユーザーから TMC に対するアクセスだけが保
護されます。各コンポーネント間の通信（TMC、管理対象エージェント、各カスタム RIA などの間
の通信）が外部から保護されているネットワークで使用してください。外部から保護されていると
は、例えば、ファイアウォールの内側のイントラネットなど、全ての通信が信頼できる状態を指し
ます。管理対象エージェントと TMC との間の通信は、セキュリティで保護されません。
LDAP や Microsft Active Directory と統合したセキュリティオプションを使うことも可能です。詳し
い情報は、「Terracotta 管理コンソールのヘルプ」を参照してください。
2.4 基本セキュリティ接続
メッセージのハッシュ化を利用したビルトインの認証スキームとデジタル証明書（identity assertion(IA)）で、TMS と管理対象エージェントとの通信を保護します。外部のネットワークから
TMS にアクセスできる状態にある場合や、外部ネットワーク上の TMS から管理対象エージェント
にアクセスできる状態にある場合は、このレベルのセキュリティを使用してください。
注意： TMS と管理対象エージェント間のセキュリティ保護には、「SSL」を使った暗号化をお薦め
します。
369
次のステップを行い、IA をセットアップします。
• TMS のトラストストアをセットアップする
• 管理対象エージェントの IA を設定する
• TMS と管理対象エージェントの共通鍵を作成する
2.4.1 トラストストアのセットアップ TMS にはトラストストアが必要です。このトラストストアは TMS に接続するすべてのエージェン
トの公開鍵の証明書を格納します。認証局（公開鍵を提供します）を利用しない場合は、各エージ
ェントのキーストアにある自己署名証明書から公開鍵をエクスポートしてください。エキスポート
には以下のようなコマンドを使います。
keytool -export -alias myAgent -keystore keystore-file.jks \ -file myAgentCert.cert
この公開鍵を TMS のトラストストアにインポートします。トラストストアが存在しない場合は、
以下に示すように作成します。
keytool -import -alias myAgent -file myAgentCert.cert \ -keystore truststore.jks
管理対象エージェントにキーストアがない場合は、作成してください。作成例については、
「cluster security documentation」を参照してください。
これらの公開鍵を格納するトラストストアを作成したら、以下の方法で TMS が利用できるように
します。
• ${user.home}/.tc/mgmt/tms-truststore
• システムプロパティの javax.net.ssl.trustStore で設定した場所
または、JVM のデフォルトのトラストストア（通常は cacerts ファイル）にこれらの公開鍵をイン
ポートすることもできます。
注意： TMS 関連のファイルのデフォルトの配置場所を変更する必要がある場合は、システムプロ
パティの com.tc.management.config.directory で設定します。
2.4.2 IAの設定 IA の設定については、「TSA のセキュリティのセットアップ」参照してください。
Terracotta クライアントで IA を設定するには、管理対象エージェントの構成情報の
managementRESTService 要素に"securityServiceLocation"属性を追加して、REST サービスのセキュ
リティ（IA を使った認証）を有効化します。Ehcache の構成情報の例は以下のとおりです。
370
<ehcache ...> ... <managementRESTService enabled="true" securityServiceLocation="http://localhost:9889/tmc/api/assertIdentity" /> ... </ehcache>
"securityServiceLocation"を指定しないと、認証が有効になりません。有効化するには、TMC に接続
するのに使用した URI に/tmc/api/assertIdentity を追加した値を設定します。上の例では、
"http://localhost:9889"が TMC の URI です。
BigMemory Go でも、Terracotta クライアントと同様の方法で IA を設定します。
2.4.3 共通鍵の作成 TMS と管理対象エージェント間で共有するパスワード（または共通鍵）を作成し、Terracotta のキ
ーチェーンファイルに格納してください。
以下のステップで必要となるスクリプトは、${BIGMEMORY_GO_HOME}/management-console/binまたは${BIGMEMORY_MAX_HOME}/tools/security/bin で見つかります。Microsoft Windows の相当
するバッチファイルを使用しください。
TMS の共通鍵
1. 以下のスクリプトを実行し、TMS と管理対象エージェント間のトラストアサーションに使う
共通鍵を作成します。
./add-tc-agent.sh <agent-url>
<agent-url>にはエージェントの URL を記述します。この URL は、そのエージェントへのアク
セスで TMC が使用する URL を正確に記述します。以下に例を示します。
./add-tc-agent.sh http://localhost:9888
Microsoft Windows の場合は add-tc-agent.bat を使用してください。
Terracotta のキーチェーンファイル<user_home>/.tc/mgmt/keychain が存在しない場合は、こ
のスクリプトが自動的にファイルを作成します。TMS はこのキーチェーンファイルを使用し
ます。したがって、キーチェーンファイルを移動・削除しないでください。
2. プロンプトに対し、任意の共通鍵を入力します。ここで入力した共通鍵は、このあとの作業で
も使用します。
3. 各エージェントの URI を使い、それぞれについて「add-tc-agent」スクリプトを実行します。
スクリプトはこれらのエントリーを同じキーチェーンファイルに保存します。
371
管理対象エージェントの共通鍵
1. キーチェーンエントリーを持つ各エージェントは、Terracotta キーチェーンファイルを通じ、
同じ共通鍵にアクセスする必要があります。
./keychain.sh -c <user_home>/.tc/mgmt/agentKeychainFile \ http://myHost:9889/tc-management-api
/tc-management-api を加えた<tmc-url>は TMC に接続するための URI です。このノードに名前
付きのキーチェーンファイルが存在する場合は、-c オプションを省略してください。同じノー
ドで動作しているエージェントは、キーチェーンファイルを共有できます。
2. 以下のように、キーチェーンファイルのマスターキーを入力します。
Terracotta Management Console - Keychain Client KeyChain file successfully created in /path/to/agentKeychainFile Open the keychain by entering its master key:
3. TMS に割り当てた共通鍵を入力します。
Enter the password you wish to associate with this URL: Password for http://myHost:9889/ successfully stored
入力する共通鍵は TMS で入力したそれと一致しなくてはなりません。また、スクリプトの成
功通知はここで入力した共通鍵が TMS に格納したそれと一致するものであるかを確認するわ
けではありません。
2.5 SSLの追加
通信内容を傍受される可能性のある環境では、より高いレベルの認証を行うために、SSL による暗
号化を行います。基本セキュリティの堅牢性を強化するには SSL を使用します。
SSL の BigMemory への追加は、「TSA security setup page」を参照してください。
SSL を BigMemory Go に追加するには、以下のステップを行なってください。
1. 管理対象エージェントの構成情報を開き、RESTful なサービスの managementRESTService 要
素に sslEnabled 属性を追加し、値を"true"に設定します。
<ehcache ...> ... <managementRESTService enabled="true" securityServiceLocation="https://localhost:9889/tmc/api/assertIdentity" sslEnabled="true" />
372
... </ehcache>
2. 管理対象エージェントに ID ストアを指定します。デフォルトの保存場所は
${user.home}/.tc/mgmt/keystore です。変更するには、システムプロパティの y javax.net.ssl.keyStore で指定します。
サーバ認証で使用する証明書は、ID ストアに保存されます。ID ストアが見つからない場合、
管理対象エージェントは起動しません。
3. ID ストアのパスワードを、その管理対象エージェントの keychain に追加します。
パスワードのキーには、ID ストアのファイルの URI を指定してください。ほかに、システム
プロパティ javax.net.ssl.keyStorePassword での設定も可能です。パスワードが見つからない場
合、管理対象エージェントは起動しません。
4. TMS を実行する JVM には、同じサーバ認証の証明書が必要です。以下のいずれかの場所に保
存してください。
– JVM のデフォルトのトラストストア（通常は、JRE の「cacerts」ファイル）。
– ${user.home}/.tc/mgmt/tms-truststore
– システムプロパティの javax.net.ssl.trustStore で設定した場所
TMS に「トラストストアが既にセットアップ」されており、さらに必要とされる公開鍵がそ
こにある場合、このステップはスキップしてください。
5. TMS に「cacerts」でないトラストストアを使用する場合、トラストストアのパスワードも
TMS の keychain ファイルに含めてください。
パスワードのキーには、トラストストアのファイルの URI を使用します。ほかに、システム
プロパティ javax.net.ssl.trustStorePassword での設定も可能です。
2.6 証明書を使用するクライアント認証
「基本的なセキュリティ」のハッシュを利用するメッセージ認証スキーム以外にも、BigMemory Go ノードによる証明書を利用するクライアント認証を使うことができます。ただし、この認証方
法は Terracotta サーバアレイでは利用できません。
クライアント認証の自動セットアップはハッシュを利用する認証を無効化します。メッセージのハ
ッシュ化を使用する場合は「SSL によるセキュリティ」を利用してください。
「基本的なセキュリティ」と「SSL」説明されているように、すべての管理対象エージェントにキ
ーストアをセットアップし、TMS にはトラストストアをセットアップしてください。さらに、以下
373
の手順で説明するように、すべての管理対象エージェントにトラストストアをセットアップし、
TMS にもキーストアをセットアップしてください。
証明書を使用するクライアント認証の設定方法は以下のとおりです。
1. 管理対象エージェントの構成情報を開き、RESTful なサービスの managementRESTService 要
素に needClientAuth 属性を追加し、値を"true"に設定します。
<ehcache ...> ... <managementRESTService enabled="true" securityServiceLocation="http://localhost:9889/tmc/api/assertIdentity" sslEnabled="true" needClientAuth="true" /> ... </ehcache>
2. 管理対象エージェントにトラストストアを指定します。デフォルトの保存場所は
${user.home}/.tc/mgmt/truststore です。変更するには、システムプロパティの
javax.net.ssl.trustStore で指定します。
3. トラストストアのパスワードを、その管理対象エージェントの keychain に追加します。
パスワードのキーには、トラストストアのファイルの URI を使用します。ほかに、システム
プロパティ javax.net.ssl.trustStorePassword での設定も可能です。
4. TMS に ID ストアを指定します。デフォルトの保存場所は${user.home}/.tc/mgmt/tms-keystoreです。変更するには、システムプロパティの javax.net.ssl.keyStore で指定します。
管理対象エージェントに対する有効な証明書が見つからなかった場合、TMS はそのエージェ
ントを拒否します。
5. TMS の ID ストアのパスワードを、その「TMS の keychain」に追加します。
パスワードのキーには、ID ストアのファイルの URI を指定してください。ほかに、システム
プロパティ javax.net.ssl.keyStorePassword での設定も可能です。
6. 管理対象エージェントからの SSL 接続を許可するには、SSL コネクタの構成情報を設定する必
要があります。提供されている Jetty Web サーバに TMS が配備されている場合、（BigMemoryキット内の）/management-console/etc/jetty.xml に以下の部分を追加してください。
<Call name="addConnector"> <Arg> <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector"> <Arg> <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
374
<Set name="keyStore">/home/.tc/mgmt/tms-keystore</Set> <Set name="keyStorePassword"> OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set> <Set name="keyManagerPassword"> OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set> <Set name="TrustStore">/home/.tc/mgmt/tms-truststore</Set> <Set name="keyStorePassword"> OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set> <Set name="needClientAuth">true</Set> </New> </Arg> <Set name="port">9999</Set> <Set name="maxIdleTime">30000</Set> </New> </Arg> </Call>
この構成情報を設定する場合は、以下の注意が必要です。
– 異なるコンテナ上に TMS WAR を配備した場合は、そのコンテナに同等の変更を加えて
ください。
– 他のプロセスとの競合を防ぐため、未使用の SSL ポートを使用してください。
– 利用中の環境に合わせ、適切な値を maxIdletime に設定してください。
– デフォルトでないキーストアまたはトラストストアを使用する場合は、使用するキー
ストアとトラストストアのパスを設定してください。
– パスワードは、Jetty の標準ツールで難読化されています。
java -cp jetty-distribution/lib/jetty-util-8.1.9.v20130131.jar org.eclipse.jetty.util.security.Password myPassword
このコマンドは、難読化した myPassword を返します。TMC のルートディレクトリで実行す
る必要があります。
2.7 TMCクライアントにSSL接続の使用を強制する方法
TMC を Jetty Web サーバと同一マシン上に配備すると、Web ブラウザはセキュリティで保護されて
いない接続（ポート 9889 を使用する HTTP）を使って TMC にアクセスできます。SSL を利用した
接続は、ポート 9443 の HTTPS を使用することでも利用可能です。
375
すべての Web ブラウザに SSL 接続を強制的に行う場合、（BigMemory キット内の）/management-console/etc/jetty.xml で該当するコネクタをコメントアウトし、セキュリティで保護されていない
接続を無効にします。
<!-- DISABLED non-secure connector <Call name="addConnector"> <Arg> <New class="org.eclipse.jetty.server.nio.SelectChannelConnector"> <Set name="host"><Property name="jetty.host" /></Set> <Set name="port"><Property name="jetty.port" default="9889"/></Set> <Set name="forwarded">true</Set> <Set name="maxIdleTime">300000</Set> <Set name="Acceptors">2</Set> <Set name="statsOn">false</Set> <Set name="confidentialPort">8443</Set> <Set name="lowResourcesConnections">20000</Set> <Set name="lowResourcesMaxIdleTime">5000</Set> </New> </Arg> </Call> -->
異なるコンテナ上に TMC WAR を配備した場合は、そのコンテナに同等の変更を加えてください。
2.7.1 デフォルトのキーストア デフォルトでは、ビルトインの Jetty コンテナの構成情報ファイル（management-console/etc/jetty.xml）は同じディレクトリにある JKS ID ストアを使います。このキーストアの証
明書は、認証局の署名を取得していません。この（信頼できない）証明書を使ってアクセスを行う
には、各ブラウザ上で、この証明書を SSL 接続の「例外」として登録する必要があります。ブラウ
ザから初めて TMS に接続するときに、この設定を行ってください。
3 Terracotta REST API
3.1 はじめに
Terracotta 管理サーバ（TMS）には、管理 REST インターフェースが内蔵されています。このイン
ターフェースに対してカスタムスクリプトを書いたり、Terracotta 管理コンソール（TMC）の代わ
りにカスタムで Rich Internet Application（RIA）を作成できます。
376
ここでは、REST インターフェースのエージェントとやりとりをするのに使われる管理 REST API について説明します。
注意：説明を簡略化するために、ここで紹介する例では TMS がローカルで稼働していると仮定し
て、ホストアドレスには「localhost」を用いています。
3.2 管理サービスREST APIへの接続
TMS 上で動いている REST 管理サービスや REST エージェントが稼働しているノードに接続するこ
とによって、REST API を利用することができます。以下に記載の URL を使って接続します。
TMS に接続する場合
http://<host>:<port>/tmc/api
TMS がデフォルトのコンテナで稼働している場合、<port>は 9889 になります。ユーザー保有のコ
ンテナを使う場合は、そのコンテナに合わせてポートを設定してください。
スタンドアロンのノードに直接接続する場合
http://<host>:<port>/tc-management-api
<port>は、Ehcache 構成情報ファイル（デフォルトでは ehcache.xml）の
<managementRESTService>要素の属性で設定します。
TSA に接続する場合
http://<host>:<port>/tc-management-api
<port>は TSA グループのポートになります。この値は、Terracotta 構成情報ファイル（デフォルト
では tc-config.xml）内にあるサーバの<tsa-group-port>要素で設定します。デフォルトは 9530 です。
3.3 HTTP運用のためのURI構築
Terracotta 管理サービスに接続するのに使われる主な URI は、以下の形式で表されます。
<scheme>://<host>[:<port>]/<path>?<query>
スキームに「http」を使う、標準的なスキームとドメインからなる URI です。この URI を通じて
HTTP が REST API にアクセスします。URI は特定の状況のクエリ文字列を受け入れます。
3.3.1 URIパス URI の<path>部分には、以下の階層を使ってリソースの場所を指定します。
1. Agent IDs：クライアント固有の ID を使って必要なクライアントを羅列します。TMS への接続
で ID が何も指定されていない場合、既知のクライアントすべてにアクセスします。Terracotta
377
クライアントまたは TSA（スタンドアロンの REST サービス）に直接接続する場合は、ID を使
わずに host:port のアドレスで識別します。すべてのスタンドアロン REST インターフェース
（TSA を含む）が、エージェント ID として「embedded」を返します。
2. CacheManager names：キャッシュマネージャーとして設定されている名前を羅列します。URIに「cacheManagers」が含まれていながらその名前が指定されていない場合、指定クライアン
トのキャッシュマネージャーすべてにアクセスします。
3. Cache names：キャッシュとして設定された名前を羅列します。URI に「caches」が含まれて
いながらその名前が指定されていない場合、アクセス先のキャッシュマネージャーに該当する
キャッシュすべてにアクセスします。アクセスが広範囲にわたる場合、相当量のデータが GETオペレーションで戻ってくることがあります。
パスの構造は以下の形式をとります。
/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}] /caches[;names={comma_sep_cache_names}
エージェント ID は必要ありません。
3.3.2 特定リソースの配置 特定の監視や管理サービスを行うためのリソースの場所を配置します。
ディスカバリー
ディスカバリーの URI は、/agents/info. のパス形式をとります。この URI は TMS と一緒に使われ、
TMS に設定されている既知のエージェント全体のメタデータを返します。埋め込みの Web サービ
スを使って、該当エージェントのメタデータ（該当エージェントに届かない場合は 404）を返しま
す。ドキュメント内には、ディスカバリーURI のその他の特定利用方法の例が記載されています。
構成情報の確認
キャッシュマネージャーとキャッシュの構成情報を確認するための URI は、agents/cacheManagersパス形式または agents/cacheManagers/caches パス形式をとります。エージェントやキャッシュマ
ネージャー、キャッシュは、ID や名前を使って指定できます。データは XML 形式で返ってきます。
キャッシュマネージャーの構成情報を取得するには、以下の形式を使います。
/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}] /configs
キャッシュの構成情報を取得するには、以下の形式を使います。
/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}] /caches[;names={comma_sep_cache_names}/configs
378
構成情報の設定
リソース指定を使って特定のキャッシュ構成情報の属性を設定するために、キャッシュリソースの
場所を指定することもできます。設定できる属性の一覧は以下のとおりです。
• enabled：キャッシュオペレーションをブーリアンで有効化（true、デフォルト値）、または
無効化（false）します。たとえば、キャッシュオペレーションを無効化するには、PUT {"enabled":true}を使います。
• statsEnabled：キャッシュ統計の収集をブーリアンで有効化（true）、または無効化（false、デフォルト値）します。
• sampledStatsEnabled：キャッシュ統計のサンプリングをブーリアンで有効化（true）、または
無効化（false、デフォルト値）します。
新規接続 URI の調査
指定場所のエージェントの存在を調べるには、以下の URL 形式を使います。
http://127.0.0.1:9889/tmc/api/agents/probeUrl/$urlToProbe
たとえば、以下の URL は指定アドレス（localhost:4343）で稼動している REST エージェントの情
報を返します。
http://127.0.0.1:9889/tmc/api/agents/probeUrl/http%253A%252F%252Flocalhost%253A4343
該当エージェントが利用できる場合、以下のようなレスポンス(status code 200 AgentMetadataEntity)を返します。
{"agentId":"embedded","agencyOf":"Ehcache","available":true,"secured":false, "sslEnabled":false,"needClientAuth":false,"licensed":false,"sampleHistorySize":8640, "sampleIntervalSeconds":10,"enabled":false,"restAPIVersion":"2.7.0"}
利用できない場合は、ステータスコードは「204 No Content」になります。
認証モードの設定
認証ステータスは、${user.home}/.tc/mgmt/settings.ini. プロパティファイルに保存されています。
REST リソースを利用して、この情報を操作します（ON または OFF に設定）。この設定を変更し
た場合は、手動で TMS を再起動してください。
ステータスを取得するには、以下の URI を使います。
http://localhost:9889/tmc/api/config/settings/authentication
「true」または「false」を返します。
379
ステータスを変更(PUT 処理)するには、リクエストの body に”true”または”false”を設定して同じ
URL を呼び出してください。変更が成功すると、ステータスコード「200 OK」を返します。
リソースの場所を使う方法については、後述する URI の例を参照してください。
3.4 HTTPの仕様
URI にエージェント ID が何も指定されていない場合、既知のエージェントすべてが含まれます。
3.4.1 レスポンスヘッダー 標準的な HTTP リクエストでは、以下のようなレスポンスヘッダーとなります。
-- response -- 200 OK Content-Type: application/vnd.sun.wadl+xml Allow: OPTIONS,GET,HEAD Content-Length: 602 Server: Jetty(7.5.4.v20111024)
3.4.2 URIの例 管理サービス REST API の順応性により、URI 構文を柔軟に利用できます。特定の URI に対応する
HTTP レスポンスの例の一覧は以下のとおりです。この一覧の各 HTTP が返すデータの例について、
レスポンスヘッダー以外の部分をそれぞれ示します。
3.4.3 DELETE キャッシュなど特定のリソースを削除します。
使用例
以下の DELETE 例は、タスクと URI で構成されています。
キャッシュを削除する
/agents;id=client01/cacheManagers;names=foo/caches;names=bar
Ehcache ノード「client01」にあるキャッシュマネージャー「foo」からキャッシュ「bar」を削除し
ます。
キャッシュ統計を消去する
/agents;id=client01/cacheManagers;names=foo/caches;names=bar/configs
キャッシュ「foo」に関するすべてのキャッシュ統計を消去し、カウンターをゼロにリセットしま
す。
DELETE によって出力される HTTP ステータスコード
380
400：URI はリソースを一つも指定していません。 404：URI に指定されたリソースが見つかりま
せん。
3.4.4 GETとHEAD 指定されたリソースすべての詳細を表す JSON 配列、または XML 形式のデータの XML 記述を返し
ます。
注意： HEAD オペレーションは GET オペレーションと同じメタデータを返しますが、ボディはあ
りません。
使用例
以下の GET の例は、タスクと URI で構成されています。
既知のエージェントをすべて見つける
/agents/info
この URI は TMS と一緒に使われ、TMS に設定されている既知のエージェント全体のメタデータを
返します。埋め込みの Web サービスを使って、該当エージェントにあるメタデータを返します。
以下は、エージェント「foo」と「goo」が設定された TMS で両方のエージェントが応答した場合
のレスポンスの例を表しています。
[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"}, {"restAPIVersion":"1.0.0","available":true,"agentId":"goo","agencyOf":"Ehcache"}]
以下は、エージェント「foo」と「goo」が設定された TMS で「foo」だけが応答している場合のレ
スポンスの例を表しています。
[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"}, {"restAPIVersion":null,"available":false,"agentId":"goo","agencyOf":null}]
なお、返すメタデータには、エージェントで稼動する API のバージョンとその API が提供するクラ
イアントのタイプ「agencyOf」が含まれます。
特定のエージェントの詳細を取得する
/agents;ids=client01,client02
JSON は、利用できるエージェントすべての詳細の配列を表しています。エージェント ID が一つも
含まれていない場合、利用できるエージェントすべてを返します。
特定のキャッシュの詳細を取得する
/agents;ids=client01/cacheManagers;names=foo/caches;names=bar
381
特定のキャッシュマネージャーの構成情報を取得する
/agents;ids=client01/cacheManagers;names=foo/configs
キャッシュマネージャー「foo」の XML 文書を返します。たとえば、スタンドアロンの Ehcache ノ
ードが返した XML 文書の例は以下のとおりです。
<configurations agentId="embedded" version="1.0.0-SNAPSHOT"> <configuration cacheManagerName="foo"> <ehcache maxBytesLocalDisk="300M" maxBytesLocalHeap="100M" maxBytesLocalOffHeap="200M" monitoring="on" name="CM1"> <diskStore path="/var/folders/nn/lxsg77756534qfn7z14y5gtm0000gp/T/"/> <managementRESTService bind="0.0.0.0:9889" enabled="false"/> <defaultCache maxElementsOnDisk="10000" overflowToOffHeap="true" statistics="true"> <elementValueComparator class="net.sf.ehcache.store.DefaultElementValueComparator"/> <terracotta/> </defaultCache> <cache diskPersistent="true" name="Cache11" overflowToDisk="true" statistics="true"> <elementValueComparator class="net.sf.ehcache.store.DefaultElementValueComparator"/> <terracotta clustered="false"> <nonstop/> </terracotta> </cache> <terracottaConfig url="localhost:9510"/> </ehcache> </configuration> </configurations>
特定のターゲットに対してしか実行できないオペレーションがあります。複数のエージェントやキ
ャッシュマネージャー、キャッシュを指定すると、エラーレスポンス（code 400）となります。
特定のキャッシュの構成情報を取得する
/agents;ids=client01/cacheManagers;names=foo/caches;names=baz/configs
すべてのキャッシュマネージャー詳細を取得する
/agents/cacheManagers
以下の例は、２つのキャッシュマネージャー（それぞれにキャッシュ１つ）を有する Ehcache ノー
ドに対して GET が実行されたときに、この URI が返した JSON オブジェクトを示しています。
[{"name":"CM2","attributes":{"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed"," Enabled":true,"HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M","
382
CacheAverageSearchTime":0,"CachePutRate":84,"CacheOnDiskHitRate":0, "CacheMetrics":{"Cache12":[2,84,84]}, "CacheRemoveRate":0,"CacheOffHeapHitRate":0,"Searchable" :false,"CacheOnDiskMissRate":84,"CacheNames":["Cache12"]," TransactionRolledBackCount":0,"CacheInMemoryHitRate":2,"WriterQueueLength":0," CacheOffHeapMissRate":0,"Transactional":false,"CacheHitRate":2," TransactionCommitRate":0,"CacheExpirationRate":0,"CacheUpdateRate":0," MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.027891714," TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":84," MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M"," CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0," Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0," StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":84}," agentId":"embedded","version":"1.0.0-SNAPSHOT"},{"name":"CM1","attributes": {"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed","Enabled":true," HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M"," CacheAverageSearchTime":0,"CachePutRate":166,"CacheOnDiskHitRate":8," CacheMetrics":{"Cache11":[7,83,83],"Cache12":[6,83,83]},"CacheRemoveRate":0," CacheOffHeapHitRate":0,"Searchable":false,"CacheOnDiskMissRate":166,"CacheNames" :["Cache11","Cache12"],"TransactionRolledBackCount":0,"CacheInMemoryHitRate":5," WriterQueueLength":0,"CacheOffHeapMissRate":0,"Transactional":false," CacheHitRate":13,"TransactionCommitRate":0,"CacheExpirationRate":0," CacheUpdateRate":0,"MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.061820637, "TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":174," MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M"," CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0," Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0," StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":166}, "agentId":"embedded","version":"1.0.0-SNAPSHOT"}]
特定のキャッシュマネージャー詳細を取得する
/agents/cacheManagers?show=CacheInMemoryHitRate&show=CacheHitRate&show=CacheAverageGetTime
この URI は、指定した統計のみで JSON 配列を返します。
[{"name":"CM1","attributes":{"CacheAverageGetTime":0.26357448,"CacheHitRate":47, "CacheInMemoryHitRate":3},"agentId":"embedded","version":"1.0.0-SNAPSHOT"}]
構成情報の属性（たとえば、MaxBytesLocalHeap も show クエリパラメーターで指定できます。
383
GET によって出力される HTTP ステータスコード
404：指定されたリソースが見つかりません。
3.4.5 OPTIONS 指定したリソースで利用できるオペレーションすべてを表す WADL を取り出します。
使用例
以下の OPTIONS の例は、タスクと URI で構成されています。スタンドアロンのノードに対して実
行された場合のベース URI は「/tc-management-api/」で終わり、TMS に対して実行された場合の
ベース URI は「/tmc/api/」で終わります。
利用可能なエージェントオペレーションで WADL を返す
/agents;ids=client01,client02
埋め込みエージェントが返した WADL の例は以下のとおりです。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.9.1 09/14/2011 02:05 PM"/> <grammars/> <resources base="http://localhost:9888/tc-management-api/"> <resource path="agents"> <method name="GET" id="getAgents"> <response> <representation mediaType="application/json"/> </response> </method> <resource path="/info"> <method name="GET" id="getAgentsMetadata"> <response> <representation mediaType="application/json"/> </response> </method> </resource> </resource> </resources> </application>
384
利用可能なキャッシュマネージャー「Config」オペレーションで WADL を返す
/agents/cacheManagers/configs
/configs を使った OPTIONS
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.9.1 09/14/2011 02:05 PM"/> <grammars/> <resources base="http://localhost:9888/tc-management-api/"> <resource path="agents/cacheManagers/configs"> <method name="GET" id="getCacheManagerConfig"> <response> <representation mediaType="application/xml"/> </response> </method> </resource> </resources> </application>
特定のキャッシュにある利用可能なオペレーションで WADL を返す
/agents/cacheManagers;names=foo,goo/caches;names=bar
TMS がアクセスできるエージェント上のキャッシュマネージャー「foo」と「goo」から、キャッシ
ュ「bar」にある情報を返します。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.9.1 09/14/2011 02:05 PM"/> <grammars/> <resources base="http://localhost:9889/api/"> <resource path="agents/cacheManagers;names=foo,goo/caches;names=bar"> <method name="GET" id="getCaches"> <response> <representation mediaType="application/json"/> </response> </method> <method name="PUT" id="createCache"/>
385
<method name="DELETE" id="deleteCache"/> <resource path="/statistics"> <method name="DELETE" id="wipeStatistics"/> </resource> </resource> </resources> </application>
特定のエージェントからの情報については、該当エージェントの ID を指定します。
/agents;ids=client01,client02/CacheManagers=foo,bar/caches=baz,goo
上記のように WADL を返し、さらに詳細なリソースの場所（とキャッシュ）も返します。
埋め込みの Web サービスを使って、該当するエージェントで見つかった指定キャッシュの情報を
この URI で返します。
3.4.6 PUT 指定したリソースの作成やリソース形態の変更を行います。
リソースの変更
リソース形態の変更とは、以下のキャッシュ属性のいずれかの値をブーリアンで変更することを意
味します。
• Enabled：キャッシュを有効化（true、デフォルト値）または無効化（false）します。
• StatisticsEnabled：キャッシュの統計収集を有効化（true、デフォルト値）または無効化（false）します。統計を無効化すると、キャッシュの処理能力を改善できますが、監視能力が制限され
ます。なお、統計を無効化すると、サンプリングした統計も自動的に無効化されます。
• SampledStatiscsEnabled：サンプリングした統計を有効化（true、デフォルト値）または無効
化（false）します。サンプリングした統計は、平均値や合計値などの値を出すのに使われます。
サンプリングした統計を有効化すると、統計収集も自動的に有効化されます。
使用例
新しいキャッシュを作成する
/agents;ids=MyConnectionGroup_MyEhcache/cacheManagers;names=foo/caches;names=baz
この URI で、エージェント ID「MyConnectionGroup_MyEhcache」の Ehcache ノード上のキャッシ
ュマネージャー「foo」内にキャッシュ「baz」を作成します。「baz」にはデフォルトのキャッシ
ュ構成情報が含まれています。
キャッシュの属性を更新する
386
/agents;ids=MyConnectionGroup_MyEhcache/cacheManagers;names=foo/caches;names=baz
この URI で、コンテンツに指定したとおりにキャッシュ属性を変更できます。たとえば、キャッシ
ュ「baz」の統計収集を停止するには、以下のコンテンツを使います。
{"attributes":{"StatisticsEnabled":false}}
キャッシュの構成情報の変更に関する情報は、「リソースの変更」を参照してください。
PUT によって出力される HTTP ステータスコード
201：オペレーションは成功しました。 204：キャッシュは正常に変更されました。 400：URI はリソースを一つも指定していません。 409：指定した名前のリソースがすでに存在しています。
3.5 URIでクエリパラメーターを使う
GET と HEAD の HTTP オペレーションを使って、特定のリソース上でクエリを実行できます。
show パラメータを使って、クエリパラメーターを実行します。
/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}] /caches[;names={comma_sep_cache_names}?show=[parameter]&show=[parameter]
たとえば、ID が「foo」の Ehcache にあるキャッシュマネージャー「CM1」の
HasWriteBehindWriter パラメーターと MaxBytesLocalDiskAsString パラメーターの値を取り出すに
は、以下を使います。
/agents;ids=foo/cachemanagers;names=CM1?show=HasWriteBehindWriter? show=MaxBytesLocalDiskAsString
このクエリで以下のような JSON オブジェクトを返します。
[{"name": "CM1","attributes": {"HasWriteBehindWriter":true, "MaxBytesLocalDiskAsString":"300M"},"guid":"95d40b093c9f44389f3cc122fbe1c30b", "agentId":"embedded","version":"1.0.0"}]
3.6 APIのバージョン
REST API はすべて、機能差や性能差による潜在的な問題を避けるために同じバージョンでなけれ
ばなりません（「バージョンの不一致」セクションを参照してください）。REST API のバージョ
ンは、Terracotta 製品および Terracotta の他の API のバージョンとは関係ありません。
接続している REST エージェントの API バージョンを確認するには、GET オペレーションで
「/agents/info」の URI を使います。
387
3.6.1 バージョンの不一致 REST API のバージョンの違いによって、作成する監視ツールの特長や機能性に影響が出ることが
あります。時間が経つにつれ、TMS と TSA（外部 TMS を使用している場合）の間で、あるいは
TMS とスタンドアロンのノード間でバージョンの不一致が問題になることがあります。
TMS は、利用できる機能だけを提供することによって、TMS よりも古いバージョンの API でエー
ジェントを補う場合があります。エージェントの API バージョンのほうが新しい場合、TMS が新し
いスキーマや機能性、API 間の違いに対応できず、不整合や誤動作を起こす可能性があります。
3.7 JSONスキーマ
REST API が返す JSON オブジェクトを構文解析するために、またスクリプトや RIA がエージェント
に送るデータ構造の正当性を確認するために、JSON スキーマをガイドとして使います。
スキーマは、API のバージョンによって変わることがあります。REST API の URI を使って、以下の
JSON スキーマの例を取得できます。
• cacheManager
• cache
• cacheConfig
• cacheStatisticsSample
3.8 TSA向けREST API
REST API を使って、接続された TSA に関して TMS にクエリを行うことができます。
3.8.1 統計 ベースの「/agents/statistics」に以下の URI 拡張を追加すると、統計情報を返すようになります。
DGC 実行
DGC の直近 1000 回分の統計を取得します。
/dgc
サーバの統計
サーバ a、b、c に対する統計 k、l、m を取得します。
/servers;names=a,b,c?show=k,l,m
「names」に何も指定しないと、すべてのサーバに対する統計がリクエストされます。「show」が
省略された場合、すべての統計がリクエストされます。
388
クライアントの統計
クライアント x、y、z に対する統計 k、l、m を取得します。
/clients;ids=x,y,z?show=k,l,m
「ids」に何も指定しないと、すべてのクライアントに対する統計がリクエストされます。「show」
が省略された場合、すべての統計がリクエストされます。
3.8.2 トポロジの確認 ベースの「/agents/topologies」に以下の URI 拡張を追加すると、トポロジの情報を返すようにな
ります。
完全なクラスタトポロジ（すべてのサーバとクライアント）を取得するには、ベース拡張の後にス
ラッシュ「/」をつけます。
/agents/topologies/
サーバ a、b、c に関するものだけ取得するには、以下を追加します。
/servers;names=a,b,c
「names」に何も指定しないと、すべてのサーバが含まれます。
クライアント x、y、z に関するものだけ取得するには、以下を追加します。
/clients;ids=x,y,z
「ids」に何も指定しないと、すべてのクライアントが含まれます。
3.8.3 構成情報 ベースの「/agents/configurations」に以下の URI 拡張を追加すると、構成情報を返すようになりま
す。
すべてのサーバとクライアントに関する構成情報を取得するには、ベース拡張の後にスラッシュ
「/」をつけます。
/agents/configurations/
サーバ a、b、c に関するものだけ取得するには、以下を追加します。
/servers;names=a,b,c
「names」に何も指定しないと、すべてのサーバが含まれます。
クライアント x、y、z に関するものだけ取得するには、以下を追加します。
/clients;ids=x,y,z
389
「ids」に何も指定しないと、すべてのサーバが含まれます。
3.8.4 診断 ベースの「/agents/disagnostics」に以下の URI 拡張を追加すると、トラブル診断に役立つ情報を返
したり、DGC サイクルを起動させることができます。
スレッドダンプ
すべてのサーバとクライアントからスレッドダンプ全体を取得します。
/threadDump
サーバ a、b、c からスレッドダンプを取得するには、以下を追加します。
/threadDump/servers;names=a,b,c
「names」に何も指定しないと、すべてのサーバが含まれます。
クライアント x、y、z からスレッドダンプを取得するには、以下を追加します。
/threadDump/clients;ids=x,y,z
「ids」に何も指定しないと、すべてのクライアントが含まれます。
DGC サイクル
DGC サイクルを起動するには、以下を入力します。
/dgc
3.8.5 バックアップ 以下の URI 拡張を入力して、クラスタデータのバックアップを開始します。
/agents/backups/
バックアップのステータス（バックアップが進行中の場合、true）を取得するには、同じ URI にGET オペレーションを使います。
/agents/backups/
バックアップ作業は TSA 全体にかかるため、特定のサーバに委任することはできません。
3.8.6 オペレーターイベント URI 拡張「/agents/operatorEvents」を使って、オペレーターイベントを返すことができます。返
すデータの量を制限するには、sinceWhen クエリを使います。
最近 10 分間のオペレーターイベントを取得するには、以下を使います。
/agents/operatorEvents?sinceWhen=10m
390
3.8.7 ログ URI 拡張「/agents/logs」を使って、ログを返すことができます。返すデータの量を制限するには、
sinceWhen クエリを使います。
最近 10 分間のログを取得するには、以下を使います。
/agents/logs?sinceWhen=10m
付録
1 Terracotta管理コンソールのヘルプ TMC（Terracotta 管理コンソール）は、Web を利用して Terracotta 製品の管理と監視を行うアプリ
ケーションです。TMC の接続は、Terracotta 管理サーバ（TMS）が管理します。TMC を使用するに
は、TMS を実行しておく必要があります。
稼働している TMC のバージョンを確認したり TMC に関するその他の情報を見るには、ツールバー
の About をクリックしてください。
1.1 ユーザーアカウントの設定
TMC に初めて接続すると、認証セットアップのページが表示されます。このページで、TMC を利
用する際の認証の有無を選択します。TMC が起動してから認証の有効化／無効化を切り替えるには、
TMC 設定パネルを使用します。
認証を有効化しなかった場合は、ログイン画面でパスワード入力をしなくとも TMC に接続できる
ようになります。
認証を有効化すると、以下の選択項目が表示されます。
• 「.ini ファイル」：ロールに基づいたシンプルなビルトイン認証です。
• LDAP：LDAP サーバを使います。
• Microsoft Active Directory：Active Directory サーバを使います。
LDAPとActive Directoryへの接続を設定する方法は、LDAPやActive Directoryを選択したときに表示
されるフォームで見ることができます。承認と認証を設定すると、TMCへのアクセスを制御できる
ようになります。しかし、接続そのものは保護されません。TMCのセキュリティと接続のセキュリ
ティは、それぞれを個別に保護する必要があります。また、TMCをセキュリティで保護するには、
そのためのTerracottaライセンスが必要になります。
391
1.1.1 アカウントベースのシンプルな認証 .ini ファイルで設定されているロールに基づくアカウントを使う認証は、TMC が提供するもっとも
簡単な認証方法です。.ini ファイル認証を選択した場合は、スクリプト（stop-tmc および start-tmc）を利用して、TMC を再起動する必要があります。TMC へのアクセスを制御する２つのアカウント
を初期化するセットアップページが表示されます。
• Administrator：このアカウント(username "admin ")は、TMC のすべての設定を読み書きでき
ます。
• Operator：この読み取り専用のアカウント(username "operator ")は、接続の構成情報や各種統
計を表示できるアカウントです。このアカウントは接続の追加や編集を行えません。
各アカウントに対するパスワードを作成して Done をクリックすると、ログイン画面が開きます。
ログイン画面は、TMC へ接続するたびに表示されます。
1.1.2 アイドル時間のタイムアウト ユーザーがログインした時点では、アイドル時間のデフォルトタイムアウトは設定されていません。
アイドル時間のデフォルトタイムアウトを設定するには、web.xml の以下の部分をコメントからは
ずし、<param-value>要素にタイムアウト値（分）を設定します。
<context-param> <description> After this amount of time has passed without user activity, the user will be automatically logged out. </description> <param-name>idleTimeoutMinutes</param-name> <param-value>30</param-value> </context-param>
1.2 TMCユーザーインターフェイス
TMC のインターフェースは以下のとおりです。アクティブ（接続中）の接続グループが利用可能か
つ選択されている場合、表示パネルや接続グループのドロップダウンメニューが表示されます。
392
1.3 接続の管理
TMC に初めてログインしたときは、デフォルト接続によるデフォルトの接続グループのみ存在して
います。監視対象となるノードが、デフォルト接続のうちの一つが指定しているポートの localhost上で実行されている場合、そのデフォルト接続がアクティブ接続として表示されます。その他のデ
フォルト接続は、利用不可（アイドル状態）の接続として表示されます。
Connections パネルを使って、接続や接続グループを作成・編集できます。Connections パネルを
開くには、ツールバーの Preferences をクリックします。また、ツールバーの New Connection を
クリックして、新しい接続を直接作成することもできます。管理タスクを簡素化するために、接続
を接続グループに割り当てます。
1.3.1 接続との連携 TMC を使って、接続でノード（クラスタ型とスタンドアロン型の両方）を監視・管理できます。
TMS からエージェントへの接続は、URI を利用して設定します。URI の形式は次のとおりです。
<scheme>:<host-address>:<port>
URI が「http:」の接続は、セキュリティで保護されません。
URI が Terracotta サーバアレイのサーバを指している場合、そのクラスタに属するその他のノード
すべてが自動的に検索されます。そのノードに対して、新たに接続を作成する必要はありません。
標準的なサーバの URI の例を以下に示します。
http://myServer:9030
393
最初の値は、IP アドレスまたは解決可能なホスト名です。その直後に、管理ポートとして使用する
TSA グループポート番号（デフォルト値は 9530）を指定します。ポートは、tc-config.xml を利用し
て構成を設定します。
Terracotta クライアントまたは BigMemory Go の標準的な URI を以下に示します。
http://myHost:9888
最初の値は、IP アドレスまたは解決可能なホスト名です。その直後に、エージェントの管理ポート
を指定します（ポート番号はノードの構成情報ファイルで定義します。デフォルト値は 9888 で
す）。例えば BigMemory Go の場合、ehcache.xml ファイルの managementRESTService 要素で指定
します。
接続の追加
接続を新規に追加するための手順は以下のとおりです。
1. ツールバーの New Connection をクリックします。
2. 監視対象ノードの場所を示す URI を入力し、Next をクリックします。
3. 接続に使用する既存の接続グループを選択、あるいは新しい接続グループを作成し、Next をクリックします。
4. 接続の識別名を入力します。
5. 接続時のタイムアウト値を入力します。あるいは、デフォルト値を使用します。
6. 読み込み時のタイムアウト値を入力します。あるいは、デフォルト値を使用します。
7. 新規の接続を保存するには Create Connection をクリックします。新規の接続作成をやめるに
は Cancel をクリックします。
接続の編集と削除
接続リストに表示されている管理対象の接続を編集または削除することができます。
394
接続の削除
既存のスタンドアロン接続を削除するには、ツールバーの Preferences をクリックし、
Connections パネルを開きます。Configured Connections リストの接続グループから削除する接続
を見つけ、その接続名の隣にある赤い X をクリックします。削除するかキャンセルするかを確認す
るメッセージが表示されます。削除を確認するメッセージが表示されます。
既存のクラスタ接続を削除するには、ツールバーの Preferences をクリックして Connections パネ
ルを開きます。Configured Connections リストの接続グループから削除する接続を見つけ、その接
続名の隣にある赤い X をクリックします。削除するかキャンセルするかを確認するメッセージが表
示されます。
スタンドアロン接続の編集
スタンドアロンの接続を編集するための手順は以下のとおりです。
1. ツールバーの Preferences をクリックします。
2. Connections パネル上で、編集する接続の鉛筆マークをクリックします。
395
3. 接続の場所、グループ、名前を編集します。
4. 接続タイムアウトを入力するかデフォルト値を流用します。
5. 読み取りタイムアウトを入力またはデフォルト値を流用します。
6. 入力した値を保存するには Save Changes をクリックします。元の値に戻すには Cancel をク
リックします。
クラスタ接続の編集
クラスタ接続を編集するには、編集対象のクラスタグループの Edit をクリックします。グループ
名および接続 URL が変更可能です。入力した値を保存するには Save Changes をクリックします。
元の値に戻すには Cancel をクリックします。
1.4 接続グループの監視
設定した接続グループごとに、グループの状態を確認できるミニダッシュボードを表示できます。
TSA 接続グループのダッシュボードにはそれぞれ、接続されている運用サーバ（緑）とミラーサー
バ（青）の数が表示されます。該当する TSA に接続しているクライアントの数も表示されます。さ
らに、起動中または復旧中（黄）と接続不能（赤）といったサーバの状態も、ダッシュボードに表
示されることがあります。
スタンドアロン型の接続グループのダッシュボードには、設定済みの接続数や接続中の接続数が表
示されます。
それぞれのダッシュボードには、そのダッシュボードに関連づけられた接続グループとそのダッシ
ュボードに適用できるコマンドを配したコントロール・ドロップダウンメニューがあります。たと
えば、ある接続グループのダッシュボードを非表示にするには、該当グループのダッシュボードの
コントロールメニューから Hide This Connection を選択します。ダッシュボードを非表示にして
も、その接続グループの接続に影響はありません。その接続のダッシュボードを元の状態に戻すに
396
は、ツールバーから Preferences をクリックし、該当グループの Show in Dashboard チェックボ
ックスにチェックを入れます。
1.5 アプリケーションデータの管理
接続グループ内のノードのアプリケーションデータを管理するには、該当するグループを選んでか
ら Application Data タブをクリックします。各 Application Data パネルには、CacheManager と
Scope メニューがあり、各パネルにどのキャッシュマネージャーとノードからデータを持ってくる
かを選択できます。
1.5.1 Overviewパネル Overview パネルには、キャッシュマネージャー全体にわたる性能やリソースの使用状況を把握す
るのに役立つ特定のキャッシュ統計など、キャッシュマネージャーやキャッシュの状態が表示され
ます。
以下の列からなる表形式で、リアルタイムの集計結果を表示できます。
• Hit Ratio：キャッシュ上にリクエストデータが見つかった割合を表します。リクエストしたデ
ータのすべてをキャッシュから取得できた場合、ヒット率は 1.00 になります（すべての PUTがヒットしたという意味）。値が小さいほど（0.00 に近づくほど）、リクエストがヒットし
なかった、つまりキャッシュ外からのデータの移動（fault）が多かったことを意味します。
• Hit Rate：キャッシュ上でデータリクエストがヒットした数を１秒当たりの値で表します。ミ
ス数よりもヒット数が高いものが、効率の良いキャッシュとなります。
• Local Disk Hit Rate：失敗数（ローカルディスク上でリクエストが失敗したデータ）を表します。
• Local Heap Hit Rate：ローカル（インヒープ領域）上でリクエストがヒットした数（失敗なし）
を表します。
• OffHeap Hit Rate：ローカルメモリ（オフヒープ領域）上でリクエストがヒットした数を表し
ます。BigMemory だけで利用できる統計データです。
• Miss Rate：キャッシュ上でデータリクエストがミスした数を１秒当たりの値で表します。ミス
数よりもヒット数が高いものが、効率の良いキャッシュとなります。
• Local Disk Miss Rate：失敗数（リモートソース上でリクエストが失敗したデータ）を表します。
• Local Heap Miss Rate：ローカル（インヒープ領域）上でリクエストがミスした数を表します。
• OffHeap Miss Rate：ローカルメモリ（オフヒープ領域）上でリクエストがミスした数を表しま
す。BigMemory だけで利用できる統計データです。
• Size：データ全体のサイズ（エントリー数）を表します。
397
• Local Heap Size：ローカルのヒープ領域におけるデータ全体のサイズ（エントリー数）です。
• Local Disk Size：ローカルディスクにおけるデータ全体のサイズ（エントリー数）です。
• Local OffHeap Size：ローカルメモリ（オフヒープ領域）におけるデータ全体のサイズ（エント
リー数）です。BigMemory だけで利用できる統計データです。
• Local Heap Bytes：ローカルのヒープ領域におけるデータ全体のサイズ（バイト数）です。
• Local Disk Bytes：ローカルディスクにおけるデータ全体のサイズ（バイト数）です。
• Local OffHeap Bytes：ローカルメモリ（オフヒープ領域）におけるデータ全体のサイズ（バイ
ト数）です。BigMemory だけで利用できる統計データです。
• Average Get Time：GET オペレーション実行の平均時間です。
• Average Search Time：平均検索時間のグラフには、各検索に要する時間を表示します（該当の
検索時間の現在値も表示されます）。時系列グラフでは、キャッシュのスピード性能や、検索
にかかる時間（平均検索時間）と実行数（検索数）の相関関係を時系列で確認することができ
ます。
• Search Rate：検索数のグラフには、秒当たりの検索実行数が表示されます（検索数の現在値も
表示されます）。時系列グラフでは、キャッシュ検索の実行数や、検索にかかる時間（平均検
索時間）と実行数（検索数）の相関関係を時系列で確認することができます。
• Put Rate：キャッシュ上の書き込みの数を１秒当たりの値で表します。データリクエストが失
敗するたびに書き込みが行われるため、書き込み数はデータリクエストの失敗数と同数かそれ
以上の数になります。また、更新も書き込みとしてカウントされます。書き込みの全体数が少
ないほうが、効率的なキャッシュとなります。
• Remove Rate：要素のエビクション（破棄）数を表します。
• Update Rate：キャッシュ上の要素に対する更新数を、秒当たりの数で表します。更新数が多
いということは、破棄数が多い、あるいはデータ変更が急速に行われたことを示します。
• Expiration Rate：キャッシュ上の要素のうち、有効期限に達している要素の数を秒当たりの数
で表します。期限切れになっても要素は自動的に破棄されません。
• Eviction Rate：キャッシュ上から破棄された要素の数を、秒当たりの数で表します。破棄され
た要素は期限切れか、あるいは使用に関するアルゴリズムに基づいて一定のサイズ制限を超え
たときに破棄された要素です。
• Transaction Rollback Rate：JTA 時系列グラフにトランザクション型キャッシュに関するロール
バック数を表示します（ロールバック数の現在値も表示されます）。
398
• Transaction Commit Rate：JTA 時系列グラフにトランザクション型キャッシュに関するトラン
ザクションのコミット数を表示します（コミット数の現在値も表示されます）。
• Writer Queue Length：ライトビハインド（Write-behind）の時系列グラフに、ライトビハイン
ドキュー（青線）における書き込み合計数と現在値を表示します。
表に表示する統計の種類を選択するには、Configure Columns をクリックし、利用できる統計の一
覧を開きます。統計を選択（またはすべての統計を表示するオプションを設定）してから、OK を
クリックして変更を受け入れます。選択した統計がすぐに表に表示されます。
特定の統計で表を並べ替えるには、該当する統計の列名をクリックします。
1.5.2 Chartsパネル Charts パネルは、「Overview」パネルで利用できる統計をグラフ化して表示します。処理能力の
時系列変化を確認したり、潜在的な問題を見つけるのに役立ちます。
キャッシュマネージャーや表示するデータ範囲を選択できることに加えて、選択したキャッシュマ
ネージャーの特定のキャッシュ（またはすべてのキャッシュ）を選択することもできます。
時系列グラフはそれぞれ、X 軸にシステム時間、Y 軸に計測データを置き、リアルタイムでデータ
を更新していきます。グラフ上のある時点の値を確認するには、マウスポインターをその場所に持
ってきます。グラフ化する統計データに使う単位もこれで表示します。
特別なチャートで統計データをグラフ化するには、該当チャートの Configure リンクをクリックし、
利用できる統計一覧を開きます。統計を選択してから、OK をクリックして変更を受け入れます。
選択した統計をチャートがすぐにグラフ化します。
399
1.5.3 Sizingパネル Diagnostics パネルに、選択したキャッシュマネージャーのキャッシュによる、ヒープやオフヒー
プ、ディスク層の使用状況の情報を表示します。
アクティブなキャッシュマネージャーのリソース層の利用状況を確認するには、CacheManager の
ドロップダウンメニューから該当するキャッシュマネージャーを選択します。
リソース層の利用状況
Relative Cache Sizes by Tier の表は、Tier ドロップダウンメニューから選択したリソース層の利用
状況を表示します。表には以下の列があります。
• Cache：キャッシュの名前です。キャッシュが配分されている（ ）か配分されていない
（ ）かをアイコンで示します。
• Size (MB)：キャッシュデータのサイズを MB で表します。
• % of Used：キャッシュデータに現在使われているキャッシュに割り当てられた全ストレージ
の割合を表します。
• Entries：キャッシュエントリーの合計数を表します。
• Mean Entry Size (bytes)：各キャッシュエントリーの平均サイズをバイトで試算します。
400
名前をつけたキャッシュの値を表示するためにキャッシュ関連のリソース層のグラフを設定するに
は、表内の行をクリックします。
利用状況のグラフ
このパネルでは以下の棒グラフを表示することができます。
• CacheManager Usage by Tier：各リソース層の全体的な利用状況を表します。
• Cache Usage by Tier：選択したキャッシュごとに、各リソース層の利用状況を表します。
Selected Cache ドロップダウンメニューからキャッシュを選択してください。
• Cache Miss Rate by Tier：各リソース層におけるキャッシュのミス数を表します。選択したキャ
ッシュごとに、各リソース層の利用状況を表します。Selected Cache ドロップダウンメニュー
からキャッシュを選択してください。
マウスポインターをグラフの棒に合わせると、利用状況の値が表示されます。Relative Cache Sizes by Tier の表にリソース層の値を表示するには、リソース層の棒をクリックします。
選択されたキャッシュのメニュー
Selected Cache ドロップダウンメニューで、キャッシュ関連のリソース層のグラフに表示するキャ
ッシュを決め、Relative Cache Sizes by Tier 内に該当キャッシュをハイライトすることができます。
また、該当キャッシュにサイズベース（ARC）とエントリーベースのどちらのサイズ指定を用いる
かを、そのメニューで指示します。
1.5.4 Managementパネル Management パネルは、選択済みの接続に対して選択したキャッシュマネージャーのキャッシュを
一覧表示します。
選択したキャッシュマネージャーに対して、以下の設定を利用できます。
• View Config：キャッシュマネージャーの構成情報ファイルの内容を表示します。このウィン
ドウのテキストはコピーできます。
401
• Edit Config：MaxBytesLocalDisk（ローカルディスクを使用している場合）と
MaxBytesLocalHeap の値を編集するためのダイアログを開きます。
• Disable All：一覧表示されているキャッシュすべてのオペレーションを一度に無効化します。
キャッシュを無効化すると、この設定は Enable All になり、一覧表示されているキャッシュ
すべてのオペレーションを一度に有効化することができるようになります。
• Clear Caches：一覧表示されているキャッシュすべてのデータを一度に消去します。
表の列には、以下の属性とその内容が表示されます。
• Cache：キャッシュの名前です。キャッシュの構成情報を確認するには、View Config をクリ
ックします。以下のパラメーターの値を編集するためのダイアログを開くには、Edit Configを開きます。
– MaxBytesLocalHeap
– MaxEntriesLocalHeap
– TimeToIdleSeconds
– TimeToLiveSeconds
• Terracotta Consistency：クラスタ化したキャッシュの一貫性モードです。EVENTUAL（デフォ
ルト）または STRONG を指定します。EVENTUAL は、パフォーマンスを重視します。個々の
キャッシュに対するロックを行なわないため、読み込みの際は、一時的に古い値を取得する可
能性が生じます。STRONG は、一貫性を重視します。常に最新の情報を取得できますが、パフ
ォーマンスは大きく低下します。この値は、動的に変更できません。
• Enabled：キャッシュが有効（true）か無効（false）かを示します。キャッシュのオペレーシ
ョンを停止するには、Disable をクリックします。キャッシュが無効になっている場合は、
Enable をクリックしてキャッシュのオペレーションを開始します。
• Pinned：キャッシュのデータがピンニングによってローカルメモリに記録されている場合は
「LOCALMEMORY」、それ以外の場所に記録されている場合は「INCACHE」、ピンニングされ
ていない場合は「na」が表示されます。
• Eviction Policy：エビクションによってキャッシュからエンティティを削除するときのポリシ
ーを表示します。例えば「Least Recently Used」ポリシーを採用している場合、「LRU」が表
示されます。
• Mode：キャッシュの運用モード（「一括ロードモード」または「通常モード」）が表示され
ます。アプリケーションがキャッシュを準備するとき、一時的に「一括ロードモード」になり
ます。
402
• Element Count：キャッシュ内の要素の合計数を表します。キャッシュデータを消去するには、
Clear Cache をクリックします。
1.6 クラスタの監視
Monitoring タブは、クラスタの接続グループに対してのみ利用できます。このタブにある機能を
使って、クラスタやクラスタの個々のコンポーネントの動きを監視できます。
1.6.1 ランタイムの集計 ランタイム集計を用いて、数々のサーバやクライアントのメトリックについて、リアルタイムでサ
ンプリングしたデータを継続的にフィード取得します。データはグラフで表します。サンプリング
はランタイム集計パネルが最初に開いたときに自動的に開始しますが、時系列データは保存されま
せん。
Select View メニューを使って、ランタイム集計のビューを以下のいずれかに設定します。
• All Servers：TSA の累計データを表示します。
• Specified mirror group：選択したミラーグループの累計データを表示します。
• Specified server：選択したサーバのランタイム集計を表示します。
• All Clients：クラスタの全クライアントの累計データを表示します。
• Specified client：選択したクライアントのランタイム集計を表示します。
以下のセクションに、それぞれのランタイム集計が定義されます。集計対象にできるクラスタのコ
ンポーネントを、テキストで示します。
Live Object Count
クラスタやミラーグループ、サーバ内で稼働しているオブジェクトの合計数を表示します。
稼働しているオブジェクトの合計数が継続的に増加している場合、該当クラスタのクライアントが
メモリ不足に陥り、アプリケーションが動かなくなることがあります。増加傾向は、アプリケーシ
ョンロジックやガーベジコレクションに問題があること、また１つ以上のクライアント上にチュー
ニング問題があることを示しています。
Eviction Rate
クラスタやミラーグループ、サーバから破棄されたエントリー数を表示します。
Expiration Rate
TSA やミラーグループ、サーバ上で見つかった期限切れのエントリー（かつ破棄されたエントリー）
の数を表示します。
403
Write Operation Rate
TSA や選択したサーバで実行された書き込み（または変更）オペレーションの数を表示します。こ
のオペレーションには、通常のエビクションや期限切れによるエビクションも含まれます。したが
って、大量のエビクションや期限切れが発生すると、オペレーション数も急激に増加します（対応
するエビクションと期限切れの統計のグラフを参照してください）。読み込み中心の場合はこの数
は低くなり、書き込み数が少なく破棄するデータも少ないことを表しています。この数字が設定ベ
ースラインよりも定期的に減少または逸脱している場合は、ネットワーク接続に問題があるかサー
バに高負荷がかかっていることを示しています。
クライアントを選択（もしくはすべてのクライアントを選択）した場合、この数字はクライアント
とサーバ間の書き込みトランザクションを追跡する Write Transaction Rate としてレポートされま
す。
Off-heap Usage
利用可能または使用中のオフヒープメモリの最大サイズをメガバイト（MB）またはギガバイト
（GB）で表示します。こうした数字は、BigMemory を有効化している場合のみ表示されます。
Read Operation Rate
fault によって TSA に移動したオブジェクトの数（1 秒あたり）を表示します。fault による移動は、
アプリケーションからの要求に応じて発生します。サーバのオンヒープ層のキャッシュにデータが
存在しない場合は、オフヒープ層またはディスク層からデータを移動します（この移動を「fault による移動」と呼びます）。ヒープ層やオフヒープ層のキャッシュデータが一杯になった場合は、デ
ータを低速なデータ層へ移動する必要が生じます（この移動を「flush による移動」と呼びます）。
初めて要求されたオブジェクトや、リクエストが届く前にオフヒープメモリから flush されたオブ
ジェクトは、ディスクから移動（fault による移動）されます。数字が高い場合、サーバにおけるメ
モリ配分が不適当であることを示しています。
クライアントの flush 数で、クライアントメモリから Terracotta サーバにオブジェクトがいくつ移
動（flush による移動）されたかを測ることができます。このオブジェクトは、後で必要に応じて
Terracotta サーバの中で利用できます。flush 数が高い場合、クライアントにおけるメモリ配分が不
適当であることを示しています。
クライアントの fault 数で、サーバからクライアントメモリにオブジェクトがいくつ障害として移
動されたかを測ることができます。fault 数が高い場合、リファレンスのローカリティが低いか、ク
ライアントにおけるメモリ配分が不適当であることを示しています。
1.6.2 Eventsパネル Events パネルは、Terracotta サーバアレイが受け取ったクラスタイベントを表示します。このパネ
ルを使うことで、Terracotta のログを検索せずに一カ所で読みやすいフォーマットで素早くイベン
トを確認できます。
404
クラスタ化された接続ごとに、小さなダッシュボードが表示されます。この中のアイコンには未読
イベントの数が表示されます。未読イベントの数が増えると、深刻度が高まります。このアイコン
の色は、未読イベントの数に応じて変化します。通常はグレーですが、警告レベルを越えると赤に
なります。
表示対象の深刻度を選択すると、それよりも高い深刻度のイベントがすべて表示されます。例えば
深刻度に INFO を選択すると、WARN（警告）以上の深刻度のイベントも表示されます。
個々のイベントの詳細は この表を参照してください。
1.7 クラスタの管理
Administration パネルには、Terracotta クラスタの情報に加え、クラスタデータのバックアップと
いった運用ツールの情報が表示されます。
1.7.1 構成パネル Configuration パネルでは、Cluster Node メニューで選択したサーバの状態、環境、構成情報をサ
ブパネルを使って表示できます。この情報は、問題の報告やデバッグに役立ちます。
Main サブパネルには、サーバの IP アドレスやバージョン、ライセンス（性能）、再起動機能やフ
ェイルオーバモードといった、サーバの状態やプロパティの一覧を表示します。このサブパネルを
見るには、特定のサーバを選択する必要があります。管理者は、このパネルからサーバをシャット
ダウンできます。
405
以下のサブパネルを追加できます。
• Environment：サーバの JVM システムプロパティです
• TCProperties：サーバが使用している Terracotta のプロパティです。
• Process Args：サーバ起動時の JVM 引数です。
• TCConfig：サーバ起動時の Terracotta の構成情報ファイルです。
1.7.2 サーバログの確認 Logs パネルには、Cluster Node メニューで選択したサーバのログをリアルタイム表示します。上
方向にスクロールすると（または Pause をクリックすると）、リアルタイム更新が一時的に停止し
ます。ログの最終行までスクロールすると（または Resume をクリックすると）、リアルタイム更
新が再開します。
1.7.3 クラスタデータのバックアップ クラスタデータのバックアップ作成を制御するには Backup パネルを利用します。以下のサーバ構
成要素を使用して、バックアップ採取の実行を制御します。
• <restartable enabled="true"/>：（すべてのサーバの）バックアップを有効化するには、グロー
バル設定に「true」を指定します。デフォルトでは「false」です。
• <data-backup>terracotta/backups：個々のサーバに対し、バックアップファイルを記録するパ
スを指定します。デフォルトのパスが表示されます。
バックアップからの復元方法の詳細は Terracottaサーバアレイのドキュメント を参照してください。
1.7.4 クラスタトポロジの変更 サーバーの追加や削除を行なうには、Terracotta 構成情報を再ロードします。正しく再ロードを行
なうため、すべてのサーバとクライアントがアクセスできる場所に編集済みの構成情報ファイルを
保存してください。
Terracotta構成情報とserversセクションの編集方法の詳細は Terracottaサーバアレイのドキュメン
トを参照してください。
1.8 クラスタのトラブルシューティング
TMC を利用して Terracotta クラスタのトラブルシューティングを行なうには、「監視パネル」を
利用して発生したイベントや統計的な傾向を監視する方法と、「ログ」と「スレッドダンプ」を利
用して解析を行なう方法があります。あるクラスタにおいて、特定リソース使用量のしきい値を超
えたような場合、「一部の機能を制限したモード」に切り替わり、システム全体のクラッシュを防
止します。
406
1.8.1 特殊なTSAモード TSA に対してスロットルモードまたは制限モードが適用された場合、TMC は警告を発します。特定
のしきい値までメモリリソース量が低下し、クラスタ運用に影響する可能性が高まると、これらの
モードが適用されます。例えばエビクションによって期限切れのデータが破棄され、十分なメモリ
が確保できる状態になると、TSA はスロットルモードから自動的に回復します。ただし、自動回復
できず、そのまま制限モードが適用される場合もあります。「Disable All または Clear Caches」を
利用すると、こうした状況を一時的に解消できます。TSA にこのモードが適用されるのは、メモリ
リソースの割り当て量の不足が原因です。クラスタを停止し、クラスタの運用のために十分なメモ
リを割り当てるための策を講じることを検討してください。
1.8.2 スレッドダンプの生成 スレッドダンプを使って、Terracotta クラスタの各サーバとクライアントの状態をスナップショッ
トで取得できます。コンソールのスレッドダンプ機能を表示するには、Troubleshooting をクリッ
クします。
スレッドダンプのナビゲーション枠に、日時形式のタイムスタンプごとに完了したスレッドダンプ
が一覧表示されます。選択したスレッドダンプの内容が右側の枠内に表示されます。表示されてい
るスレッドダンプをすべて削除するには、Clear All をクリックします。
スレッドダンプを生成するための手順は以下のとおりです。
1. Scope メニューから対象となるスレッドダンプを選びます。
2. Take Thread Dump をクリックします。
3. スレッドダンプのナビゲーション枠に作成されたエントリーを拡大すると、スレッドダンプの
エントリーを確認できます。
4. サーバまたはクライアントのエントリーをクリックして、該当するサーバやクライアントのス
レッドダンプを表示します。
5. 表示されているスレッドダンプをアーカイブとして保存するには Download All をクリックし
てください。
6. 表示されているスレッドダンプを一覧から削除するには Clear All をクリックします。
Scope メニューに表示されるサーバのうち、接続していないサーバは、空のスレッドダンプを生成
します。
1.8.3 サーバログの確認 Terracotta クラスタ内の各サーバのログを表示するには、次のように操作します。
1. Troubleshooting をクリックし、Logs をクリックします。
2. Cluster Node メニューからサーバを選択します。
407
3. Pause をクリックする、またはログを上にスクロールすると、ログの更新が一時停止します。
4. ログをアーカイブとして保存するには Download Logs をクリックしてください。
1.9 プリファレンス
ツールバーの Preferences をクリックして、TMC のグローバル設定を構成するためのダイアログ
を開きます。
1.9.1 ポーリング間隔 Polling タブをクリックし、ポーリングした統計データの精度を制御する Polling Interval Secondsを設定します。ポーリング間隔が短いほど、ポーリング対象となるノード全体のパフォーマンスへ
の影響も大きくなります。デフォルト値にリセットするには、Reset to Defaults をクリックします。
1.9.2 セキュリティの設定 セキュリティの構成情報を設定するには Security タブをクリックします。TMS で使用中のセキュ
リティ種別を変更する際は、以下の点に注意が必要です。
• セキュリティの設定を変更した場合は、TMC の再起動が必要です。
• セキュリティ種別を変更することで、そのための構成情報と追加機器などが必要になる場合が
あります。
• セキュリティを追加すると、セキュリティで保護されていないノードと接続できなくなる場合
があります。
• 認証を無効化すると、セキュリティで保護されているノードと接続できなくなる場合がありま
す。
SSL 接続を利用すると、デフォルトの Java cacerts ファイルのほか、カスタムトラストストアを選
択できます。カスタムトラストストアは、Security パネルで指定したデフォルトに保存してくださ
い。
セキュリティ設定の詳細は、「ユーザーアカウントの設定」と TMCのドキュメントを参照してく
ださい。
2 Terracottaライセンスファイルの取り扱い Terracotta 製品のエンタープライズ版を実行するには、Terracotta ライセンスファイルが必要です。
ファイル名は terracotta-license.key で、変更はできません。Terracotta 製品の体験版には試用期間
があります。Terracotta に延長を申し入れる時間を設けるため、有効期限切れの警告はログと標準
出力の両方に発行されます。
Terracotta ソフトウェア製品のエンタープライズ版を使用する各ノードに、ライセンスファイルの
コピーまたはライセンスファイルの場所を設定した構成情報が必要です。ライセンスファイルは、
408
デフォルトで Terracotta ソフトウェアキットのルートディレクトリに配置されています。ライセン
スファイルをキットのルートディレクトリに置いておくことで、ファイルの所在位置を明示的に指
定するのを避けることができます。
または、リソース（/terracotta-license.key）が、Terracotta Toolkit ランタイム JAR と同じクラスパ
ス上にあるようにしてください。.（標準 Terracotta Toolkit ランタイム JAR は Terracotta キットに
含まれています。JAR ファイルのインストールについては、お手元の Terracotta 製品のインストー
ル手順をご参照ください。）例えば、Web アプリケーションを使用する際は、ライセンスファイル
は WEB-INF/classes に配置することも可能です。
2.1 ライセンスファイルを配置場所の明示的に指定する
ライセンスファイルが Terracotta インストールディレクトリにある場合、以下のように指定します。
-Dtc.install-root=/path/to/terracotta-install-dir
ライセンスファイルが別の場所にある場合、以下のように指定します。
-Dcom.tc.productkey.path=/path/to/terracotta-license.key
または、以下を Terracotta 構成ファイル（デフォルトで tc-config.xml）の先頭に追加することで、
ライセンスファイルへのパスを指定することができます。
<tc-properties> <property name="productkey.path" value="path/to/terracotta-license.key" /> <!-- Other tc.properties here. --> </tc-properties>
WAR または JAR ファイルにあるライセンスファイルを参照するには、productkey.path を
productkey.resource.path に置き換えます。
2.2 製品と機能の確認
お手元のプロダクトキーによってどの製品と機能が利用可能となり、どのような制限が課せられる
のかを確認する方法は何通りかあります。まず、プロダクトキーが入っている読み取り可能なファ
イル（terracotta-license.key）を参照することで確認できます。
第二に、Terracotta ソフトウェアは、起動時にプロダクトキーに関するメッセージをログに記録し
ます。このメッセージはログと標準出力にプリントされます。また、以下のように表示されます。
2010-11-03 15:56:53,701 INFO - Terracotta license loaded from /Downloads/terracotta-ee-3.4.0/terracotta-license.key Capabilities: DCV2, authentication, ehcache, ehcache monitor, ehcache offheap, operator console, quartz, roots, server array offheap, server striping, sessions
409
Date of Issue: 2010-10-16 Edition: FX Expiration Date: 2011-01-03 License Number: 0000 License Type: Trial Licensee: Terracotta QA Max Client Count: 100 Product: Enterprise Suite ehcache.maxOffHeap: 200G terracotta.serverArray.maxOffHeap: 200G
ライセンス情報は、Terracotta デベロッパーコンソールと Terracotta オペレーションセンターの
Terracotta サーバ情報パネルにも含まれています。
3 BigMemory GoとHibernateの連携
3.1 はじめに
BigMemory Goは、O/Rマッピングフレームワークの Hibernateと簡単に連携できます。Hibernateの開発者であるGavin King自身も、BigMemory GoのEhcacheプロジェクトのコミッターです。したが
ってBigMemory Goは、Hibernateにおける第一級のデータストアであることが約束されています。
BigMemory GoとHibernateの連携の構成設定は非常に簡単です。基本的な手順は以下のとおりです。
• BigMemory Go をダウンロードおよびインストールし、プロジェクトに組み込む。
• プロジェクトの Hibernate の構成情報を編集し、BigMemory Go をキャッシュプロバイダーに
設定する。
• プロジェクトの Hibernate に 2 次キャッシュの構成情報を設定する。
• キャッシュの対象にする各エンティティ、コレクション、またはクエリに対し、Hibernate の
キャッシュの構成情報を設定する。
• 必要に応じて、各エンティティ、コレクション、またはクエリに対し、ehcache.xml ファイル
で構成情報を設定する。
Hibernateのキャッシュの構成情報の詳細は、Hibernateのドキュメントを参照してください。
3.2 ダウンロードとインストール
Hibernate プロバイダは BigMemory Go のキットに同梱されている ehcache-ee モジュールに含まれ
ています。
410
3.3 Mavenを利用したビルド
利用するキットによって、依存関係のあるバージョンは異なります。キットごとに互換性のあるア
ーティファクトが用意されています。キットをダウンロードし、必要なアーティファクトのバージ
ョンを確認してください。ダウンロードしたビルドの「pom.xml」を編集し、以下の\を追加してく
ださい。
<repository> <id>terracotta-releases</id> <url>http://www.terracotta.org/download/reflector/releases</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository>
以下のように、\を用いて Ehcache と BigMemory のモジュールをビルド（pom.xml）に設定または
追加します。
<dependency> <groupId>net.sf.ehcache</groupId> <artifactId>ehcache-ee</artifactId> <version>${ehcacheVersion}</version> </dependency> <dependency> <groupId>org.terracotta.bigmemory</groupId> <artifactId>bigmemory</artifactId> <version>${bigmemoryVersion}</version> </dependency>
3.4 BigMemory Goを 2 次キャッシュプロバイダーとして設定
BigMemory Go を Hibernate の 2 次キャッシュに設定するには、Hibernate の構成情報に、以下のい
ずれかのファクトリプロパティを設定します。Hibernate の構成情報は、「hibernate.cfg.xml」、
「hibernate.properties」または Spring で設定します。以下は、「hibernate.cfg.xml」に指定する型
式の例です。
3.4.1 Hibernate 3.3 以上 インスタンスを作成する場合
<property name="hibernate.cache.region.factory_class"> net.sf.ehcache.hibernate.EhCacheRegionFactory</property>
Hibernate で使用する Ehcache の CacheManager をシングルトンにする場合
411
<property name="hibernate.cache.region.factory_class"> net.sf.ehcache.hibernate.SingletonEhCacheRegionFactory</property>
3.5 クエリキャッシュと 2 次キャッシュの設定
2 次キャッシュプロバイダの構成情報を設定したら、2 次キャッシュを有効化します（Hibernate の
デフォルト値は「無効」です）。Hibernate の構成情報に、以下のプロパティを設定してください。
<property name="hibernate.cache.use_second_level_cache">true</property>
Hibernate でクエリのキャッシュを使用するには、クエリのキャッシュの有効化も必要です。
Hibernate の構成情報に、以下のプロパティを設定してください。
<property name="hibernate.cache.use_query_cache">true</property>
3.6 その他の設定
以下の操作や設定は省略可能です。
3.6.1 構成リソース名 Hibernate インスタンス、キャッシュプロバイダ、キャッシュ領域ファクトリが使用する Ehcache構成情報ファイルの場所を指定するには configurationResourceName プロパティを使用します。リ
ソースの検索は、classpath のルートで行います。このリソースは、1 つの VM の中で複数の
CacheManager をサポートするときに使用します。Hibernate に対し、使用すべき構成情報を指定し
ます。例えば「ehcache-2.xml」のように指定してください。複数の Hibernate インスタンスを使用
する場合、シングルトンでない複数のプロバイダまたは領域ファクトリを用意し、それぞれに専用
の Ehcache 構成リソースを割り当てて使用することを推奨します。
net.sf.ehcache.configurationResourceName=/name_of_ehcache.xml
3.6.2 Hibernateのキャッシュプロバイダーをプログラムから設定する方法 Hibernate のプロバイダーは、プログラム側からも設定できます。SessionFactory を作成する前に
必要な Hibernate プロパティ設定を追加してください。
Configuration.setProperty("hibernate.cache.region.factory_class", "net.sf.ehcache.hibernate.EhCacheRegionFactory")
3.7 クエリキャッシュと 2 次キャッシュ
2 次キャッシュとクエリのキャッシュの両方を有効化する場合、Hibernate の構成情報ファイルに
は以下の記述が必要です。
<property name="hibernate.cache.use_second_level_cache">true</property> <property name="hibernate.cache.use_query_cache">true</property>
412
<property name="hibernate.cache.region.factory_class"> net.sf.ehcache.hibernate.EhCacheRegionFactory</property>
同様に、Spring の構成情報ファイルには以下の記述が必要です。
<prop key="hibernate.cache.use_second_level_cache">true</prop> <prop key="hibernate.cache.use_query_cache">true</prop> <prop key="hibernate.cache.region.factory_class"> net.sf.ehcache.hibernate.EhCacheRegionFactory</prop>
3.8 Hibernateのエンティティで 2 次キャッシュを使用するための構成
Hibernate の 2 次キャッシュプロバイダの構成に加え、Hibernate に対し、エンティティ、コレクシ
ョン、クエリのキャッシュ化を指示する必要があります。例えば、ドメインオブジェクトの
「com.somecompany.someproject.domain.Country」に対するキャッシュエントリーを有効化するに
は、以下のようなマッピングファイルを作成します。
<hibernate-mapping> <class name="com.somecompany.someproject.domain.Country" table="ut_Countries" dynamic-update="false" dynamic-insert="false" > ... </class> </hibernate-mapping>
そして、以下の要素を追加してキャッシュを有効化します。
<cache usage="read-write|nonstrict-read-write|read-only" />
以下に例を示します。
<hibernate-mapping> <class name="com.somecompany.someproject.domain.Country" table="ut_Countries" dynamic-update="false" dynamic-insert="false" > <cache usage="read-write" /> ...
413
</class> </hibernate-mapping>
この設定は、以下のように@Cache アノーテーションを指定することでも代替できます。
@Entity @Cache(usage = CacheConcurrencyStrategy.READ_WRITE) public class Country { ... }
3.8.1 キャッシュへの同時並行アクセスを制御する属性 read-only
キャッシュデータ更新を禁止します。
nonstrict-read-write
キャッシュをロックしないで行うキャッシュデータ更新を許可します。キャッシュデータの同時並
行アクセスを許可すると、キャッシュから得た値がデータベースの最新情報を反映しているという
保証が得られなくなります。したがって、キャッシュにはタイムアウト値の設定が必要です。
read-write
分離レベル「read committed」を維持した状態でのキャッシュデータ更新を許可します。データベ
ースを「repeatable read」に設定した場合、この属性を設定することで内容をほぼ保証できるよう
になります。ただし、同時並行での書き込みが発生した場合、分離レベル「repeatable read」は維
持できません。
3.9 構成
ehcache.xml ファイルには defaultCache が定義されているため、Hibernate でキャッシュが必要にな
った場合は自動的に作成されます。しかし、キャッシュに名前を設定して、キャッシュごとに構成
情報を設定すれば、より細かく制御できるようになります。Hibernate のキャッシュは、データベ
ースからの読み込み処理を伴うため、準備に非常に時間を要する場合があります。こうした処理を
制御するには、maxEntriesLocalHeap を使用してメモリ上のキャッシュ数に上限を設定し、残りを
ディスクへ移動するよう設定します。Hibernate は、ドメインオブジェクト、コレクション、およ
びクエリのキャッシュに対し、独自のルールで名前を設定します。
3.9.1 ドメインオブジェクト Hibernate は、ドメインオブジェクトの完全修飾名を含むキャッシュ名を作成します。したがって、
例えば「com.somecompany.someproject.domain.Country」ドメイン用のキャッシュを作成する場合
は、「ehcache.xml」に以下のような記述を挿入します。
414
<?xml version="1.0" encoding="UTF-8"?> <ehcache> <cache name="com.somecompany.someproject.domain.Country" maxEntriesLocalHeap="10000" eternal="false" timeToIdleSeconds="300" timeToLiveSeconds="600" <persistence strategy="localTempSwap"/> /> </ehcache>
Hibernate のキャッシュの同時並行アクセス
ドメインオブジェクトのキャッシュの属性には、「read-write」、「nonstrict-read-write」、また
は「read-only」を指定できます。
3.9.2 コレクション Hibernate がコレクションのキャッシュを作成する場合、キャッシュの名前は「\.\」となります
（ドメイン名とコレクション名の間に「.（ピリオド）」。例えば、ドメインオブジェクトの
「Country」が「advancedSearchFacilities」というコレクションを持っていたとします。Hibernateのアクセッサ用の Doclet は、次のようになっています。
/** * Returns the advanced search facilities that should appear for this country. * @hibernate.set cascade="all" inverse="true" * @hibernate.collection-key column="COUNTRY_ID" * @hibernate.collection-one-to-many class="com.wotif.jaguar.domain.AdvancedSearchFacility" * @hibernate.cache usage="read-write" */ public Set getAdvancedSearchFacilities() { return advancedSearchFacilities; }
このセット用に、キャッシュ構成情報を追加する必要があります。「ehcache.xml」ファイルに、次
のような記述を追加します。
<?xml version="1.0" encoding="UTF-8"?> <ehcache> <cache name="com.somecompany.someproject.domain.Country" maxEntriesLocalHeap="50" eternal="false"
415
timeToLiveSeconds="600" <persistence strategy="localTempSwap"/> /> <cache name="com.somecompany.someproject.domain.Country.advancedSearchFacilities" maxEntriesLocalHeap="450" eternal="false" timeToLiveSeconds="600" <persistence strategy="localTempSwap"/> /> </ehcache>
Hibernate のキャッシュの同時並行アクセス
ドメインオブジェクトのコレクションのキャッシュの属性には、「read-write」、「nonstrict-read-write」、または「read-only」を指定できます。
3.9.3 クエリ Hibernate は、クエリの結果のキャッシュ化をサポートします。クエリ用のキャッシュは 2 種類あ
ります。
StandardQueryCache
名前を設定せずにクエリのキャッシュを使用する場合は、このキャッシュを使用します。
「ehcache.xml」の構成情報の例は以下のとおりです。
<cache name="org.hibernate.cache.StandardQueryCache" maxEntriesLocalHeap="5" eternal="false" timeToLiveSeconds="120" <persistence strategy="localTempSwap"/> />
UpdateTimestampsCache
特定のテーブルに対する最終更新のタイムスタンプを追跡します。クエリのキャッシュに設定する
タイムアウトには、元になるキャッシュのタイムアウトよりも小さい値を設定してください。実際
には、元になるキャッシュのタイムアウトは無期限にすることを推奨します。「ehcache.xml」の構
成情報の例は以下のとおりです。
<cache name="org.hibernate.cache.UpdateTimestampsCache"
416
maxEntriesLocalHeap="5000" eternal="true" <persistence strategy="localTempSwap"/> />
名前付きクエリのキャッシュ
QueryCache に対して Hibernate で「Query.setCacheRegion(String name)」を実行すると、名前付き
のキャッシュとして利用できるようになります。この処理により、「ehcache.xml」内のキャッシュ
にも、このメソッドで名前を指定できるようになります。名前は何でも構いませんが、混乱を避け
るため、名前の先頭には必ず「query.」を使用してください。例は以下のとおりです。
<cache name="query.AdministrativeAreasPerCountry" maxEntriesLocalHeap="5" eternal="false" timeToLiveSeconds="86400" <persistence strategy="localTempSwap"/> />
クエリのキャッシュの使用方法
例えば、Country ドメインに対して実行するクエリがあったとします。以下のようなコードで、こ
のクエリのキャッシュを使用します。
public List getStreetTypes(final Country country) throws HibernateException { final Session session = createSession(); try { final Query query = session.createQuery( "select st.id, st.name" + " from StreetType st " + " where st.country.id = :countryId " + " order by st.sortOrder desc, st.name"); query.setLong("countryId", country.getId().longValue()); query.setCacheable(true); query.setCacheRegion("query.StreetTypes"); return query.list(); } finally { session.close(); } }
417
クエリをキャッシュ化しているのはquery.setCacheable(true)というコードです。このキャッシュに
対し、query.setCacheRegion("query.StreetTypes")というコードで名前を付けています。Alex Millerの記事では、クエリ用キャッシュの利用に役立つ情報を提供しています。参照してください。
Hibernate のキャッシュの同時並行アクセス
ドメインオブジェクトに、「read-write」、「nonstrict-read-write」、または「read-only」を指定
しても意味はありません。クエリキャッシュに対する同時並行アクセスの属性は設定できません。
常に、ロックなしの読み取り専用キャッシュ（read-only）として動作します。
3.10 デモアプリケーション
Hibernate の CacheRegionFactory の使用方法を示すためのデモアプリケーションが用意してありま
す。
3.10.1 Hibernateのチュートリアル Terracotta Forgeからチェックアウトして使用してください。
3.11 パフォーマンス向上のヒント
3.11.1 Session.load Session.load は、常にキャッシュを使用します。
3.11.2 Session.find and Query.find Session.find は、プライマリーオブジェクトに対するキャッシュを使用しません。Hibernate は、関
連オブジェクトのキャッシュを常に使用します。その一方で、Session.find はキャッシュにデータ
を作成します。Query.find も、まったく同じ動作をします。キャッシュのヒット率が低そうな場合
は、これらを利用してください。
3.11.3 Session.iterate and Query.iterate Session.iterate は、プライマリーオブジェクトと、その関連オブジェクトについて、常にキャッシ
ュを使用します。Query.iterate も、まったく同じ動作をします。キャッシュのヒット率が高そうな
場合は、これらを利用してください。
3.12 FAQ
3.12.1 アプリケーションにBigMemory Goを使用し、2 次キャッシュにHibernateを使用
する場合、アプリケーションのキャッシュ用のCacheManagerはHibernateで作成
する必要がありますか。 両者の CacheManager のリソースファイルは共有できますが、両者の動作環境はきちんと分割した
ほうがよいでしょう。各アプリケーションが使用するキャッシュの有効期限は、Hibernate と異な
る可能性があります。そうした場合も、CacheManager の「Automatic Resource Control (ARC)」に
は、異なる設定が必要になります。
418
3.12.2 プロバイダーが、Hibernateのリリース版とBigMemory GoのEhcacheの両方に同梱
されています。どちらを使用すべきですか。 Hibernate 2.1 からは、Ehcache の CacheProvider が同梱されるようになりました。このプロバイダ
ーは、Ehcache のコアと同期されるよう、定期的に更新されています。しかし、一般的には、
Ehcacheno コアに新機能が追加され、それから Hibernate に追加されることが多いはずです。
3.12.3 HibernateプロジェクトとEhcacheプロジェクトは、どのような関係があるのでし
ょうか。 Gavin King と Greg Luck は、互いに協力して Ehcache を作成し、それを Hibernate にも組み込んで
います。2009 年から Greg Luck は Hibernate のコミッターになっています。したがって、Ehcacheは、Hibernate の 2 次キャッシュとして、最も信頼性の高い製品であることが約束されています。
3.12.4 BigMemory Goは、トランザクションに対応していますか。 はい。Ehcache 2.1 から、この機能が導入されています。
3.12.5 Hibernateは一部のキャッシュを自動的にクリアする場合があるようです。なぜ
ですか。 例えば Query.executeUpdate()を実行するたびに、Hibernate は関連するキャッシュ領域を無効化し
ます。ここでいう関連するキャッシュ領域とは、メソッドの実行による影響を受けるデータベース
テーブルの領域を指します。古いデータをキャッシュに残さないためには、こうした処理が必要に
なるからです。データベースのストアドプロシジャを実行した場合も、この処理が実行されます。
詳細は Hibernateのバグ報告を参照してください。
3.12.6 Hibernateのエンティティには、どのようにキーが付けられるのでしょうか。 Hibernate はオブジェクト ID によってキャッシュ済みエントリーを識別します。
3.12.7 複合キーはサポートされていますか。 はい。
3.12.8 次のようなメッセージが表示されました。キャッシュの要素がロックされてい
るのに期限切れになりました。これはどういう意味ですか。 ある種の値を置換すると、ソフトロックがかかります。このロックにより、他のスレッドは通常の
要素と異なる扱いをするようになります。Hibernate は、2 相コミットを行うデータベースの
Read/Write に、この性質を利用しています。これは、データベースのコミット処理中は、キャッ
シュが何を返すべきかわからないからです（データベース側では把握できているはずです）。2 相
コミットの処理中、ソフトロックのかかった Element は期限切れの状態になります。したがって、
2 相コミットが完了してからキャッシュにアクセスしても、キャッシュには値がありません。この
ため、そのオブジェクトの値をデータベースから再ロードすることになります。この動作によって
データベースの負荷は上がります。しかし、致命的な問題ではありません。
結論をいえば、この Hibernate メッセージが表示されたからといって、問題が発生しているとは限
りません。これが問題になるのは、新しくロードされた項目を、間違ったエビクションで破棄して
419
いる場合です。エビクションの間違いを防ぐには、エビクションの前に、その項目を破棄すべきか
どうか判断することです。この判断処理を行う LRU を使用するには、システムプロパティに java -Dnet.sf.ehcache.use.classic.lru=true を指定してください。
4 BigMemory GoとSpringの連携
4.1 はじめに
BigMemory GoのEhcacheは、これまでのバージョンでもSpringとの連携を効果的に行ってきました。
Spring 3.1 はEhcacheの実装を含んでいます。詳細は Spring 3.1 JavaDocを参照してください。
4.2 Spring 3.1 Spring Framework 3.1 は、Spring アプリケーションに対して透過的にキャッシュを適用するための、
一般的なキャッシュ抽象の概念を持っています。クラスとメソッドでキャッシュをサポートするた
め、2 つのアノーテーションが提供されています。
4.2.1 @Cacheable メソッド呼び出しをキャッシュ化します。以下の例の場合、戻り値の型は「Manual」です。id を使
用して引数の ISBN からキーを抽出します。
@Cacheable(value="manual", key="#isbn.id") public Manual findManual(ISBN isbn, boolean checkWarehouse)
4.2.2 @CacheEvict 呼び出されたときキャッシュをクリアします。
@CacheEvict(value = "manuals", allEntries=true) public void loadManuals(InputStream batch)
SpEL（Spring Expression Language）のブログに、参考になる記事が投稿されています。を参照して
ください。
4.3 Spring 2.5 - 3.1: Spring用アノーテーション
Eric Dalquist らによるオープンソースは、Spring 3.1 プロジェクト以前から存在します。これらの
アノーテーションは、Spring 3.1 でも、それ以前のバージョンでも使用できます。
4.3.1 @Cacheable Spring 3.1 と同様、メソッドのキャッシュ化には@Cacheable アノーテーションを使用します。以下
の例では、findMessage メソッドの呼び出しを「messageCache」という名前のキャッシュに保存し
ます。値は Message 型です。各エントリーの id には、引数に指定された id を使用します。
420
@Cacheable(cacheName = "messageCache") public Message findMessage(long id)
4.3.2 @TriggersRemove キャッシュを無効化する場合は@TriggersRemove アノーテーションを使用します。以下の例は、メ
ソッド起動後に cache.removeAll()を呼び出します。
@TriggersRemove(cacheName = "messagesCache", when = When.AFTER_METHOD_INVOCATION, removeAll = true) public void addMessage(Message message)
使用方法の詳細は、を参照してください。このページには、関連情報のリンクも紹介されています。
4.4 Springプロジェクト用のアノーテーション
メソッドの戻り値のキャッシュを動的に構成する方法は、code.google.comの Ehcache Annotations for Spring project at code.google.comで紹介されている方法を利用します。このプロジェクトでは、
構成情報だけを利用してメソッド呼び出しのキャッシュ化を動的に構成する方法を紹介しています。
この仕組みでは、メソッドのパラメーターの値をキャッシュの複合キーとして使用し、メソッドの
戻り値をキャッシュに記録します。
例えば次のメソッドがあるとします。Dog getDog(String name)
このメソッドをキャッシュ化すると、このメソッドに対するすべての呼び出しは、パラメーターの
「name」をキーとしてキャッシュに記録されます。
まず、アプリケーションは name に「fido」を指定して、「t0」番目のメソッド呼び出しを行いま
す。「fido」は存在しないため、メソッドは通常どおり起動します。そして、「fido」という名前
の Dog オブジェクトを作成して返します。このオブジェクトは、「fido」というキー名でキャッシ
ュに記録されます。
次に、アプリケーションは name に「spot」を指定して、「t1」番目のメソッド呼び出しを行いま
す。同様の処理により、キャッシュには「spot」というキー名の Dog オブジェクトが記録されます。
その後、アプリケーションは再び「fido」という名前を指定して、「t2」番目のメソッド呼び出し
を行います。既に「fido」というキー名のオブジェクトがキャッシュに存在します。したがって、
キャッシュはメソッドを実行せず、キャッシュに記録されている「fido」というキーの Dog オブジ
ェクトを返します。
この仕組みを手元のアプリケーションへ実装するには、以下の手順を実施してください。
手順 1:
Ehcache Annotations for Spring project siteからjarファイルを入手し、アプリケーションに追加しま
す。
421
手順 2:
キャッシュ化するメソッドにアノーテーションを追加します。ここでは、前述の例で使用した
「Dog getDog(String name)」メソッドをキャッシュ化する例を示します。
@Cacheable(name="getDog") Dog getDog(String name) { .... }
手順 3:
Spring の構成情報を設定します。Spring 構成情報ファイルの beans 宣言セクションに、以下のテキ
ストを挿入する必要があります。
<ehcache:annotation-driven cache-manager="ehCacheManager" />
さらに詳細な情報が必要な場合は、以下のページを参照してください。
• Spring用Ehcacheアノーテーション
• @Cachableアノーテーションの使い方
• Javaメソッドのキャッシュ化に関するブログ
