Use the Cloudant Spring Boot Starter to access a Cloudant NoSQL DB service

The Cloudant NoSQL DB has a Spring Boot Starter to allow configuring Cloudant DB using Spring annotations and properties.

Cloudant NoSQL DB is a non-relational, distributed database based on the Apache CouchDB project and the open source BigCouch project.

Learning objectives

This guide will show you how to use the Cloudant Spring Boot Starter to access a Cloudant DB service from a Spring Boot application. This example uses a Cloudant DB on IBM Cloud. You will perform the following steps:

• Create a Spring Boot application using the Spring Initializr
• Create a Cloudant DB service on IBM Cloud
• Add the Cloudant DB service config (credentials and URL) to your application
• Add the Cloudant Spring Boot Starter
• Add a REST endpoint that accesses the Cloudant DB and returns the results
• Build the app and invoke the REST endpoint and display the Cloudant DB results

Prerequisites

• Maven and Java installed on your computer. It is assumed that you can build and run a Maven based Spring Initializr project.
• An IBM Cloud account – sign up for free if you don’t have an account yet

Estimated time

One hour.

Steps

Create a Spring Boot application with the Spring Initializr

On the Spring Initializr page generate a Maven Project with language Java, and the Web dependency. For this example we use group com.example and artifact cloudant-spring. Download the project and unzip it.

Create a Cloudant service using the IBM Cloud Catalog

On the IBM Cloud Data & Analytics Catalog select the Cloudant NoSQL DB service. The Lite version of the service is available to try for free.

Add databases to the Cloudant service

The Cloudant service can contain multiple databases, but initially has none.

To add databases select the Cloudant service on your IBM Cloud Dashboard and click on “Launch” to display the Cloudant Dashboard. On the dashboard select the “Databases” tab on the left and use the “Create Database” button on the top to add two databases.

Add the service URL and credentials to the app

Select the Cloudant service on your IBM Cloud Dashboard and then select “Service credentials” in the left pane. If no credentials are listed, click the “New credential” button to create a set of credentials. Then click on “View credentials” to display the service credentials.

Edit the unzipped Spring Initializr project and add the credentials to the src/main/resources/application.properties file with the following property names:

cloudant.url=<your-cloudant-url>
cloudant.username=<your-cloudant-username>
cloudant.password=<your-cloudant-password>

Note: It is not recommended to store credentials in your application. We do so here only for the sake of simplicity in this tutorial. The Cloudant Spring Boot Starter can utilize other property sources such as environment variables, etc.

Add the Cloudant Spring Boot Starter, and a REST endpoint to access the Cloudant service

For this example we’ll create a simple REST application with an endpoint that queries the Cloudant service and returns a list of the database names created in the previous step.

Edit the unzipped Spring Boot project to make the following changes:

• Add the following dependency in the pom.xml dependencies section:

  <dependency>
    <groupId>com.cloudant</groupId>
    <artifactId>cloudant-spring-boot-starter</artifactId>
    <version>0.0.3</version>
  </dependency>
  

  Show more

• For the REST endpoint add a @RestController annotation to the Spring Boot application class that was created by the Spring Initializr – com/example/cloudantspring/CloudantSpringApplication.java. (Note that the Java package and class names are derived from the Group and Artifact values entered on the Initializr).

• Add an @Autowired annotation for the CloudantClient object. The Cloudant Spring Boot Starter will create the CloudantClient object with the credentials found in application.properties.
• Now add a REST endpoint with the @GetMapping annotation. Use the CloudantClient getAllDbs() method to get the names of all the DB’s in the Cloudant service, and then return a message containing the names.

Your Spring Boot application should now look like the code below (shown here in the Intellij Idea IDE).

Build and run the app, and invoke the Cloudant DB service

Build and run your app with the following command:

mvn package spring-boot:run

Now you can invoke the REST endpoint – http://localhost:8080/cloudant. You should see the message from your REST endpoint listing the DB’s in your Cloudant service:

Summary

The Cloudant Spring Boot Starter makes it easy to configure and use a Cloudant NoSQL DB in a Spring native fashion using Spring auto configuration and Spring Boot properties.