Tutorial: Build a Java web application using Azure Cosmos DB and the API for NoSQL

Article
08/14/2024

APPLIES TO: NoSQL

Java
Node.js

This Java web application tutorial shows you how to use the Microsoft Azure Cosmos DB service to store and access data from a Java application hosted on Azure App Service Web Apps. Without a credit card or an Azure subscription, you can set up a free Try Azure Cosmos DB account. In this article, you will learn:

How to build a basic JavaServer Pages (JSP) application in Eclipse.
How to work with the Azure Cosmos DB service using the Azure Cosmos DB Java SDK.

This Java application tutorial shows you how to create a web-based task-management application that enables you to create, retrieve, and mark tasks as complete, as shown in the following image. Each of the tasks in the ToDo list is stored as JSON documents in Azure Cosmos DB.

My ToDo List Java application

Tip

This application development tutorial assumes that you have prior experience using Java. If you are new to Java or the prerequisite tools, we recommend downloading the complete todo project from GitHub and building it using the instructions at the end of this article. Once you have it built, you can review the article to gain insight on the code in the context of the project.

Prerequisites for this Java web application tutorial

Before you begin this application development tutorial, you must have the following:

If you don't have an Azure subscription, without a credit card or an Azure subscription, you can set up a free Try Azure Cosmos DB account.

You can try Azure Cosmos DB for free, without an Azure subscription, and with no commitment required. Alternatively, you can create an Azure Cosmos DB free tier account, with the first 1000 RU/s and 25 GB of storage for free. You can also use the Azure Cosmos DB emulator with a URI of https://localhost:8081. For the key to use with the emulator, see Authenticating requests.
Java Development Kit (JDK) 7+.
Eclipse IDE for Java EE Developers.
An Azure Web Site with a Java runtime environment (for example, Tomcat or Jetty) enabled.

If you're installing these tools for the first time, coreservlets.com provides a walk-through of the installation process in the quickstart section of their Tutorial: Installing TomCat7 and Using it with Eclipse article.

Create an Azure Cosmos DB account

Let's start by creating an Azure Cosmos DB account. If you already have an account or if you are using the Azure Cosmos DB Emulator for this tutorial, you can skip to Step 2: Create the Java JSP application.

From the Azure portal menu or the Home page, select Create a resource.
Search for Azure Cosmos DB. Select Create > Azure Cosmos DB.
On the Create an Azure Cosmos DB account page, select the Create option within the Azure Cosmos DB for NoSQL section.

Azure Cosmos DB provides several APIs:
- NoSQL, for document data
- PostgreSQL
- MongoDB, for document data
- Apache Cassandra
- Table
- Apache Gremlin, for graph data
To learn more about the API for NoSQL, see Welcome to Azure Cosmos DB.

In the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos DB account.

Setting	Value	Description
Subscription	Subscription name	Select the Azure subscription that you want to use for this Azure Cosmos DB account.
Resource Group	Resource group name	Select a resource group, or select Create new, then enter a unique name for the new resource group.
Account Name	A unique name	Enter a name to identify your Azure Cosmos DB account. Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name. The name can contain only lowercase letters, numbers, and the hyphen (-) character. It must be 3-44 characters.
Location	The region closest to your users	Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data.
Capacity mode	Provisioned throughput or Serverless	Select Provisioned throughput to create an account in provisioned throughput mode. Select Serverless to create an account in serverless mode.
Apply Azure Cosmos DB free tier discount	Apply or Do not apply	With Azure Cosmos DB free tier, you get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about free tier.
Limit total account throughput	Selected or not	Limit the total amount of throughput that can be provisioned on this account. This limit prevents unexpected charges related to provisioned throughput. You can update or remove this limit after your account is created.

You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt in when creating the account. If you don't see the option to apply the free tier discount, another account in the subscription has already been enabled with free tier.

Note

The following options are not available if you select Serverless as the Capacity mode:

Apply Free Tier Discount
Limit total account throughput

In the Global Distribution tab, configure the following details. You can leave the default values for this quickstart:

Setting	Value	Description
Geo-Redundancy	Disable	Enable or disable global distribution on your account by pairing your region with a pair region. You can add more regions to your account later.
Multi-region Writes	Disable	Multi-region writes capability allows you to take advantage of the provisioned throughput for your databases and containers across the globe.
Availability Zones	Disable	Availability Zones help you further improve availability and resiliency of your application.

Note

The following options are not available if you select Serverless as the Capacity mode in the previous Basics page:

Geo-redundancy
Multi-region Writes

Optionally, you can configure more details in the following tabs:
- Networking. Configure access from a virtual network.
- Backup Policy. Configure either periodic or continuous backup policy.
- Encryption. Use either service-managed key or a customer-managed key.
- Tags. Tags are name/value pairs that enable you to categorize resources and view consolidated billing by applying the same tag to multiple resources and resource groups.
Select Review + create.
Review the account settings, and then select Create. It takes a few minutes to create the account. Wait for the portal page to display Your deployment is complete.
Select Go to resource to go to the Azure Cosmos DB account page.

Go to the Azure Cosmos DB account page, and select Keys. Copy the values to use in the web application you create next.

Screenshot of the Azure portal with the Keys button highlighted on the Azure Cosmos DB account page

Create the Java JSP application

To create the JSP application:

First, we'll start off by creating a Java project. Start Eclipse, then select File, select New, and then select Dynamic Web Project. If you don't see Dynamic Web Project listed as an available project, do the following: Select File, select New, select Project…, expand Web, select Dynamic Web Project, and select Next.
Enter a project name in the Project name box, and in the Target Runtime drop-down menu, optionally select a value (e.g. Apache Tomcat v7.0), and then select Finish. Selecting a target runtime enables you to run your project locally through Eclipse.
In Eclipse, in the Project Explorer view, expand your project. Right-click WebContent, select New, and then select JSP File.
In the New JSP File dialog box, name the file index.jsp. Keep the parent folder as WebContent, as shown in the following illustration, and then select Next.
In the Select JSP Template dialog box, for the purpose of this tutorial select New JSP File (html), and then select Finish.
When the index.jsp file opens in Eclipse, add text to display Hello World! within the existing <body> element. The updated <body> content should look like the following code:
```
<body>
  <% out.println("Hello World!"); %>
</body>
```
Save the index.jsp file.
If you set a target runtime in step 2, you can select Project and then Run to run your JSP application locally:

Install the SQL Java SDK

The easiest way to pull in the SQL Java SDK and its dependencies is through Apache Maven. To do this, you need to convert your project to a Maven project by using the following steps:

Right-click your project in the Project Explorer, select Configure, select Convert to Maven Project.
In the Create new POM window, accept the defaults, and select Finish.
In Project Explorer, open the pom.xml file.
On the Dependencies tab, in the Dependencies pane, select Add.
In the Select Dependency window, do the following:
- In the Group Id box, enter com.azure.
- In the Artifact Id box, enter azure-cosmos.
- In the Version box, enter 4.11.0.
Or, you can add the dependency XML for Group ID and Artifact ID directly to the pom.xml file:
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos</artifactId>
  <version>4.11.0</version>
</dependency>
```
Select OK and Maven will install the SQL Java SDK or save the pom.xml file.

Use the Azure Cosmos DB service in your Java application

Now let's add the models, the views, and the controllers to your web application.

Add a model

First, let's define a model within a new file TodoItem.java. The TodoItem class defines the schema of an item along with the getter and setter methods:

package com.microsoft.azure.cosmos.sample.model;

//@Data
//@Builder
public class TodoItem {
    private String entityType;
    private String category;
    private boolean complete;
    private String id;
    private String name;

    public String getCategory() {
        return category;
    }

    public void setCategory(String category) {
        this.category = category;
    }

    public String getEntityType() {
        return entityType;
    }

    public void setEntityType(String entityType) {
        this.entityType = entityType;
    }

    public boolean isComplete() {
        return complete;
    }

    public void setComplete(boolean complete) {
        this.complete = complete;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
    
    
}

Add the Data Access Object(DAO) classes

Create a Data Access Object (DAO) to abstract persisting the ToDo items to Azure Cosmos DB. In order to save ToDo items to a collection, the client needs to know which database and collection to persist to (as referenced by self-links). In general, it is best to cache the database and collection when possible to avoid additional round-trips to the database.

To invoke the Azure Cosmos DB service, you must instantiate a new cosmosClient object. In general, it is best to reuse the cosmosClient object rather than constructing a new client for each subsequent request. You can reuse the client by defining it within the cosmosClientFactory class. Update the HOST and MASTER_KEY values that you saved in step 1. Replace the HOST variable with your URI and replace the MASTER_KEY with your PRIMARY KEY. Use the following code to create the CosmosClientFactory class within the CosmosClientFactory.java file:

package com.microsoft.azure.cosmos.sample.dao;

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

public class CosmosClientFactory {
    private static final String HOST = "[ACCOUNT HOST NAME]";
    private static final String MASTER_KEY = "[ACCOUNT KEY]";

    private static CosmosClient cosmosClient = new CosmosClientBuilder()
            .endpoint(HOST)
            .key(MASTER_KEY)
            .consistencyLevel(ConsistencyLevel.EVENTUAL)
            .buildClient();

    public static CosmosClient getCosmosClient() {
        return cosmosClient;
    }

}

Create a new TodoDao.java file and add the TodoDao class to create, update, read, and delete the todo items:

package com.microsoft.azure.cosmos.sample.dao;

import java.util.List;

import com.microsoft.azure.cosmos.sample.model.TodoItem;

public interface TodoDao {
    /**
     * @return A list of TodoItems
     */
    public List<TodoItem> readTodoItems();

    /**
     * @param todoItem
     * @return whether the todoItem was persisted.
     */
    public TodoItem createTodoItem(TodoItem todoItem);

    /**
     * @param id
     * @return the TodoItem
     */
    public TodoItem readTodoItem(String id);

    /**
     * @param id
     * @return the TodoItem
     */
    public TodoItem updateTodoItem(String id, boolean isComplete);

    /**
     *
     * @param id
     * @return whether the delete was successful.
     */
    public boolean deleteTodoItem(String id);
}

Create a new MockDao.java file and add the MockDao class, this class implements the TodoDao class to perform CRUD operations on the items:

package com.microsoft.azure.cosmos.sample.dao;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import lombok.NonNull;

import com.microsoft.azure.cosmos.sample.model.TodoItem;

public class MockDao implements TodoDao {
    private final Map<String, TodoItem> todoItemMap;

    public MockDao() {
        todoItemMap = new HashMap<String, TodoItem>();
    }

    @Override
    public TodoItem createTodoItem(@NonNull TodoItem todoItem) {
        if (todoItem.getId() == null || todoItem.getId().isEmpty()) {
            todoItem.setId(generateId());
        }
        todoItemMap.put(todoItem.getId(), todoItem);
        return todoItem;
    }

    @Override
    public TodoItem readTodoItem(@NonNull String id) {
        return todoItemMap.get(id);
    }

    @Override
    public List<TodoItem> readTodoItems() {
        return new ArrayList<TodoItem>(todoItemMap.values());
    }

    @Override
    public TodoItem updateTodoItem(String id, boolean isComplete) {
        todoItemMap.get(id).setComplete(isComplete);
        return todoItemMap.get(id);
    }

    @Override
    public boolean deleteTodoItem(@NonNull String id) {
        todoItemMap.remove(id);
        return true;
    }

    private String generateId() {
        return new Integer(todoItemMap.size()).toString();
    }
}

Create a new DocDbDao.java file and add the DocDbDao class. This class defines code to persist the TodoItems into the container, retrieves your database and collection, if it exists, or create a new one if it doesn't exist. This example uses Gson to serialize and de-serialize the TodoItem Plain Old Java Objects (POJOs) to JSON documents. In order to save ToDo items to a collection, the client needs to know which database and collection to persist to (as referenced by self-links). This class also defines helper function to retrieve the documents by another attribute (e.g. "ID") rather than self-link. You can use the helper method to retrieve a TodoItem JSON document by ID and then deserialize it to a POJO.

You can also use the cosmosClient client object to get a collection or list of TodoItems using a SQL query. Finally, you define the delete method to delete a TodoItem from your list. The following code shows the contents of the DocDbDao class:

package com.microsoft.azure.cosmos.sample.dao;

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.CosmosDatabase;
import com.azure.cosmos.CosmosException;
import com.azure.cosmos.implementation.Utils;
import com.azure.cosmos.models.CosmosContainerProperties;
import com.azure.cosmos.models.CosmosContainerResponse;
import com.azure.cosmos.models.CosmosDatabaseResponse;
import com.azure.cosmos.models.CosmosItemRequestOptions;
import com.azure.cosmos.models.CosmosQueryRequestOptions;
import com.azure.cosmos.models.FeedResponse;
import com.azure.cosmos.models.PartitionKey;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.google.gson.Gson;
import com.microsoft.azure.cosmos.sample.model.TodoItem;

import java.util.ArrayList;
import java.util.List;

public class DocDbDao implements TodoDao {
    // The name of our database.
    private static final String DATABASE_ID = "TestDB";

    // The name of our collection.
    private static final String CONTAINER_ID = "TestCollection";

    // We'll use Gson for POJO <=> JSON serialization for this example.
    private static Gson gson = new Gson();

    // The Cosmos DB Client
    private static CosmosClient cosmosClient = CosmosClientFactory
        .getCosmosClient();

    // The Cosmos DB database
    private static CosmosDatabase cosmosDatabase = null;

    // The Cosmos DB container
    private static CosmosContainer cosmosContainer = null;

    // For POJO/JsonNode interconversion
    private static final ObjectMapper OBJECT_MAPPER = Utils.getSimpleObjectMapper();

    @Override
    public TodoItem createTodoItem(TodoItem todoItem) {
        // Serialize the TodoItem as a JSON Document.

        JsonNode todoItemJson = OBJECT_MAPPER.valueToTree(todoItem);

        ((ObjectNode) todoItemJson).put("entityType", "todoItem");

        try {
            // Persist the document using the DocumentClient.
            todoItemJson =
                getContainerCreateResourcesIfNotExist()
                    .createItem(todoItemJson)
                    .getItem();
        } catch (CosmosException e) {
            System.out.println("Error creating TODO item.\n");
            e.printStackTrace();
            return null;
        }


        try {

            return OBJECT_MAPPER.treeToValue(todoItemJson, TodoItem.class);
            //return todoItem;
        } catch (Exception e) {
            System.out.println("Error deserializing created TODO item.\n");
            e.printStackTrace();

            return null;
        }

    }

    @Override
    public TodoItem readTodoItem(String id) {
        // Retrieve the document by id using our helper method.
        JsonNode todoItemJson = getDocumentById(id);

        if (todoItemJson != null) {
            // De-serialize the document in to a TodoItem.
            try {
                return OBJECT_MAPPER.treeToValue(todoItemJson, TodoItem.class);
            } catch (JsonProcessingException e) {
                System.out.println("Error deserializing read TODO item.\n");
                e.printStackTrace();

                return null;
            }
        } else {
            return null;
        }
    }

    @Override
    public List<TodoItem> readTodoItems() {

        List<TodoItem> todoItems = new ArrayList<TodoItem>();

        String sql = "SELECT * FROM root r WHERE r.entityType = 'todoItem'";
        int maxItemCount = 1000;
        int maxDegreeOfParallelism = 1000;
        int maxBufferedItemCount = 100;

        CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
        options.setMaxBufferedItemCount(maxBufferedItemCount);
        options.setMaxDegreeOfParallelism(maxDegreeOfParallelism);
        options.setQueryMetricsEnabled(false);

        int error_count = 0;
        int error_limit = 10;

        String continuationToken = null;
        do {

            for (FeedResponse<JsonNode> pageResponse :
                getContainerCreateResourcesIfNotExist()
                    .queryItems(sql, options, JsonNode.class)
                    .iterableByPage(continuationToken, maxItemCount)) {

                continuationToken = pageResponse.getContinuationToken();

                for (JsonNode item : pageResponse.getElements()) {

                    try {
                        todoItems.add(OBJECT_MAPPER.treeToValue(item, TodoItem.class));
                    } catch (JsonProcessingException e) {
                        if (error_count < error_limit) {
                            error_count++;
                            if (error_count >= error_limit) {
                                System.out.println("\n...reached max error count.\n");
                            } else {
                                System.out.println("Error deserializing TODO item JsonNode. " +
                                    "This item will not be returned.");
                                e.printStackTrace();
                            }
                        }
                    }

                }
            }

        } while (continuationToken != null);

        return todoItems;
    }

    @Override
    public TodoItem updateTodoItem(String id, boolean isComplete) {
        // Retrieve the document from the database
        JsonNode todoItemJson = getDocumentById(id);

        // You can update the document as a JSON document directly.
        // For more complex operations - you could de-serialize the document in
        // to a POJO, update the POJO, and then re-serialize the POJO back in to
        // a document.
        ((ObjectNode) todoItemJson).put("complete", isComplete);

        try {
            // Persist/replace the updated document.
            todoItemJson =
                getContainerCreateResourcesIfNotExist()
                    .replaceItem(todoItemJson, id, new PartitionKey(id), new CosmosItemRequestOptions())
                    .getItem();
        } catch (CosmosException e) {
            System.out.println("Error updating TODO item.\n");
            e.printStackTrace();
            return null;
        }

        // De-serialize the document in to a TodoItem.
        try {
            return OBJECT_MAPPER.treeToValue(todoItemJson, TodoItem.class);
        } catch (JsonProcessingException e) {
            System.out.println("Error deserializing updated item.\n");
            e.printStackTrace();

            return null;
        }
    }

    @Override
    public boolean deleteTodoItem(String id) {
        // CosmosDB refers to documents by self link rather than id.

        // Query for the document to retrieve the self link.
        JsonNode todoItemJson = getDocumentById(id);

        try {
            // Delete the document by self link.
            getContainerCreateResourcesIfNotExist()
                .deleteItem(id, new PartitionKey(id), new CosmosItemRequestOptions());
        } catch (CosmosException e) {
            System.out.println("Error deleting TODO item.\n");
            e.printStackTrace();
            return false;
        }

        return true;
    }

    /*
    
    private CosmosDatabase getTodoDatabase() {
        if (databaseCache == null) {
            // Get the database if it exists
            List<CosmosDatabase> databaseList = cosmosClient
                    .queryDatabases(
                            "SELECT * FROM root r WHERE r.id='" + DATABASE_ID
                                    + "'", null).getQueryIterable().toList();

            if (databaseList.size() > 0) {
                // Cache the database object so we won't have to query for it
                // later to retrieve the selfLink.
                databaseCache = databaseList.get(0);
            } else {
                // Create the database if it doesn't exist.
                try {
                    CosmosDatabase databaseDefinition = new CosmosDatabase();
                    databaseDefinition.setId(DATABASE_ID);

                    databaseCache = cosmosClient.createDatabase(
                            databaseDefinition, null).getResource();
                } catch (CosmosException e) {
                    // TODO: Something has gone terribly wrong - the app wasn't
                    // able to query or create the collection.
                    // Verify your connection, endpoint, and key.
                    e.printStackTrace();
                }
            }
        }

        return databaseCache;
    }

    */

    private CosmosContainer getContainerCreateResourcesIfNotExist() {

        try {

            if (cosmosDatabase == null) {
                CosmosDatabaseResponse cosmosDatabaseResponse = cosmosClient.createDatabaseIfNotExists(DATABASE_ID);
                cosmosDatabase = cosmosClient.getDatabase(cosmosDatabaseResponse.getProperties().getId());
            }

        } catch (CosmosException e) {
            // TODO: Something has gone terribly wrong - the app wasn't
            // able to query or create the collection.
            // Verify your connection, endpoint, and key.
            System.out.println("Something has gone terribly wrong - " +
                "the app wasn't able to create the Database.\n");
            e.printStackTrace();
        }

        try {

            if (cosmosContainer == null) {
                CosmosContainerProperties properties = new CosmosContainerProperties(CONTAINER_ID, "/id");
                CosmosContainerResponse cosmosContainerResponse = cosmosDatabase.createContainerIfNotExists(properties);
                cosmosContainer = cosmosDatabase.getContainer(cosmosContainerResponse.getProperties().getId());
            }

        } catch (CosmosException e) {
            // TODO: Something has gone terribly wrong - the app wasn't
            // able to query or create the collection.
            // Verify your connection, endpoint, and key.
            System.out.println("Something has gone terribly wrong - " +
                "the app wasn't able to create the Container.\n");
            e.printStackTrace();
        }

        return cosmosContainer;
    }

    private JsonNode getDocumentById(String id) {

        String sql = "SELECT * FROM root r WHERE r.id='" + id + "'";
        int maxItemCount = 1000;
        int maxDegreeOfParallelism = 1000;
        int maxBufferedItemCount = 100;

        CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
        options.setMaxBufferedItemCount(maxBufferedItemCount);
        options.setMaxDegreeOfParallelism(maxDegreeOfParallelism);
        options.setQueryMetricsEnabled(false);

        List<JsonNode> itemList = new ArrayList();

        String continuationToken = null;
        do {
            for (FeedResponse<JsonNode> pageResponse :
                getContainerCreateResourcesIfNotExist()
                    .queryItems(sql, options, JsonNode.class)
                    .iterableByPage(continuationToken, maxItemCount)) {

                continuationToken = pageResponse.getContinuationToken();

                for (JsonNode item : pageResponse.getElements()) {
                    itemList.add(item);
                }
            }

        } while (continuationToken != null);

        if (itemList.size() > 0) {
            return itemList.get(0);
        } else {
            return null;
        }
    }

}

Next, create a new TodoDaoFactory.java file and add the TodoDaoFactory class that creates a new DocDbDao object:

package com.microsoft.azure.cosmos.sample.dao;

public class TodoDaoFactory {
    private static TodoDao myTodoDao = new DocDbDao();

    public static TodoDao getDao() {
        return myTodoDao;
    }
}

Add a controller

Add the TodoItemController controller to your application. In this project, you are using Project Lombok to generate the constructor, getters, setters, and a builder. Alternatively, you can write this code manually or have the IDE generate it:

package com.microsoft.azure.cosmos.sample.controller;

import java.util.List;
import java.util.UUID;

import lombok.NonNull;

import com.microsoft.azure.cosmos.sample.dao.TodoDao;
import com.microsoft.azure.cosmos.sample.dao.TodoDaoFactory;
import com.microsoft.azure.cosmos.sample.model.TodoItem;

public class TodoItemController {
    public static TodoItemController getInstance() {
        if (todoItemController == null) {
            todoItemController = new TodoItemController(TodoDaoFactory.getDao());
        }
        return todoItemController;
    }

    private static TodoItemController todoItemController;

    private final TodoDao todoDao;

    TodoItemController(TodoDao todoDao) {
        this.todoDao = todoDao;
    }

    public TodoItem createTodoItem(@NonNull String name,
            @NonNull String category, boolean isComplete) {
        TodoItem todoItem = new TodoItem();
        
        todoItem.setName(name);
        todoItem.setCategory(category);
        todoItem.setComplete(isComplete);
        todoItem.setId(UUID.randomUUID().toString());

        return todoDao.createTodoItem(todoItem);
    }

    public boolean deleteTodoItem(@NonNull String id) {
        return todoDao.deleteTodoItem(id);
    }

    public TodoItem getTodoItemById(@NonNull String id) {
        return todoDao.readTodoItem(id);
    }

    public List<TodoItem> getTodoItems() {
        return todoDao.readTodoItems();
    }

    public TodoItem updateTodoItem(@NonNull String id, boolean isComplete) {
        return todoDao.updateTodoItem(id, isComplete);
    }
}

Create a servlet

Next, create a servlet to route HTTP requests to the controller. Create the ApiServlet.java file and define the following code under it:

package com.microsoft.azure.cosmos.sample;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.google.gson.Gson;
import com.microsoft.azure.cosmos.sample.controller.TodoItemController;

/**
 * API Frontend Servlet
 */
@WebServlet("/api")
public class ApiServlet extends HttpServlet {
    // API Keys
    public static final String API_METHOD = "method";

    // API Methods
    public static final String CREATE_TODO_ITEM = "createTodoItem";
    public static final String GET_TODO_ITEMS = "getTodoItems";
    public static final String UPDATE_TODO_ITEM = "updateTodoItem";

    // API Parameters
    public static final String TODO_ITEM_ID = "todoItemId";
    public static final String TODO_ITEM_NAME = "todoItemName";
    public static final String TODO_ITEM_CATEGORY = "todoItemCategory";
    public static final String TODO_ITEM_COMPLETE = "todoItemComplete";

    public static final String MESSAGE_ERROR_INVALID_METHOD = "{'error': 'Invalid method'}";

    private static final long serialVersionUID = 1L;
    private static final Gson gson = new Gson();

    @Override
    protected void doGet(HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {

        String apiResponse = MESSAGE_ERROR_INVALID_METHOD;

        TodoItemController todoItemController = TodoItemController
                .getInstance();

        String id = request.getParameter(TODO_ITEM_ID);
        String name = request.getParameter(TODO_ITEM_NAME);
        String category = request.getParameter(TODO_ITEM_CATEGORY);
        String itemComplete = request.getParameter(TODO_ITEM_COMPLETE);
        boolean isComplete = itemComplete!= null && itemComplete.equalsIgnoreCase("true");

        switch (request.getParameter(API_METHOD)) {
        case CREATE_TODO_ITEM:
            apiResponse = gson.toJson(todoItemController.createTodoItem(name,
                    category, isComplete));
            break;
        case GET_TODO_ITEMS:
            apiResponse = gson.toJson(todoItemController.getTodoItems());
            break;
        case UPDATE_TODO_ITEM:
            apiResponse = gson.toJson(todoItemController.updateTodoItem(id,
                    isComplete));
            break;
        default:
            break;
        }

        response.setCharacterEncoding("UTF-8");
        response.getWriter().println(apiResponse);
    }

    @Override
    protected void doPost(HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {
        doGet(request, response);
    }
}

Wire the rest of the Java app together

Now that we've finished the fun bits, all that's left is to build a quick user interface and wire it up to your DAO.

You need a web user interface to display to the user. Let's re-write the index.jsp we created earlier with the following code:

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge;" />
  <title>Azure Cosmos Java Sample</title>

  <!-- Bootstrap -->
  <link href="//ajax.aspnetcdn.com/ajax/bootstrap/3.2.0/css/bootstrap.min.css" rel="stylesheet">

  <style>
    /* Add padding to body for fixed nav bar */
    body {
      padding-top: 50px;
    }
  </style>
</head>
<body>
  <!-- Nav Bar -->
  <div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
    <div class="container">
      <div class="navbar-header">
        <a class="navbar-brand" href="#">My Tasks</a>
      </div>
    </div>
  </div>

  <!-- Body -->
  <div class="container">
    <h1>My ToDo List</h1>

    <hr/>

    <!-- The ToDo List -->
    <div class = "todoList">
      <table class="table table-bordered table-striped" id="todoItems">
        <thead>
          <tr>
            <th>Name</th>
            <th>Category</th>
            <th>Complete</th>
          </tr>
        </thead>
        <tbody>
        </tbody>
      </table>

      <!-- Update Button -->
      <div class="todoUpdatePanel">
        <form class="form-horizontal" role="form">
          <button type="button" class="btn btn-primary">Update Tasks</button>
        </form>
      </div>

    </div>

    <hr/>

    <!-- Item Input Form -->
    <div class="todoForm">
      <form class="form-horizontal" role="form">
        <div class="form-group">
          <label for="inputItemName" class="col-sm-2">Task Name</label>
          <div class="col-sm-10">
            <input type="text" class="form-control" id="inputItemName" placeholder="Enter name">
          </div>
        </div>

        <div class="form-group">
          <label for="inputItemCategory" class="col-sm-2">Task Category</label>
          <div class="col-sm-10">
            <input type="text" class="form-control" id="inputItemCategory" placeholder="Enter category">
          </div>
        </div>

        <button type="button" class="btn btn-primary">Add Task</button>
      </form>
    </div>

  </div>

  <!-- Placed at the end of the document so the pages load faster -->
  <script src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-2.1.1.min.js"></script>
  <script src="//ajax.aspnetcdn.com/ajax/bootstrap/3.2.0/bootstrap.min.js"></script>
  <script src="assets/todo.js"></script>
</body>
</html>

Finally, write some client-side JavaScript to tie the web user interface and the servlet together:

/**
 * ToDo App
 */

var todoApp = {
  /*
   * API methods to call Java backend.
   */
  apiEndpoint: "api",

  createTodoItem: function(name, category, isComplete) {
    $.post(todoApp.apiEndpoint, {
        "method": "createTodoItem",
        "todoItemName": name,
        "todoItemCategory": category,
        "todoItemComplete": isComplete
      },
      function(data) {
        var todoItem = data;
        todoApp.addTodoItemToTable(todoItem.id, todoItem.name, todoItem.category, todoItem.complete);
      },
      "json");
  },

  getTodoItems: function() {
    $.post(todoApp.apiEndpoint, {
        "method": "getTodoItems"
      },
      function(data) {
        var todoItemArr = data;
        $.each(todoItemArr, function(index, value) {
          todoApp.addTodoItemToTable(value.id, value.name, value.category, value.complete);
        });
      },
      "json");
  },

  updateTodoItem: function(id, isComplete) {
    $.post(todoApp.apiEndpoint, {
        "method": "updateTodoItem",
        "todoItemId": id,
        "todoItemComplete": isComplete
      },
      function(data) {},
      "json");
  },

  /*
   * UI Methods
   */
  addTodoItemToTable: function(id, name, category, isComplete) {
    var rowColor = isComplete ? "active" : "warning";

    todoApp.ui_table().append($("<tr>")
      .append($("<td>").text(name))
      .append($("<td>").text(category))
      .append($("<td>")
        .append($("<input>")
          .attr("type", "checkbox")
          .attr("id", id)
          .attr("checked", isComplete)
          .attr("class", "isComplete")
        ))
      .addClass(rowColor)
    );
  },

  /*
   * UI Bindings
   */
  bindCreateButton: function() {
    todoApp.ui_createButton().click(function() {
      todoApp.createTodoItem(todoApp.ui_createNameInput().val(), todoApp.ui_createCategoryInput().val(), false);
      todoApp.ui_createNameInput().val("");
      todoApp.ui_createCategoryInput().val("");
    });
  },

  bindUpdateButton: function() {
    todoApp.ui_updateButton().click(function() {
      // Disable button temporarily.
      var myButton = $(this);
      var originalText = myButton.text();
      $(this).text("Updating...");
      $(this).prop("disabled", true);

      // Call api to update todo items.
      $.each(todoApp.ui_updateId(), function(index, value) {
        todoApp.updateTodoItem(value.name, value.value);
        $(value).remove();
      });

      // Re-enable button.
      setTimeout(function() {
        myButton.prop("disabled", false);
        myButton.text(originalText);
      }, 500);
    });
  },

  bindUpdateCheckboxes: function() {
    todoApp.ui_table().on("click", ".isComplete", function(event) {
      var checkboxElement = $(event.currentTarget);
      var rowElement = $(event.currentTarget).parents('tr');
      var id = checkboxElement.attr('id');
      var isComplete = checkboxElement.is(':checked');

      // Togle table row color
      if (isComplete) {
        rowElement.addClass("active");
        rowElement.removeClass("warning");
      } else {
        rowElement.removeClass("active");
        rowElement.addClass("warning");
      }

      // Update hidden inputs for update panel.
      todoApp.ui_updateForm().children("input[name='" + id + "']").remove();

      todoApp.ui_updateForm().append($("<input>")
        .attr("type", "hidden")
        .attr("class", "updateComplete")
        .attr("name", id)
        .attr("value", isComplete));

    });
  },

  /*
   * UI Elements
   */
  ui_createNameInput: function() {
    return $(".todoForm #inputItemName");
  },

  ui_createCategoryInput: function() {
    return $(".todoForm #inputItemCategory");
  },

  ui_createButton: function() {
    return $(".todoForm button");
  },

  ui_table: function() {
    return $(".todoList table tbody");
  },

  ui_updateButton: function() {
    return $(".todoUpdatePanel button");
  },

  ui_updateForm: function() {
    return $(".todoUpdatePanel form");
  },

  ui_updateId: function() {
    return $(".todoUpdatePanel .updateComplete");
  },

  /*
   * Install the TodoApp
   */
  install: function() {
    todoApp.bindCreateButton();
    todoApp.bindUpdateButton();
    todoApp.bindUpdateCheckboxes();

    todoApp.getTodoItems();
  }
};

$(document).ready(function() {
  todoApp.install();
});

Now all that's left is to test the application. Run the application locally, and add some Todo items by filling in the item name and category and clicking Add Task. After the item appears, you can update whether it's complete by toggling the checkbox and clicking Update Tasks.

Deploy your Java application to Azure Web Sites

Azure Web Sites makes deploying Java applications as simple as exporting your application as a WAR file and either uploading it via source control (e.g. Git) or FTP.

To export your application as a WAR file, right-click on your project in Project Explorer, select Export, and then select WAR File.
In the WAR Export window, do the following:
- In the Web project box, enter azure-cosmos-java-sample.
- In the Destination box, choose a destination to save the WAR file.
- Select Finish.
Now that you have a WAR file in hand, you can simply upload it to your Azure Web Site's webapps directory. For instructions on uploading the file, see Add a Java application to Azure App Service Web Apps. After the WAR file is uploaded to the webapps directory, the runtime environment will detect that you've added it and will automatically load it.
To view your finished product, navigate to http://YOUR\_SITE\_NAME.azurewebsites.net/azure-cosmos-java-sample/ and start adding your tasks!

Get the project from GitHub

All the samples in this tutorial are included in the todo project on GitHub. To import the todo project into Eclipse, ensure you have the software and resources listed in the Prerequisites section, then do the following:

Install Project Lombok. Lombok is used to generate constructors, getters, setters in the project. Once you have downloaded the lombok.jar file, double-click it to install it or install it from the command line.
If Eclipse is open, close it and restart it to load Lombok.
In Eclipse, on the File menu, select Import.
In the Import window, select Git, select Projects from Git, and then select Next.
On the Select Repository Source screen, select Clone URI.
On the Source Git Repository screen, in the URI box, enter https://github.com/Azure-Samples/azure-cosmos-java-sql-api-todo-app, and then select Next.
On the Branch Selection screen, ensure that main is selected, and then select Next.
On the Local Destination screen, select Browse to select a folder where the repository can be copied, and then select Next.
On the Select a wizard to use for importing projects screen, ensure that Import existing projects is selected, and then select Next.
On the Import Projects screen, unselect the DocumentDB project, and then select Finish. The DocumentDB project contains the Azure Cosmos DB Java SDK, which we will add as a dependency instead.
In Project Explorer, navigate to azure-cosmos-java-sample\src\com.microsoft.azure.cosmos.sample.dao\DocumentClientFactory.java and replace the HOST and MASTER_KEY values with the URI and PRIMARY KEY for your Azure Cosmos DB account, and then save the file. For more information, see Step 1. Create an Azure Cosmos DB database account.
In Project Explorer, right-click the azure-cosmos-java-sample, select Build Path, and then select Configure Build Path.
On the Java Build Path screen, in the right pane, select the Libraries tab, and then select Add External JARs. Navigate to the location of the lombok.jar file, and select Open, and then select OK.
Use step 12 to open the Properties window again, and then in the left pane select Targeted Runtimes.
On the Targeted Runtimes screen, select New, select Apache Tomcat v7.0, and then select OK.
Use step 12 to open the Properties window again, and then in the left pane select Project Facets.
On the Project Facets screen, select Dynamic Web Module and Java, and then select OK.
On the Servers tab at the bottom of the screen, right-click Tomcat v7.0 Server at localhost and then select Add and Remove.
On the Add and Remove window, move azure-cosmos-java-sample to the Configured box, and then select Finish.
In the Servers tab, right-click Tomcat v7.0 Server at localhost, and then select Restart.
In a browser, navigate to http://localhost:8080/azure-cosmos-java-sample/ and start adding to your task list. Note that if you changed your default port values, change 8080 to the value you selected.
To deploy your project to an Azure web site, see Step 6. Deploy your application to Azure Web Sites.

Next steps

Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.

If all you know is the number of vCores and servers in your existing database cluster, read about estimating request units using vCores or vCPUs
If you know typical request rates for your current database workload, read about estimating request units using Azure Cosmos DB capacity planner

Build a Node.js application with Azure Cosmos DB

Share via