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>
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 theCloudantClient
object. The Cloudant Spring Boot Starter will create theCloudantClient
object with the credentials found inapplication.properties
. - Now add a REST endpoint with the
@GetMapping
annotation. Use theCloudantClient 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.