#Microsoft Azure DocumentDB Java SDK
This project provides a client library in Java that makes it easy to interact with Azure DocumentDB. For documentation please see the Microsoft Azure Java Developer Center and the JavaDocs.
##Download ###Option 1: Via Maven
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-documentdb</artifactId>
<version>1.8.1</version>
</dependency>
###Option 2: Source Via Git
To get the source code of the SDK via git just type:
git clone git://github.com/Azure/azure-documentdb-java.git
###Option 3: Source Zip
To download a copy of the source code, click "Download ZIP" on the right side of the page or click here.
##Minimum Requirements
- Java Development Kit 7
- (Optional) Maven
- Apache Commons Lang 3.3.2 (org.apache.commons / commons-lang3 / 3.3.2)
- Apache HttpClient 4.2.5 (org.apache.httpcomponents / httpclient / 4.2.5)
- Apache HttpCore 4.2.5 (org.apache.httpcomponents / httpcore / 4.2.5)
- Jackson Data Mapper 1.8 (org.codehaus.jackson / jackson-mapper-asl / 1.8.5)
- JSON 20140107 (org.json / json / 20140107)
- JUnit 4.12 (junit / junit / 4.12)
- mockito 1.10.19 (org.mockito / mockito-core / 1.10.19)
Dependencies will be added automatically if Maven is used. Otherwise, please download the jars and add them to your build path.
##Usage
To use this SDK to call Azure DocumentDB, you need to first create an account.
You can follow this tutorial to help you get started.
importjava.io.IOException;
importjava.util.List;
importcom.google.gson.Gson;
importcom.microsoft.azure.documentdb.ConnectionPolicy;
importcom.microsoft.azure.documentdb.ConsistencyLevel;
importcom.microsoft.azure.documentdb.Database;
importcom.microsoft.azure.documentdb.Document;
importcom.microsoft.azure.documentdb.DocumentClient;
importcom.microsoft.azure.documentdb.DocumentClientException;
importcom.microsoft.azure.documentdb.DocumentCollection;
importcom.microsoft.azure.documentdb.RequestOptions;
publicclassHelloWorld {
// Replace with your DocumentDB end point and master key.privatestaticfinalStringEND_POINT = "[YOUR_ENDPOINT_HERE]";
privatestaticfinalStringMASTER_KEY = "[YOUR_KEY_HERE]";
// Define an id for your database and collectionprivatestaticfinalStringDATABASE_ID = "TestDB";
privatestaticfinalStringCOLLECTION_ID = "TestCollection";
// We'll use Gson for POJO <=> JSON serialization for this sample.// Codehaus' Jackson is another great POJO <=> JSON serializer.privatestaticGsongson = newGson();
publicstaticvoidmain(String[] args) throwsDocumentClientException,
IOException {
// Instantiate a DocumentClient w/ your DocumentDB Endpoint and AuthKey.DocumentClientdocumentClient = newDocumentClient(END_POINT,
MASTER_KEY, ConnectionPolicy.GetDefault(),
ConsistencyLevel.Session);
// Start from a clean state (delete database in case it already exists).documentClient.deleteDatabase("dbs/" + DATABASE_ID, null);
// Define a new database using the id above.DatabasemyDatabase = newDatabase();
myDatabase.setId(DATABASE_ID);
// Create a new database.myDatabase = documentClient.createDatabase(myDatabase, null)
.getResource();
System.out.println("Created a new database:");
System.out.println(myDatabase.toString());
System.in.read();
// Define a new collection using the id above.DocumentCollectionmyCollection = newDocumentCollection();
myCollection.setId(COLLECTION_ID);
// Set the provisioned throughput for this collection to be 1000 RUs.RequestOptionsrequestOptions = newRequestOptions();
requestOptions.setOfferThroughput(1000);
// Create a new collection.myCollection = documentClient.createCollection(
myDatabase.getSelfLink(), myCollection, requestOptions)
.getResource();
System.out.println("Created a new collection:");
System.out.println(myCollection.toString());
System.in.read();
// Create an object, serialize it in to JSON, and wrap it in to a// document.SomePojoandrewPojo = newSomePojo("123", "Andrew Liu", "andrl@microsoft.com");
StringandrewJson = gson.toJson(andrewPojo);
DocumentandrewDocument = newDocument(andrewJson);
// Create the 1st document.andrewDocument = documentClient.createDocument(
myCollection.getSelfLink(), andrewDocument, null, false)
.getResource();
System.out.println("Created 1st document:");
System.out.println(andrewDocument.toString());
System.in.read();
// Create another object, serialize it in to JSON, and wrap it in to a// document.SomePojomimiPojo = newSomePojo("456", "Mimi Gentz",
"mimig@microsoft.com");
StringsomePojoJson = gson.toJson(mimiPojo);
DocumentmimiDocument = newDocument(somePojoJson);
// Create the 2nd document.mimiDocument = documentClient.createDocument(
myCollection.getSelfLink(), mimiDocument, null, false)
.getResource();
System.out.println("Created 2nd document:");
System.out.println(mimiDocument.toString());
System.in.read();
// Query documentsList<Document> results = documentClient
.queryDocuments(
myCollection.getSelfLink(),
"SELECT * FROM myCollection WHERE myCollection.email = 'andrl@microsoft.com'",
null).getQueryIterable().toList();
System.out.println("Query document where e-mail address = 'andrl@microsoft.com':");
System.out.println(results.toString());
System.in.read();
// Replace Document Andrew with ShireeshandrewPojo = gson.fromJson(results.get(0).toString(), SomePojo.class);
andrewPojo.setName("Shireesh Thota");
andrewPojo.setEmail("Shireesh.Thota@microsoft.com");
andrewDocument = documentClient.replaceDocument(
andrewDocument.getSelfLink(),
newDocument(gson.toJson(andrewPojo)), null)
.getResource();
System.out.println("Replaced Andrew's document with Shireesh's contact information");
System.out.println(andrewDocument.toString());
System.in.read();
// Delete Shireesh's DocumentdocumentClient.deleteDocument(andrewDocument.getSelfLink(), null);
System.out.println("Deleted Shireesh's document");
System.in.read();
// Delete DatabasedocumentClient.deleteDatabase(myDatabase.getSelfLink(), null);
System.out.println("Deleted database");
System.in.read();
}
}The sample code above depends on a sample Plain Old Java Object (POJO) class, which is defined as follows:
classSomePojo {
privateStringid;
privateStringname;
privateStringemail;
publicSomePojo(Stringid, Stringname, Stringemail) {
super();
this.id = id;
this.name = name;
this.email = email;
}
publicStringgetEmail() {
returnemail;
}
publicStringgetId() {
returnid;
}
publicStringgetName() {
returnname;
}
publicvoidsetEmail(Stringemail) {
this.email = email;
}
publicvoidsetId(Stringid) {
this.id = id;
}
publicvoidsetName(Stringname) {
this.name = name;
}
}The following code Illustrates how to create a partitioned collection and use the partition key to access documents:
// Create a partition key definition that specifies the path to the property// within a document that is used as the partition key. PartitionKeyDefinitionpartitionKeyDef = newPartitionKeyDefinition();
ArrayList<String> paths = newArrayList<String>();
paths.add("/id");
partitionKeyDef.setPaths(paths);
// Create a collection with the partition key definition and set the offer throughput// to 10100 RU per second.DocumentCollectionmyPartitionedCollection = newDocumentCollection();
myPartitionedCollection.setId(COLLECTION_ID_PARTITIONED);
myPartitionedCollection.setPartitionKey(partitionKeyDef);
RequestOptionsoptions = newRequestOptions();
options.setOfferThroughput(10100);
myPartitionedCollection = documentClient.createCollection(
myDatabase.getSelfLink(), myCollection, options).getResource();
// Insert a document into the created collection.Stringdocument = "{ 'id': 'document1', 'description': 'this is a test document.' }";
DocumentnewDocument = newDocument(document);
newDocument = documentClient.createDocument(myPartitionedCollection.getSelfLink(),
newDocument, null, false).getResource();
// Read the created document, specifying the required partition key in RequestOptions.options = newRequestOptions();
options.setPartitionKey(newPartitionKey("document1"));
newDocument = documentClient.readDocument(newDocument.getSelfLink(), options).getResource();Additional samples are provided in the unit tests.
##Need Help?
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.
##Contribute Code or Provide Feedback
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.
##Learn More