Azure Cosmos DB

Documentation

Setting Up the Azure Cosmos DB Java SDK

This guide walks you through the process of setting up the Azure Cosmos DB Java SDK in your development environment.

Prerequisites

Step 1: Install JDK and Build Tool

If you haven't already, download and install the latest version of the JDK from Oracle or use an OpenJDK distribution.

Download and install Maven from Apache Maven or Gradle from Gradle.

Step 2: Create a New Project

You can create a new project using either Maven or Gradle. Below are examples for creating a simple project.

Using Maven

Open your terminal or command prompt and run the following command:

mvn archetype:generate -DgroupId=com.yourcompany.cosmosdb -DartifactId=cosmosdb-java-example -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

This will create a project directory named cosmosdb-java-example.

Using Gradle

Create a new directory for your project and navigate into it. Then, create a build.gradle file with the following content:

plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.azure:azure-cosmos:4.+' // Or specify a version like 4.40.0
}

application {
    mainClass = 'com.yourcompany.cosmosdb.App'
}

You'll also need a settings.gradle file in the same directory:

rootProject.name = 'cosmosdb-java-example'

Step 3: Add the Azure Cosmos DB Java SDK Dependency

To include the SDK in your project, add the following dependency to your build file.

For Maven (pom.xml)

Open your pom.xml file and add the following inside the <dependencies> section:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.40.0</version><!-- Check for the latest stable version -->
</dependency>

For Gradle (build.gradle)

Add the following line to the dependencies block in your build.gradle file:

implementation 'com.azure:azure-cosmos:4.+'

If you are using a specific version, replace 4.+ with the desired version, for example: implementation 'com.azure:azure-cosmos:4.40.0'.

Note: Always check the Maven Central repository for the latest stable version of the azure-cosmos library.

Step 4: Obtain Your Cosmos DB Connection Information

You will need your Azure Cosmos DB account's endpoint and primary key to connect to your database.

  1. 1
    Navigate to your Azure Cosmos DB account in the Azure portal.
  2. 2
    In the left-hand menu, select Keys.
  3. 3
    Copy the URI (this is your endpoint) and the PRIMARY KEY.
Important: Never hardcode your connection string or keys directly in your application code. Use environment variables or a secure configuration management system.

Step 5: Initialize the Cosmos Client

In your Java application, you can now initialize the CosmosClient using your endpoint and key.

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosDatabase;

public class App {

    // Replace with your actual endpoint and key
    private static final String ENDPOINT = System.getenv("AZURE_COSMOS_ENDPOINT");
    private static final String KEY = System.getenv("AZURE_COSMOS_KEY");
    private static final String DATABASE_ID = "MyDatabase"; // Replace with your database ID

    public static void main(String[] args) {
        if (ENDPOINT == null || KEY == null) {
            System.err.println("Please set AZURE_COSMOS_ENDPOINT and AZURE_COSMOS_KEY environment variables.");
            return;
        }

        // Initialize CosmosClient
        CosmosClient client = new CosmosClientBuilder()
            .endpoint(ENDPOINT)
            .key(KEY)
            .buildClient();

        System.out.println("Cosmos DB Client initialized successfully.");

        // Get a reference to the database
        CosmosDatabase database = client.getDatabase(DATABASE_ID);
        System.out.println("Database '" + DATABASE_ID + "' retrieved.");

        // Further operations can be performed here...

        // Close the client when done
        client.close();
        System.out.println("Cosmos DB Client closed.");
    }
}
Tip: For better security practices, consider using Azure Identity libraries for authentication, especially in production environments.

Next Steps