commons-transaction は、ファイルアクセスにトランザクション機能 (ていうか ACID 特性) を提供します。例えば、トランザクション中でファイルを作成したり書き込んだりしても、コミットするまでは反映されませんし、ロールバックすればその操作は無かったことになります。また、トランザクション中の操作は分離しており、他のトランザクションやトランザクションに参加していないファイルアクセスからは見えないようになります。(コレクションへのアクセスにもトランザクション機能を提供してくれるみたいですが、これはよく分かりませんでした)

手順

• リソース マネージャを起動します。
  • アプリケーション中で 1 度だけ。例えば、アプリケーションの開始時。
• トランザクションの ID を取得し、トランザクションを開始します。
• リソース マネージャ経由でファイルアクセスを行います。
  • java.io などを使用して直接ファイルアクセスしてはダメです。リソース マネージャ経由で行うことでトランザクションに参加することができます。
• コミット、またはロールバックします。
• リソース マネージャを停止します。
  • アプリケーション中で 1 度だけ。例えば、アプリケーションの終了時。

リソース マネージャの起動、終了

org.apache.commons.transaction.file.FileResourceManager クラスをインスタンス化し、 FileResourceManager#start() メソッドを呼び出すことでリソース マネージャを起動します。

FileResourceManager クラスのコンストラクタは以下の形式です。

FileResourceManager(String storeDir, String workDir, boolean urlEncodePath, LoggerFacade logger)

• storeDir
  • トランザクション管理を行う対象のディレクトリを指定します。
• workDir
  • トランザクション管理の作業ディレクトリを指定します。
• urlEncodePath
  • true を指定すると、ファイル名が URL エンコードされます。
• logger
  • リソース マネージャのログ出力に使用します。 null を指定すると例外がスローされます (ログ出力なんてどうでも良いときはどうするんだ…) 。

FileResourceManager manager = new FileResourceManager(
    "/temp/data",
    "/temp/work",
    false,
    new PrintWriterLogger(new PrintWriter(System.err, true), "log", true));
manager.start();

FileResourceManager#stop() メソッドを呼び出すことでリソース マネージャを停止します。

boolean FileResourceManager#stop(int mode)

• mode
  • 停止の仕方を指定します。

mode 引数に指定する値は以下の定数です。いずれも実行中のトランザクションをどのように扱うかを表しています。

• ResourceManager.SHUTDOWN_MODE_NORMAL
  • 全てのトランザクションの完了を待ってから、リソース マネージャを停止します。
• ResourceManager.SHUTDOWN_MODE_ROLLBACK
  • 全てのトランザクションをロールバックして、リソース マネージャを停止します。
• ResourceManager.SHUTDOWN_MODE_KILL
  • 全てのトランザクションを直ちに停止して、リソース マネージャを停止します。ロールバックやコミットなどはせず、途中の状態であってもすぐに停止します。

manager.stop(ResourceManager.SHUTDOWN_NORMAL);

トランザクションの開始、コミット、ロールバック

リソース マネージャはトランザクションを識別するためにトランザクション ID を要求します。トランザクション ID を指定して FileResourceManager#startTransaction() メソッドを呼び出すと、トランザクションを開始します。

String txId = manager.generatedUniqueTxId();
manager.startTransaction(txId);

FileResourceManager#commitTransaction() メソッドを呼び出すとトランザクションをコミットします。

manager.commitTransaction(txId);

FileResourceManager#rollbackTransaction() メソッドを呼び出すとトランザクションをロールバックします。

manager.rollbackTransaction(txId);

ファイルの作成

FileResourceManager#createResource() メソッドを呼び出すことでファイルを作成することができます。

manager.createResource(txId, "test.txt");

コミットしたときに、実際にファイルが作成されます。ロールバックすれば、ファイルは作成されません。

また、 FileResourceManager#writeResource() メソッドを呼び出したときにファイルが存在しないと、自動でファイルが作成されます。

// ファイルが存在しない場合、自動で作成されます。
OutputStream out = manager.writeResource(txId, "test.txt");

ファイルの削除

FileResourceManager#deleteResource() メソッドを呼び出すことでファイルを削除することができます。

manager.deleteResource(txId, "test.txt");

コミットしたときに、実際にファイルが削除されます。ロールバックすれば、ファイルは削除されません。

ファイルへの書き込み

FileResourceManager#writeResource() メソッドを呼び出すことで、ファイルへの書き込みを行う出力ストリームを取得することができます。

OutputStream out = manager.writeResource(txId, "test.txt");
try {
    // 適当な書き込み処理
} finally {
    out.close();
}

コミットしたときに、実際に書き込んだ内容がファイルに反映されます。ロールバックすれば反映されません。

ファイルの読み込み

FileResourceManager#readResource() メソッドを呼び出すことで、ファイルの内容を読み込む入力ストリームを取得することができます。 FileResourceManager#readResource() メソッドは、トランザクション中のファイルを読み込む呼び出し方と、実際のファイルを読み込む呼び出し方があります。これは、引数にトランザクション ID を指定するかどうかで変わります。

引数にトランザクション ID を指定すると、トランザクション中のファイルを読み込みます。

InputStream in = manager.readResource(txId, "test.txt");
try {
    // 適当な読み込み処理
} finally {
    in.close();
}

この場合、トランザクション中で変更された内容を読み込むことができます。また、実際にはファイルが存在しなくてもトランザクション中でファイルを作成したならば、そのファイルを読み込むこともできます。

引数にトランザクション ID を指定しないと、実際のファイルを読み込みます。

InputStream in = manager.readResource("test.txt");
try {
    // 適当な読み込み処理
} finally {
    in.close();
}

この場合、実際のファイルの内容を読み込みます。トランザクションとは分離しているので、トランザクション中に作成したファイルは読み込めませんし、トランザクション中で変更した内容も読み込めません。

いずれの場合も、対象のファイルが存在しない場合は例外がスローされます。