Quick Start

本ドキュメントは、Object Storage Service 用 Java SDK v2 の導入と主要機能の利用方法について、詳細なガイドを提供します。

前提条件

ご利用のシステムにJavaがインストールされていることを確認してください。Java 1.7以降のバージョンを推奨します。バージョンは java -version で確認できます。

サンプルコード

Java SDK Rest v2 には、以下のような各種サンプルプログラムが用意されています。

SDKインストール

各種操作を行う前に、Java SDK をインストールしてください。SDKは GitHub からダウンロードできます。

Mavenプロジェクトへの依存関係追加

<dependency>
  <groupId>com.chinanetcenter.wcs.sdk</groupId>
  <artifactId>wcs-java-sdk-v2</artifactId>
  <version>1.0.3</version>
</dependency>

IntelliJ IDEAでJAR導入例

バージョン 1.0.0 の場合:

1. Java SDKパッケージをダウンロード
2. パッケージを解凍
3. wcs-java-sdk-rest-v2-1.0.0.jar と lib ディレクトリ内の全JARファイルをプロジェクトにコピー
4. IntelliJ IDEAでプロジェクトを選択し File -> Project Structure -> Modules -> Dependencies -> + -> JARs or directories を選択
5. コピーしたJARファイルをすべて選択してExternal Librariesへ追加

初期化

WosClient は、Java SDKでバケットやオブジェクトを管理するためのクライアントです。ご利用の前に、WosConfiguration を初期化し、必要に応じてデフォルト設定値を調整してください。

// コンソール：ユーザーセンター > ユーザー情報 > AccessKey管理 から Access Key（ak）および Secret Key（sk）を取得
// コンソール：オブジェクトストレージ > バケット概要 から endpoint と regionName を取得
String endPoint = "https://your-endpoint";
String regionName = "your regionName";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

WosConfiguration config = new WosConfiguration();
config.setSocketTimeout(30000);
config.setConnectionTimeout(10000);
config.setEndPoint(endPoint);
config.setRegionName(regionName);

// WosClientインスタンス作成
WosClient wosClient = new WosClient(ak, sk, config);
        
// WosClientを閉じる
wosClient.close();

WosClientの作成

// WosClientインスタンス作成
WosClient wosClient = new WosClient(ak, sk, config, regionName);

// WosClientを閉じる
wosClient.close();

注意: 新しいWosClientを作成する場合、Endpointを指定する必要があります。1つのプロジェクト内で1つ以上のWosClientインスタンスを持つことができます。WosClientはスレッドセーフで、並行利用をサポートします。

WosClientの設定

WosClientは、WosConfiguration により各種パラメータ（タイムアウト値、最大接続数等）の設定が可能です。主な設定項目は下記の通りです。

クイックスタート

Java SDKは以下のような基本操作に対応しています。

1. オブジェクトのアップロード

以下のコードは、オブジェクトをアップロードする例です。

wosClient.putObject("bucketname", "objectname", new ByteArrayInputStream("Hello WOS".getBytes()));

2. オブジェクトの取得

次のようにして、オブジェクトの内容を取得できます。

WosObject wosObject = wosClient.getObject("bucketname", "objectname");
InputStream content = wosObject.getObjectContent();
if (content != null) {
    BufferedReader reader = new BufferedReader(new InputStreamReader(content));
    while (true) {
        String line = reader.readLine();
        if (line == null)
            break;
        System.out.println("\n" + line);
    }
    reader.close();
}

注意:

• wosObject.getObjectメソッドは、コンテンツおよびメタデータを含むWosObjectインスタンスを返します。
• wosObject.getObjectContentでInputStream（内容）を取得できます。ストリームは使用後必ずクローズしてください。

3. バケット内オブジェクト一覧

オブジェクトを複数アップロードした後、バケット内の内容リストが必要になることがあります。例:

ObjectListing objectListing = wosClient.listObjects("bucketname");
for (WosObject wosObject : objectListing.getObjects()) {
    System.out.println(" - " + wosObject.getObjectKey() + "  " +  "(size = " + wosObject.getMetadata().getContentLength() + ")");
}

注意:

• wosClient.listObjectsはObjectListingインスタンスを返し、ObjectListing.getObjects経由で詳細を取得できます。
• デフォルトで最大1,000件まで返されます。

4. オブジェクトの削除

特定のオブジェクトの削除方法は以下の通りです。

wosClient.deleteObject("bucketname", "objectname");

5. 署名付きURLでオブジェクト取得

署名付きURLを生成してアクセスする例です。

TemporarySignatureRequest req = new TemporarySignatureRequest(HttpMethodEnum.GET, 300);
req.setBucketName(bucketName);
req.setObjectKey(objectKey);
TemporarySignatureResponse res = wosClient.createTemporarySignature(req);
System.out.println("一時署名URLを利用してオブジェクト取得:");
System.out.println("\t" + res.getSignedUrl());

6. WOSクライアント一般利用例

WOSクライアント経由でAPIを呼び出した後、例外がスローされなければ戻り値（SDK基本レスポンスまたはそのサブクラス）は有効です。例外発生時は、SDKカスタム例外オブジェクトからエラー情報を取得してください。

標準的な利用パターンは下記となります。

// プロジェクト全体で単一のグローバルWosClientインスタンスを維持することも可能です。
// WosClientはスレッドセーフで並列利用をサポートします。
WosClient wosClient = null; 
try {
    String endPoint = "https://your-endpoint";
    String regionName = "your regionName";
    String ak = "*** Provide your Access Key ***";
    String sk = "*** Provide your Secret Key ***";

    // 設定の作成
    WosConfiguration config = new WosConfiguration();
    config.setSocketTimeout(30000);
    config.setConnectionTimeout(10000);
    config.setEndPoint(endPoint);
    config.setRegionName(regionName);

    // WosClientインスタンス作成
    wosClient = new WosClient(ak, sk, config);
    // 例：オブジェクトアップロード
    HeaderResponse response = wosClient.putObject("bucketname", "objectname", new File("localfile"));  // 'localfile'はアップロードするファイルのパス。フルファイル名を指定してください。
    System.out.println(response);
} catch (WosException e) {
    System.out.println("HTTP Code: " + e.getResponseCode());
    System.out.println("Error Code: " + e.getErrorCode());
    System.out.println("Error Message: " + e.getErrorMessage());
    System.out.println("Request ID: " + e.getErrorRequestId());
    System.out.println("Host ID: " + e.getErrorHostId());
} finally {
    // WosClientインスタンスを閉じます。グローバルWosClient利用時は都度クローズ不要です。
    // wosClient.close() 呼び出し後は、再利用不可となりますのでご注意ください。
    if (wosClient != null) {
        try {
            // wosClient.close();
        } catch (IOException e) {
            // 必要に応じて例外処理を実装
        }
    }
}