How to use the Spring Boot Starter with the Azure Cosmos DB SQL API

Overview

Azure Cosmos DB is a globally-distributed database service that allows developers to work with data using a variety of standard APIs, such as SQL, MongoDB, Graph, and Table APIs. Microsoft's Spring Boot Starter enables developers to use Spring Boot applications that easily integrate with Azure Cosmos DB by using the SQL API.

This article demonstrates creating an Azure Cosmos DB using the Azure portal, then using the Spring Initializr to create a custom java application, and then add the Spring Boot Starter functionality to your custom application to store data in and retrieve data from your Azure Cosmos DB by using the SQL API.

Prerequisites

The following prerequisites are required in order to follow the steps in this article:

Create an Azure Cosmos DB by using the Azure portal

  1. Browse to the Azure portal at https://portal.azure.com/ and click +Create a resource.

    Azure portal

  2. Click Databases, and then click Azure Cosmos DB.

    Azure portal

  3. On the Azure Cosmos DB page, enter the following information:

    • Enter a unique ID, which you will use as the URI for your database. For example: wingtiptoysdata.documents.azure.com.
    • Choose SQL for the API.
    • Choose the Subscription you want to use for your database.
    • Specify whether to create a new Resource group for your database, or choose an existing resource group.
    • Specify the Location for your database.

    When you have specified these options, click Create to create your database.

    Azure portal

  4. When your database has been created, it is listed on your Azure Dashboard, as well as under the All Resources and Azure Cosmos DB pages. You can click on your database on any of those locations to open the properties page for your cache.

    Azure portal

  5. When the properties page for your database is displayed, click Access keys and copy your URI and access keys for your database; you will use these values in your Spring Boot application.

    Azure portal

Create a simple Spring Boot application with the Spring Initializr

  1. Browse to https://start.spring.io/.

  2. Specify that you want to generate a Maven project with Java, enter the Group and Artifact names for your application, specify your Spring Boot version, and then click the button to Generate Project.

    Important

    There were several breaking changes to the APIs in Spring Boot version 2.0.n, which will be used to complete the steps in this article. You can still use one of the Spring Boot 1.5.n versions to complete the steps in this tutorial, and the differences will be highlighted when necessary.

    Basic Spring Initializr options

    Note

    The Spring Initializr uses the Group and Artifact names to create the package name; for example: com.example.wintiptoysdata.

  3. When prompted, download the project to a path on your local computer.

    Download custom Spring Boot project

  4. After you have extracted the files on your local system, your simple Spring Boot application will be ready for editing.

    Custom Spring Boot project files

Configure your Spring Boot app to use the Azure Spring Boot Starter

  1. Locate the pom.xml file in the directory of your app; for example:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -or-

    /users/example/home/wingtiptoysdata/pom.xml

    Locate the pom.xml file

  2. Open the pom.xml file in a text editor, and add the following lines to list of <dependencies>:

    <dependency>
       <groupId>com.microsoft.azure</groupId>
       <artifactId>azure-documentdb-spring-boot-starter</artifactId>
       <version>2.0.4</version>
    </dependency>
    

    Editing the pom.xml file

    Important

    If you are using one of Spring Boot 1.5.n versions to complete this tutorial, you will need to specify the older version of the Azure Cosmos DB starter; for example:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-documentdb-spring-boot-starter</artifactId>
      <version>0.1.4</version>
    </dependency>
    
  3. Verify that the Spring Boot version is the version that you chose when you created your application with the Spring Initializr; for example:

    <parent>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-parent</artifactId>
       <version>2.0.1.RELEASE</version>
       <relativePath/>
    </parent>
    

    Note

    If you are using one of Spring Boot 1.5.n versions to complete this tutorial, you will need to verify the correct version; for example: <version>1.5.14.RELEASE</version>.

  4. Save and close the pom.xml file.

Configure your Spring Boot app to use your Azure Cosmos DB

  1. Locate the application.properties file in the resources directory of your app; for example:

    C:\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

    -or-

    /users/example/home/wingtiptoysdata/src/main/resources/application.properties

    Locate the application.properties file

  2. Open the application.properties file in a text editor, and add the following lines to the file, and replace the sample values with the appropriate properties for your database:

    # Specify the DNS URI of your Azure Cosmos DB.
    azure.documentdb.uri=https://wingtiptoys.documents.azure.com:443/
    
    # Specify the access key for your database.
    azure.documentdb.key=57686f6120447564652c20426f6220526f636b73==
    
    # Specify the name of your database.
    azure.documentdb.database=wingtiptoysdata
    

    Editing the application.properties file

  3. Save and close the application.properties file.

Add sample code to implement basic database functionality

In this section you create two Java classes for storing user data, and then you modify your main application class to create an instance of the user class and save it to your database.

Define a basic class for storing user data

  1. Create a new file named User.java in the same directory as your main application Java file.

  2. Open the User.java file in a text editor, and add the following lines to the file to define a generic user class that stores and retrieve values in your database:

    package com.example.wingtiptoysdata;
    
    // Define a generic User class.
    public class User {
       private String id;
       private String firstName;
       private String lastName;
    
       public User() {
       }
    
       public User(String id, String firstName, String lastName) {
          this.id = id;
          this.firstName = firstName;
          this.lastName = lastName;
       }
    
       public String getId() {
          return this.id;
       }
    
       public void setId(String id) {
          this.id = id;
       }
    
       public String getFirstName() {
          return firstName;
       }
    
       public void setFirstName(String firstName) {
          this.firstName = firstName;
       }
    
       public String getLastName() {
          return lastName;
       }
    
       public void setLastName(String lastName) {
          this.lastName = lastName;
       }
    
       @Override
       public String toString() {
          return String.format("User: %s %s %s", id, firstName, lastName);
       }
    }
    
  3. Save and close the User.java file.

Define a data repository interface

  1. Create a new file named UserRepository.java in the same directory as your main application Java file.

  2. Open the UserRepository.java file in a text editor, and add the following lines to the file to define a user repository interface that extends the default DocumentDB repository interface:

    package com.example.wingtiptoysdata;
    
    import com.microsoft.azure.spring.data.documentdb.repository.DocumentDbRepository;
    import org.springframework.stereotype.Repository;
    
    @Repository
    public interface UserRepository extends DocumentDbRepository<User, String> { } 
    
  3. Save and close the UserRepository.java file.

Modify the main application class

  1. Locate the main application Java file in the package directory of your app; for example:

    C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

    -or-

    /users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

    Locate the application Java file

  2. Open the main application Java file in a text editor, and add the following lines to the file:

    package com.example.wingtiptoysdata;
    
    // These imports are required for the application.
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    
    // These imports are only used to create an ID for this example.
    import java.util.Date;
    import java.text.SimpleDateFormat;
    
    @SpringBootApplication
    public class wingtiptoysdataApplication implements CommandLineRunner {
    
       @Autowired
       private UserRepository repository;
    
       public static void main(String[] args) {
          // Execute the command line runner.
          SpringApplication.run(wingtiptoysdataApplication.class, args);
          System.exit(0);
       }
    
       public void run(String... args) throws Exception {
          // Create a simple date/time ID.
          SimpleDateFormat userId = new SimpleDateFormat("yyyyMMddHHmmssSSS");
          Date currentDate = new Date();
    
          // Create a new User class.
          final User testUser = new User(userId.format(currentDate), "Gena", "Soto");
    
          // For this example, remove all of the existing records.
          repository.deleteAll();
    
          // Save the User class to the Azure database.
          repository.save(testUser);
    
          // Retrieve the database record for the User class you just saved by ID.
          // final User result = repository.findOne(testUser.getId());
          final User result = repository.findById(testUser.getId()).get();
    
          // Display the results of the database record retrieval.
          System.out.printf("\n\n%s\n\n",result.toString());
       }
    }
    

    Important

    If you are using one of Spring Boot 1.5.n versions to complete this tutorial, you will need to replace the final User result = repository.findById(testUser.getId()).get(); syntax with final User result = repository.findOne(testUser.getId());.

  3. Save and close the main application Java file.

Build and test your app

  1. Open a command prompt and change directory to the folder where your pom.xml file is located; for example:

    cd C:\SpringBoot\wingtiptoysdata

    -or-

    cd /users/example/home/wingtiptoysdata

  2. Build your Spring Boot application with Maven and run it; for example:

    mvn clean package
    mvn spring-boot:run
    
  3. Your application will display several runtime messages, and it will display a message like the following examples to indicate that values have been successfully stored and retrieved from your database.

    User: 20170724025215132 Gena Soto
    

    Successful output from the application

  4. OPTIONAL: You can use the Azure portal to view the contents of your Azure Cosmos DB from the properties page for your database by clicking Data Explorer, and then selecting and item from the displayed list to view the contents.

    Using the Document Explorer to view your data

Next steps

To learn more about Spring and Azure, continue to the Spring on Azure documentation center.

Additional Resources

For more information about using Azure Cosmos DB and Java, see the following articles:

For more information about using Spring Boot applications on Azure, see the following articles:

For more information about using Azure with Java, see the Azure for Java Developers and the Working with Azure DevOps and Java.

The Spring Framework is an open-source solution that helps Java developers create enterprise-level applications. One of the more-popular projects that is built on top of that platform is Spring Boot, which provides a simplified approach for creating stand-alone Java applications. To help developers get started with Spring Boot, several sample Spring Boot packages are available at https://github.com/spring-guides/. In addition to choosing from the list of basic Spring Boot projects, the Spring Initializr helps developers get started with creating custom Spring Boot applications.