Java で OpenStack Swift からファイルをインポート
OpenStack4j を使い、OpenStack Swift のオブジェクトをローカルファイルにダウンロードします。以下の完全な Java プログラムは空のオブジェクトにも対応し、HTTP レスポンスとダウンロードしたバイト数を検証します。ダウンロードが成功するまで保存先は変更しません。
Java 環境の準備
この例では、Linux 上の POSIX シェル、UTF-8 ロケール、アトミックな移動に対応したローカルファイルシステムを使用します。ロケールは、JVM がコマンドラインのファイル名をデコードする方法を決定します。保守が継続されている JDK 21 と Apache Maven 3.10 を個別にインストールしてください。以下の手順は OpenJDK 21.0.12.1 と Maven 3.10.0 でテスト済みです。Maven 3.9.11 でも正常に動作しました。
既存の Swift コンテナーとオブジェクトにプロジェクトスコープでアクセスできる Keystone v3 アカウントも必要です。プロバイダーの認証情報設定またはシークレットマネージャーで、次の環境変数を用意してください。
| 変数 | 値 |
|---|---|
OS_AUTH_URL | /v3 で終わる Keystone URL |
OS_USERNAME, OS_PASSWORD | ユーザー名とパスワード |
OS_USER_DOMAIN_NAME | ユーザーが所属するドメイン |
OS_PROJECT_NAME, OS_PROJECT_DOMAIN_NAME | プロジェクトとそのドメイン |
OS_REGION_NAME | 公開オブジェクトストレージエンドポイントがあるリージョン |
ユーザーとプロジェクトは異なるドメインに所属していてもかまいません。Keystone と、そのサービスカタログにある Swift エンドポイントの両方で HTTPS を使用し、JVM が信頼する証明書を使用してください。パスワードをコミットしたり、コピーするシェルコマンドに含めたりしないでください。このチュートリアルでは既存のオブジェクトを読み取ります。コンテナーの作成やアクセスポリシーの変更は行いません。
プロジェクトを作成する前に、各実行ファイルを確認してください。次のブロックを現在のシェルに貼り付けてください。サブシェルを使うため、現在のシェルの作業ディレクトリとオプションは変わりません。swift-import ディレクトリがすでに存在する場合、その内容を変更せずにセットアップが失敗します。
(
cd -P . &&
swift_parent=$PWD &&
while :; do
if [ -e "$swift_parent/.mvn" ] || [ -L "$swift_parent/.mvn" ]; then
printf 'Run setup outside an existing Maven project.\n' >&2
exit 1
fi
[ "$swift_parent" = / ] && break
swift_parent=${swift_parent%/*}
[ -n "$swift_parent" ] || swift_parent=/
done &&
command -v java >/dev/null &&
command -v javac >/dev/null &&
command -v mvn >/dev/null &&
command -v locale >/dev/null &&
[ "$(locale charmap)" = UTF-8 ] &&
mkdir swift-import &&
cd swift-import &&
mkdir -p src/main/java
)
次の完全なファイルを swift-import/pom.xml として保存してください。OpenStack4j 3.12 は Maven Central で公開されているリリースです。このアーティファクトには RESTEasy コネクターが含まれています。
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>swift-import</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>com.github.openstack4j.core</groupId>
<artifactId>openstack4j</artifactId>
<version>3.12</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.8.1</version>
</plugin>
</plugins>
</build>
</project>
セットアップのガード処理は、ファイルを作成する前に祖先ディレクトリの
.mvn 設定を検出すると処理を拒否します。Maven は上位のプロジェクトから起動オプションを継承することがあります。この例を既存のアプリケーションに組み込む前に、それらを確認してください。依存関係の解決に失敗した場合は、ネットワークまたはリポジトリへのアクセスを修正し、以下のビルドコマンドを再実行してください。保存したソースと
pom.xml は残しておいてください。
OpenStack Swift への接続
このプログラムを swift-import/src/main/java/SwiftImport.java として保存してください。Keystone で認証し、指定したプロジェクトとプロジェクトドメインにトークンのスコープを設定して、要求したリージョンを選択します。Keystone の ID モデルでは、これらはそれぞれ独立した選択です。
import java.io.IOException;
import java.io.InputStream;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import org.openstack4j.api.OSClient.OSClientV3;
import org.openstack4j.api.exceptions.ResponseException;
import org.openstack4j.core.transport.Config;
import org.openstack4j.core.transport.HttpResponse;
import org.openstack4j.model.common.Identifier;
import org.openstack4j.model.storage.object.SwiftObject;
import org.openstack4j.openstack.OSFactory;
public class SwiftImport {
private static String encodeName(String value, boolean object) {
String[] segments = value.split("/", -1);
if (!object && segments.length != 1) {
throw new IllegalArgumentException("A container name cannot contain a slash");
}
for (int index = 0; index < segments.length; index++) {
String segment = segments[index];
if (segment.isEmpty() || segment.equals(".") || segment.equals("..")) {
throw new IllegalArgumentException("Empty and dot path segments are unsupported");
}
segments[index] = URLEncoder.encode(segment, StandardCharsets.UTF_8).replace("+", "%20");
}
return String.join("/", segments);
}
private static String required(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("Missing environment variable: " + name);
}
return value;
}
private static long download(OSClientV3 os, String container, String object,
Path destination) throws IOException {
SwiftObject remote = os.objectStorage().objects().get(container, object);
if (remote == null) {
throw new IOException("Object not found");
}
long expected = remote.getSizeInBytes();
Path partial = Files.createTempFile(destination.getParent(), ".swift-import-", ".part");
try {
long written;
// The download API exposes its response without mapping HTTP errors to exceptions.
try (HttpResponse response = remote.download().getHttpResponse()) {
if (response.getStatus() != 200) {
throw new IOException("Download rejected (HTTP " + response.getStatus() + ")");
}
try (InputStream input = response.getInputStream()) {
if (input == null) {
throw new IOException("Missing download stream");
}
written = Files.copy(input, partial, StandardCopyOption.REPLACE_EXISTING);
}
}
if (written != expected) {
throw new IOException("Downloaded byte count does not match object metadata");
}
Files.move(partial, destination,
StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
return written;
} finally {
Files.deleteIfExists(partial);
}
}
public static void main(String[] args) {
if (args.length != 3) {
System.err.println("Usage: SwiftImport CONTAINER OBJECT DESTINATION");
System.exit(2);
}
try {
String container = encodeName(args[0], false);
String object = encodeName(args[1], true);
Config config = Config.newConfig().withConnectionTimeout(10_000);
OSClientV3 os = OSFactory.builderV3()
.endpoint(required("OS_AUTH_URL"))
.credentials(required("OS_USERNAME"), required("OS_PASSWORD"),
Identifier.byName(required("OS_USER_DOMAIN_NAME")))
.scopeToProject(Identifier.byName(required("OS_PROJECT_NAME")),
Identifier.byName(required("OS_PROJECT_DOMAIN_NAME")))
.withConfig(config)
.authenticate()
.useRegion(required("OS_REGION_NAME"));
Path destination = Path.of(args[2]).toAbsolutePath();
long written = download(os, container, object, destination);
System.out.println("Imported " + written + " bytes to " + destination);
} catch (ResponseException error) {
System.err.println("OpenStack request failed (HTTP " + error.getStatus() + ").");
System.exit(1);
} catch (Exception error) {
System.err.println("Import failed (" + error.getClass().getSimpleName()
+ "). Check configuration, object access, and local storage before retrying.");
System.exit(1);
}
}
}
Swift からのファイルのインポート
swift-import があるディレクトリで、次のブロックを貼り付けてください。exports と reports/report.bin を、既存のコンテナー名と正確なオブジェクト名に置き換えてください。ローカルの保存先は swift-import からの相対パスで、親ディレクトリがすでに存在している必要があります。
コンテナー名とオブジェクト名は、空白やパーセント記号も含め、未加工の UTF-8 で渡してください。プログラムは OpenStack4j を呼び出す前に、URL の各パスセグメントをエンコードします。コンテナー名に / は使用できません。この例のオブジェクトパスには、空のセグメント、.、.. のセグメントを含められません。ローカルの保存先パスも有効な UTF-8 である必要があります。
(
cd swift-import &&
mvn -B package dependency:copy-dependencies &&
java -cp 'target/classes:target/dependency/*' SwiftImport \
'exports' 'reports/report.bin' './download.bin'
)
成功すると、インポートしたバイト数と保存先の絶対パスが表示されます。空のオブジェクトではゼロバイトのファイルが作成され、インポートしたバイト数はゼロと報告されます。ビルドに失敗すると、target/ に古いコンパイル済みクラスが残っている場合も含め、Java コマンドは実行されません。
プログラムは Swift の HEAD レスポンスから期待するサイズを取得し、完全な GET の成功を必須とし、期待するサイズがゼロの場合もコピーしたバイト数を比較します。これらの操作は Swift のオブジェクト API リファレンスに記載されています。インポート中はリモートオブジェクトを変更しないでください。サイズの比較では、サイズが同じ内容の変更は検出できません。その検証が必要な場合は、信頼できる発行元が提供するチェックサムを別途比較してください。
既存の保存先が置き換えられるのは、ダウンロードが完了し、サイズの検証を終えた場合だけです。一時ファイルは保存先と同じディレクトリに置かれるため、配置にアトミックな移動を使用できます。ファイルシステムでこの移動を実行できない場合、非アトミックなコピーには切り替えず、インポートが失敗します。Java のアトミックな置換の動作はファイルシステムに依存します。この置換処理は Linux でテスト済みです。保存先ごとにインポーターは一つだけ使用し、親ディレクトリは自身の管理下に置いてください。
大きなファイルの効率的な処理
OpenStack4j 3.12 のデフォルトの RESTEasy コネクターは、入力ストリームを公開する前にレスポンス全体をバッファーに格納します。JVM の使用可能なメモリに余裕を持って収まるオブジェクトを選んでください。コピーバッファーを大きくしたり、コピーループから進捗を表示したりしても、このメモリ割り当てはなくなりません。
エラー処理と再試行の実装
オブジェクトが存在しない場合、読み取りが拒否された場合、転送が不完全な場合、ローカルへの書き込みに失敗した場合、コマンドはゼロ以外のステータスを返します。アプリケーションレベルでの試行は一回で、接続タイムアウトとして 10 秒を要求します。転送全体の期限はありません。この RESTEasy バージョンでは、withReadTimeout は接続プールからの接続取得を設定するパラメーターであり、ソケットの読み取りタイムアウトではないため、ここでは省略しています。レスポンスが停止すると、接続が閉じられるまで待機することがあります。アプリケーションに経過時間の上限が必要な場合は、監視下のプロセスを使用してください。
エラーが処理された後は、その原因を修正し、同じビルド・実行ブロックを再実行してください。ダウンロードに失敗すると、部分的なファイルは削除され、以前の保存先はそのまま残ります。プロセスの強制終了やマシンのクラッシュによって、.swift-import-*.part ファイルが残ることがあります。停止したインポートに属する、使われなくなったファイルだけを削除してください。別のインポーターが動作している間は、一時ファイルを一括削除しないでください。
エラー処理の注意点
- 認証に失敗した場合は、Keystone v3 URL、ユーザードメイン、プロジェクトドメイン、認証情報を確認してください。
- オブジェクトが存在しないかアクセスを拒否された場合は、正確な名前とプロジェクトの読み取り権限を確認してください。ログインの成功は、ダウンロード権限があることを意味しません。
- ローカル I/O に失敗した場合は、保存先の既存の親ディレクトリ、書き込み権限、ディスク容量、アトミックな移動への対応を確認してください。ダウンロードの失敗を回避するために、以前の保存先を削除しないでください。
パフォーマンス最適化のヒント
認証とダウンロードは同じスレッドで行ってください。OpenStack4j は有効なセッションをスレッドローカル値に保存します。スレッドのガイドでは、別のスレッドでトークンからクライアントを生成する方法を説明しています。この単一オブジェクト用のコマンドは一つのスレッドを使用し、ワーカープールや自動再試行は実装していません。
アプリケーションに組み込む際は、ダウンロード、バイト数の検証、配置を一連の処理として扱ってください。download が成功した後にのみ、利用側のコードにローカルパスを返してください。
