JAzure - Tutorial

A brief guide for using the JAzure API, the Java wrapper for the RESTful Cloud Windows Azure Storage Services API.

Using JAzure

To use JAzure, include JAzure-xxx.jar shipped in the distribution in your application classpath together with all the jar file dependencies included in the lib folder of the distribution.

Configuring JAzure

To use cloud storage, you must apply for a Storage account.
You have to provide your account credentials and the various Azure storage endpoint URLs in the jazure.properties file in your classpath. The format of the file is a standard Java properties file format. A sample file is provided in the root directory of the distribution.
JAzure uses Log4J for logging. If you want to configure log4j provide a log4j.properties file with the configuration needed in your classpath.

The Blob Storage API

Initialising BlobStorage

The BlobStorage class is the entry point for the Azure Blob Storage API.
  • To create an instance of BlobStorage, you need to specify the base URI of the Blob Storage Service to run against and your account credentials, and you can do that in two ways:
    • Using the configuration properties file: Just provide the URI and credentials in the jazure.properties file in your class path and use the empty constructor.
BlobStorage blobStorage = new BlobStorage(); 
  • Passing the configuration parameters to the constructor: for example:
String endPoint = "http://YOURACCOUNT.blob.core.windows.net";

String accountName = "YOURACCOUNT";
String accountSharedKey = "YOURKEY";
BlobStorage blobStorage = new BlobStorage(endPoint,accountName,accountSharedKey);

Operations on the account

  • To List all the containers in the BlobStorage Account..
List<BlobContainer> containers = blobStorage.listContainers(); 
  • To get a reference to a container with the name 'foo'
BlobContainer container = blobStorage.getBlobContainer("foo"); 

Operations on containers

After obtaining a reference to a BlobContainer, you can perform any of the following operations on it.
  • To create a container with the name 'test' in the actual storage service:
BlobContainer container = blobStorage.getBlobContainer("foo");
boolean created = container.create();
  • To delete a container with the name 'foo' from the actual storage service:
BlobContainer container = blobStorage.getBlobContainer("foo");
boolean deleted = container.delete();
  • To enumerate the blobs in the BlobContainer, we can use the BlobContainer#listBlobs(String prefix, boolean combineCommonPrefixes) method. By passing an empty string to the prefix parameters we can list all the Blobs.
BlobContainer container = blobStorage.getBlobContainer("foo");
List blobs = container.listBlobs("", false);
...
Following the Microsoft Storage Client Sample, the list returned contain BlobProperties objects (corresponding to each Blob), and String objects representing the common prefixes.
for(Object o:blobs){
if(o instanceof BlobProperties){
// ..Do Something with the BlobProperties object..

}
if(o instanceof String){
// ..Do Something with the commonPrefix String..

}
}
  • To create/upload a blob in the container, first create a BlobProperties instance containing the properties of your blob (name, content type, size,..etc.) :
BlobProperties blob = new BlobProperties("foo");
Second create a BlobContent object wrapping the content of the blob. In case the contents represent a file:
String filePath = "YourFilePath";
BlobContents blobContents = new BlobContents(new FileInputStream(new File(filePath)));
Now you are ready to upload the Blob in the service:
boolean created = container.createBlob(blob,blobContents,true);
  • To Download a blob from the storage service, first you need to create an output stream into which the blob contents will be written. For Example to download the blob to a file, you can create a FileOutputStream:
FileOutputStream fos = new FileOutputStream(new File("PathToDownLoadTo));
Then use the getBlobImpl(String blobName, OutputStream outStream) to download the blob of the given name to the given outputstream. The method will also returns the blob properties as an instance of BlobProperties:
BlobProperties blob = container.getBlobImpl("foo", fos); 
  • To Delete a blob, simply call the deleteBlob(String blobName) method on the container where the blob exsits.
boolean deleted = container.deleteBlob("foo"); 

The Queue Storage API

Initialising QueueStorage

The QueueStorage class is the entry point for the Azure Queue Storage API.
  • To create an instance of QueueStorage, you need to specify the base URI of the Queue Storage Service to run against and your account credentials, and you can do that in two ways
    • Using the configuration properties file: Just provide the URI and credentials in the jazure.properties file in your class path and use the empty constructor.
QueueStorage queueStorage = new QueueStorage(); 
  • Passing the configuration parameters to the constructor: for example:
String endPoint = "http://YOURACCOUNT.queue.core.windows.net";
String accountName = "YOURACCOUNT";
String accountSharedKey = "YOURKEY";
QueueStorage queueStorage = new QueueStorage(endPoint,accountName,accountSharedKey);

Operations on the account

  • To List all the queues in the QueueStorage Account..
List<Queue> queues = queueStorage.listQueues(); 
  • To get a reference to a queue in the queue storage with the name 'foo'
Queue q = queueStorage.getQueue("foo"); 

Operations on queues

After obtaining a reference to a Queue, you can perform any of the following operations on it.
  • To create a queue with the name 'foo' in the actual storage service:
Queue q = queueStorage.getQueue("foo");
boolean created = q.create();
  • To delete a queue with the name 'foo' from the actual storage service:
Queue q = queueStorage.getQueue("foo");
boolean deleted = q.delete();
  • To put a message in the queue, we first instantiate a QueueMessage object to wrap the message and then call the Queue#putMessages(QueueMessage message) method:
Queue q = queueStorage.getQueue("foo");
q.putMessage(new QueueMessage("Hello World !"));
  • To pop messages from the front of the queue, we use the Queue#getMessages(int nMessages) method. For example to retrieve a maximum number of 5 messages from the fron of the queue:
Queue q = queueStorage.getQueue("foo");
List<QueueMessage> messages = q.getMessages(5);
  • To clear all the messages in the queue:
Queue q = queueStorage.getQueue("foo");
q.clearMessages();

The Table Storage API

Initialising TableStorage

The TableStorage class is the entry point for the Azure Table Storage API.
  • To create an instance of TableStorage, you need to specify the base URI of the Table Storage Service to run against and your account credentials, and you can do that in two ways:
    • Using the configuration properties file: Just provide the URI and credentials in the jazure.properties file in the your class path and use the empty constructor.
TableStorage tableStorage = new TableStorage(); 
  • Passing the configuration parameters to the constructor: for example:
String endPoint = "http://YOURACCOUNT.table.core.windows.net";
String accountName = "YOURACCOUNT";
String accountSharedKey = "YOURKEY";
TableStorage tableStorage = new TableStorage(endPoint,accountName,accountSharedKey);

Operations on the account

  • To list all the tables in the TableStorage Account..
List<Table> tables = tableStorage.listTables(); 
  • To create a new table in the table storage with the name 'foo'
boolean created = tableStorage.createTable("foo"); 
  • To get a reference to a table with the name 'foo'
Table myTable = tableStorage.getTable("foo"); 

Table Storage Entities

As stated in the Microsoft MSDN library, "Tables store data as collections of entities. Entities are similar to rows. An entity has a primary key and a set of properties. A property is a name, typed-value pair, similar to a column".

JAzure models entities and properties by introducing the TableStorageEntity and TableStorageProperty classes.
The TableStorageProperty encapsulates a String for the type of the property and an Object containing the value of the property.
The TableStorageEntity encapsulates a Map of which the keys are the names of the properties and the values are instances of TableStorageProperty.

To illustrate how to use these classes to create table entities, the following code shows an example of creating a table entity identified by a pair of arbitrary row and partition keys, and then adding properties to it:
TableStorageEntity ent = new TableStorageEntity("11","xxx");
entity.getProperties().put("employeeName",new TableStorageProperty(TableStorageProperty.EdmString,"Martin"));
entity.getProperties().put("employeeSalary",new TableStorageProperty(TableStorageProperty.EdmInt32,new Integer(35000)));

Operations on Tables

After obtaining a reference to a Table, you can perform any of the following operations on it.
  • To insert a new entity into the table, create an instance of TableStorageEntity as describe above then simply use the Table#insertEntity(TableStorageEntity entity) method:
// create the entity
TableStorageEntity ent = new TableStorageEntity("11","xxx");
entity.getProperties().put("employeeName",new TableStorageProperty(TableStorageProperty.EdmString,"Martin"));
entity.getProperties().put("employeeSalary",new TableStorageProperty(TableStorageProperty.EdmInt32,new Integer(35000)));
//insert it
boolean inserted = myTable.insertEntity(entity)
  • To retrieve a single entity of a given pair of partition and row keys.
TableStorageEntity entity = myTable.getEntity("11","xxx");
  • To update an existing entity in the table, modify the properties you want then use the Table#updateEntity(TableStorageEntity entity) method:
entity.getProperties().put("employeeSalary",new TableStorageProperty(TableStorageProperty.EdmInt32,new Integer(37000)));
boolean updated=myTable.updateEntity(entity);
  • To perform queries on table entities using the querying capabilities of the Windows Azure Table Storage API:
List<TableStorageEntity> entites = myTable.queryEntities("PartitionKey%20eq%20'11'");
Note that the query expression "PartitionKey='11'" is URL-encoded.

For detailed explanation of writing table query expressions, see the related MSDN document here.
  • To delete an existing entity from the table:
boolean deleted=myTable.deleteEntity(entity);

MSDN Documentation of the Windows Azure Storage Services API

Please refer to the Microsoft MSDN library for a complete documentation of the Windows Azure Storage Services API. http://msdn.microsoft.com/en-gb/library/dd179355.aspx

Last edited Sep 27, 2009 at 1:50 PM by dyaaalbakour, version 13

Comments

No comments yet.