December 20, 2013

Windows Azure Storage Client Library for Java v. 0.5.0

Windows Azure Storage Client Library for Java v. 0.5.0 がリリースされました

2013/12/27 Windows Azure Japan Team Blog 公式 谷訳出ました。 Java v. 0.5.0 用 Windows Azure ストレージ クライアント ライブラリ

以下にざっくりと訳します。

抄訳 Windows Azure Storage Team Blog - Windows Azure Storage Client Library for Java v. 0.5.0

このリリースでは、logging support, 新しい API overloads、そして 2013-08-15 REST[1]が完全にサポートされています。今までのようにソースコードは、github Windows Azure Storage libraries for Javaで公開されています。[2]従来のようにmaven のレポジトリに登録されています。

<dependency>  
     <groupId>com.microsoft.windowsazure.storage</groupId>
     <artifactId>microsoft-windowsazure-storage-sdk</artifactId>
     <version>0.5.0</version>
</dependency>

エミュレータ ガイダンス

現在のAzure SDK(2.2)のエミュレータは、2013-08-15 RESTをサポートしていません。今後数ヶ月以内にサポートしたものを出す予定です。

Samples

githubのソースのなかに、幾つかの重要なシナリを説明するサンプルがあります。指定されたサンプルを実行するには、サンプルプロジェクトをロードし、ストレージの資格情報を提供するために、Utility.javaの次の行を更新します。

public static final String storageConnectionString = "DefaultEndpointsProtocol=http;AccountName=[ACCOUNT_NAME];AccountKey=[ACCOUNT_KEY]";

fiddler を使ってサンプル実行中の traffic を見たい場合は、Utility.java の下記の2行をコメントアウトを外してください。

// System.setProperty("http.proxyHost", "localhost");
// System.setProperty("http.proxyPort", "8888");

Note about Packaging and Versioning

このリリースで、大きな Windows Azure SDK for Java から、ストレージパッケージを独立させました。現在、既存のSDKを活用している開発者は、それに応じて依存関係を更新する必要があります。さらに、パッケージ名は、この新しい構造を反映するように変更されました：

  • com.microsoft.windowsazure.storage - RetryPolicies、LocationMode、StorageException、StorageAccountなどサービス間で共通しているすべてのpublicクラス
  • com.microsoft.windowsazure.storage.blob - Blob convenience implementation、Windows Azure Blobを利用しているアプリケーションは、importしてください。
  • com.microsoft.windowsazure.storage.queue - Queue convenience implementation、Windows Azure Queueを利用するアプリケーションは、importしてください。
  • com.microsoft.windowsazure.storage.table - Table convenience implementation、Windows Azure Tableを利用しているアプリケーションは、importしてください。

さらに詳しい情報は、以下の Change Log & Breaking Changes のセクションを見て下さい。

また、Storage Client SDK componentでは、Semantic Versioningを採用します。これは、SDKを活用する開発者に一貫した予測可能なバージョン管理指針を提供するのに役立ちます。

Whats New

Java client library の 0.5.0 では、2013-08-15 REST service version の全ての機能[1]をサポートします。

Support for Read Access Geo Redundant Storage

このリリースでは、secondary region の storage account data の読み取りアクセス (RA-GRS)[3]を完全にサポートしています。クライアントオブジェクト上の位置モードを設定し、getServiceStatsを起動すると、以下の例に示されている。LocationModeもRequestOptionsオブジェクト上に設定することで、リクエストごとに設定することができます。

下記の例では、client objectの location mode を設定して getServiceStats を呼び出すことで、 replication の状態を取得しています。

CloudStorageAccount httpAcc = CloudStorageAccount.parse(connectionString);
CloudTableClient tClient = httpAcc.createCloudTableClient();

// Set the LocationMode to SECONDARY_ONLY since getServiceStats is supported only on the secondary endpoints.
tClient.setLocationMode(LocationMode.SECONDARY_ONLY);
ServiceStats stats = tClient.getServiceStats();
Date lastSyncTime = stats.getGeoReplication().getLastSyncTime();

System.out.println(String.format("Replication status = %s and LastSyncTime = %s",stats.getGeoReplication().getStatus().toString(), lastSyncTime != null ? lastSyncTime.toString(): "empty"));

Expanded Table Protocol Support (JSON)

table traffic で、JSONがサポートされました。TableClient の setTablePayloadFormat() で、TablePayloadFormatを指定することでJSONformatを使うことができます。
CloudStorageAccount httpAcc = CloudStorageAccount.parse(connectionString);
CloudTableClient tableClient = httpAcc.createCloudTableClient();

// Set the payload format to JsonNoMetadata.
tableClient.setTablePayloadFormat(TablePayloadFormat.JsonNoMetadata);

JsonNoMetadataを指定した場合メタデータがpayloadに有りません、その場合プロパティの型はpropertyResolver を用意して下記のようにコードで解釈します。

public static class Class1 extends TableServiceEntity implements PropertyResolver {    
    private String A;
    private byte[] B;

    public String getA() {
	return this.A;
    }
    
    public byte[] getB() {
	return this.B;
    }
    
    public void setA(final String a) {
	this.A = a;
    }
    
    public void setB(final byte[] b) {
	this.B = b;
    }
    
    @Override
    public EdmType propertyResolver(String pk, String rk, String key, String value) {
	if (key.equals("A")) {
	    return EdmType.STRING;
	}
	else if (key.equals("B")) {
	    return EdmType.BINARY;
	}
	return null;
    }
    
}

この、propertyResolver は、TableRequestOptions にセットします。

Class1 ref = new Class1();
ref.setA("myPropVal");
ref.setB(new byte[] { 0, 1, 2 });
ref.setPartitionKey("testKey");
ref.setRowKey(UUID.randomUUID().toString());

options.setPropertyResolver(ref);

Table Insert Optimizations

以前のバージョンでは、Table Insertのレスポンスでentity全体が返されていましたが、このバージョンから inserts が成功したときは 204 (no-content) でbodyは空がかえるようになりました。従来と同じように動作させるには、insert(TableEntity, boolean) method に true を指定します。

Table Reflection Optimizations

clients が、POJOを永続化するときに、繰り返しの reflection calls を無くすために、type や property information をcacheするようにしました。この最適化の結果劇的にCPU時間が削減されます。このCache機能を無効にするには、TableServiceEntity.setReflectedEntityCacheDisabled(true) を使って下さい。

New APIs and overloads

customer feedback から下記のAPIを追加しました、

  • CloudBlob.downloadRange
  • CloudBlob.downloadToByteArray
  • CloudBlob.downloadRangeToByteArray
  • CloudBlob.uploadFromByteArray
  • CloudBlob.uploadFromByteArray
  • CloudBlob.downloadToFile
  • CloudBlob.uploadFromFile
  • CloudBlockBlob.uploadText
  • CloudBlockBlob.downloadText

Logging

0.5.0 リリースでは、SLF4Jlogging facade をサポートしています。

詳細省略

Change Log & Breaking Changes

このリリースには、 2013-08-15 REST[1]のサポート以外にも幾つかの重要な変更があります。要点を下記にまとめます。

Common

  • Package の再構築
  • RetryResultが追加機能を提供しRetryInfoに置き換えられています
  • request中に起きるevent operations (event firingを含む) は、同期では無くなりました。 (thread safety は、event listenersのCopyOnWriteArrayList で保証されます)
  • OperationContext.sendingRequest eventは、 headerを変更することができるように connection が established されるまえに fireされます

Blob

  • BlobdownloadRangeはStreamにダウンロードします。以前のdownloadRangeはdownloadRangeToByteArrayに変更されました
  • sparse page blob feature は削除されました
  • CloudBlobContainer.createIfNotExistはCloudBlobContainer.createIfNotExistに改名されました
  • CloudBlobClient.streamMinimumReadSizeInBytesは削除されました。この機能は、はCloudBlob.streamMinimumReadSizeInBytesで提供さえます（これは、Client毎のではなくBlob毎の設定です）
  • CloudBlobClient.pageBlobStreamWriteSizeInBytesとCloudBlobClient.writeBlockSizeInBytesは削除されました。この機能は、CloudBlob.streamWriteSizeInBytesで提供されます

Table

  • TableResultから id field が削除されました（getId、setIdも）
  • CloudTable.createIfNotExistはCloudTable.createIfNotExistに名前が変更されました
  • Insert 操作はcontents echoをしません。
  • デフォルトのPayload形式は、JsonMinimalMetadataになりました。CloudTableClient.setTablePayloadFormatで全てのリクエスト、あるいは個々のリクエストでTableRequestOptions.setTablePayloadFormatを使ってpayload formatを変更することができます

Queue

  • CloudQueue.createIfNotExistはCloudQueue.createIfNotExistに名前が変更されました

最後に

0.4 にあった、Azure SDK for Java 0.4.6 long値のfilter BUGは無事改修されているようです。https://github.com/WindowsAzure/azure-storage-java/commit/834daae4e23b51e16e65e5bbf13096075d1f47ca#diff-f8d410db4741b0e56a8050948b11115c

互換性の問題などから、0.4を使い続ける場合は引き続き注意が必要です。


[1](1, 2, 3) version 2013-08-15 storage英語日本語SATO NAOKI訳
[2]0.4 までは、azure-sdk-for-javaだったのですが、レポジトリが変わり。 0.5からは、azure-storage-javaになりました。.NETのStorage Clientと同じような名前変更がされたようです。
[3]Windows Azure ストレージの冗長オプションと読み取りアクセス地理冗長ストレージ
Filed under: Azure, Azure SDK, Azure Storage
Tags: 2013-08-15, Azure, Java, Release, Azure Storage