This project provides a client library in Java that makes it easy to consume Microsoft Azure Storage services. For documentation please see the Storage API doc page and the quick start document. Please note that this version of the library is a compete overhaul of the current Azure Storage Java Client Library, and is based on the new Storage SDK architecture, also referred to as V10.
If you are looking for the Azure Storage Android SDK, please visit https://github.com/Azure/azure-storage-android.
Migrating to the newest version of the SDK will require a substantial rewrite of any component that interfaces with Azure Storage. Despite this, we feel the benefits offered by this new design are worth it, and we are happy to help with the transition! Please refer to the wiki for information on the core ideas behind the new design and best practices on how to use it effectively.
- Blob
- Create/Read/Update/Delete containers
- Create/Read/Update/Delete blobs
- Advanced Blob Operations wrapped in the TransferManager class
- Features new to V10
- Asynchronous I/O for all operations using the ReactiveX framework
- HttpPipeline which enables a high degree of per-request configurability and guaranteed thread safety
- Please see the wiki for more information
- 1-to-1 correlation with the Storage REST API for clarity and simplicity
To get the binaries of this library as distributed by Microsoft, ready for use within your project, you can use Maven.
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
<version>10.1.0</version>
</dependency>To get the source code of the SDK via git just type:
git clone git://github.com/Azure/azure-storage-java.git
cd ./azure-storage-java
git checkout New-Storage-SDK-V10-Preview
mvn compile
To download a copy of the source code, use the drop down menu on the left to select the branch New-Storage-SDK-V10-Preview and click "Download ZIP" on the right side of the page or click here. Unzip and navigate to the microsoft-azure-storage folder.
- Java 1.8+
- Jackson-Core is used for JSON and XML parsing.
- ReactiveX is used for reactive, asynchronous IO operations.
- Autorest-runtime is used to interact with auto-generated code.
- (Optional) Maven
The three dependencies, Jackson-Core, ReactiveX, and Autorest-runtime, will be added automatically if Maven is used. Otherwise, please download the jars and add them to your build path.
To use this SDK to call Microsoft Azure storage services, you need to first create an account.
Samples are provided in azure-storage/src/test/groovy/com/microsoft/azure/storage/Samples.java. The unit tests in the same directory can also be helpful.
The following is a quick example on how to upload some data to an azure blob and download it back. You may also run the samples in azure-storage/src/test/groovy/com/microsoft/azure/storage/Samples.java. For additional information on using the client libraries to access Azure services see the How To guides for blobs and the general documentation.
public class Sample {
/**
* This example shows how to start using the Azure Storage Blob SDK for Java.
*/
public void basicExample() throws InvalidKeyException, MalformedURLException {
// From the Azure portal, get your Storage account's name and account key.
String accountName = getAccountName();
String accountKey = getAccountKey();
// Use your Storage account's name and key to create a credential object; this is used to access your account.
SharedKeyCredentials credential = new SharedKeyCredentials(accountName, accountKey);
/*
Create a request pipeline that is used to process HTTP(S) requests and responses. It requires your accont
credentials. In more advanced scenarios, you can configure telemetry, retry policies, logging, and other
options. Also you can configure multiple pipelines for different scenarios.
*/
HttpPipeline pipeline = StorageURL.createPipeline(credential, new PipelineOptions());
/*
From the Azure portal, get your Storage account blob service URL endpoint.
The URL typically looks like this:
*/
URL u = new URL(String.format(Locale.ROOT, "https://%s.blob.core.windows.net", accountName));
// Create a ServiceURL objet that wraps the service URL and a request pipeline.
ServiceURL serviceURL = new ServiceURL(u, pipeline);
// Now you can use the ServiceURL to perform various container and blob operations.
// This example shows several common operations just to get you started.
/*
Create a URL that references a to-be-created container in your Azure Storage account. This returns a
ContainerURL object that wraps the container's URL and a request pipeline (inherited from serviceURL).
Note that container names require lowercase.
*/
ContainerURL containerURL = serviceURL.createContainerURL("myjavacontainerbasic");
/*
Create a URL that references a to-be-created blob in your Azure Storage account's container.
This returns a BlockBlobURL object that wraps the blob's URl and a request pipeline
(inherited from containerURL). Note that blob names can be mixed case.
*/
BlockBlobURL blobURL = containerURL.createBlockBlobURL("HelloWorld.txt");
String data = "Hello world!";
// Create the container on the service (with no metadata and no public access)
containerURL.create(null, null)
.flatMap(containersCreateResponse ->
/*
Create the blob with string (plain text) content.
NOTE: It is imperative that the provided length matches the actual length exactly.
*/
blobURL.upload(Flowable.just(ByteBuffer.wrap(data.getBytes())), data.length(),
null, null, null))
.flatMap(blobsDownloadResponse ->
// Download the blob's content.
blobURL.download(null, null, false))
.flatMap(blobsDownloadResponse ->
// Verify that the blob data round-tripped correctly.
FlowableUtil.collectBytesInBuffer(blobsDownloadResponse.body(null))
.doOnSuccess(byteBuffer -> {
if (byteBuffer.compareTo(ByteBuffer.wrap(data.getBytes())) != 0) {
throw new Exception("The downloaded data does not match the uploaded data.");
}
}))
.flatMap(byteBuffer ->
// Delete the blob we created earlier.
blobURL.delete(null, null))
.flatMap(blobsDeleteResponse ->
// Delete the container we created earlier.
containerURL.delete(null))
/*
This will synchronize all the above operations. This is strongly discouraged for use in production as
it eliminates the benefits of asynchronous IO. We use it here to enable the sample to complete and
demonstrate its effectiveness.
*/
.blockingGet();
}
}If building from sources, run mvn compile to build. No build steps are necessary if including the package as a maven dependency.
Please refer to CONTRIBUTING.md for information on how to run the tests.
Be sure to check out the Microsoft Azure Developer Forums on MSDN or the Developer Forums on Stack Overflow if you have trouble with the provided code.
If you would like to become an active contributor to this project please follow the instructions provided in Azure Projects Contribution Guidelines.
If you encounter any bugs with the library please file an issue in the Issues section of the project.
When sending pull requests, please send non-breaking PRs to the dev branch and breaking changes to the dev_breaking branch. Do not make PRs against master.