Fork me on GitHub

CosmosDB Async Tutorial

This tutorial demonstrates using CosmosDB to read/write data asynchronously from Azure CosmosDB.

The example used in this tutorial is three end points:

  • POST /posts {"message":"Message to post"} to create a post
  • GET /posts/{id} to obtain a particular post
  • GET /posts to obtain all posts

Tutorial Source

WoOF configuration

The configuration of the end points are as follows:

CosmosDbHttpServer screen shot.

With the implementation as follows:

public class CosmosAsyncDbLogic {

	public Mono<Post> savePost(Post post, CosmosAsyncEntities entities) {
		return entities.getContainer(Post.class).createItem(new Post(UUID.randomUUID().toString(), post.getMessage()))
				.map(response -> response.getItem());

	public Mono<Post> retrievePost(@HttpPathParameter("id") String identifier, CosmosAsyncEntities entities) {
		PartitionKey partitionKey = entities.createPartitionKey(new Post());
		return entities.getContainer(Post.class).readItem(identifier, partitionKey, Post.class)
				.map(response -> response.getItem());

	public void sendPost(@Parameter Post post, ObjectResponse<Post> response) {

	public Flux<Post> retrieveAllPosts(CosmosAsyncEntities entities, ObjectResponse<Post[]> response) {
		PartitionKey partitionKey = entities.createPartitionKey(new Post());
		return entities.getContainer(Post.class).readAllItems(partitionKey, Post.class);

	public void sendPosts(@Parameter Post[] posts, ObjectResponse<Post[]> response) {

The CosmosDB entity is as follows:

@CosmosEntity(containerId = "POST")
@JsonIgnoreProperties(ignoreUnknown = true)
public class Post {

	private String id;

	private String message;

	public String getPartitionKey() {
		return "same";

The Cosmos annotations are optional:

  • @CosmosEntity allows specifying a container name. If not provided, then the class name is used for the container name.
  • @CosmosPartitionKey flags a particular attribute as the partition key. If not provided, the id is used.

Configuring CosmosDB

The following dependency is required:


		<!-- Required for testing -->

CosmosDB is configured in application.objects as follows:

	<supplier source="net.officefloor.nosql.cosmosdb.CosmosAsyncDbSupplierSource">
		<property name="cosmos.entity.locators" value="net.officefloor.tutorial.cosmosasyncdbhttpserver.CosmosAsyncDbEntities" />		

For performance reasons, the entities are not dynamically discovered. As Azure starts instances as required, the application must be brought up quickly to service the first request. Having to inspect all jars and classes for entities is typically too slow. Therefore, CosmosDB requires registering all entities with it manually.

Therefore, to make the entities available to CosmosDB, the following is the above configured class:

public class CosmosAsyncDbEntities implements CosmosEntityLocator {

	public Class<?>[] locateEntities() throws Exception {
		return new Class[] { Post.class };


Note: for third party libraries requiring to store data, it is also possible to register entities via a CosmosEntityLocatorServiceFactory. This allows the entities to be automatically registered when the library is added to the class path.


To make local testing easier, the following unit tests demonstrate automatically setting up a local data store for testing.

	public final CosmosDbExtension cosmosDb = new CosmosDbExtension().waitForCosmosDb();

	public final MockWoofServerExtension server = new MockWoofServerExtension();

	private @Dependency CosmosAsyncEntities entities;

	public void ensureCreatePost() throws Exception {

		// Have server create the post
		Post post = new Post(null, "TEST");
		MockWoofResponse response = this.server.send(MockWoofServer.mockJsonRequest(HttpMethod.POST, "/posts", post));

		// Ensure post created
		PartitionKey partitionKey = this.entities.createPartitionKey(new Post());
		Mono<List<Post>> monoCreated = this.entities.getContainer(Post.class).readAllItems(partitionKey, Post.class)
		List<Post> created = monoCreated.block();
		assertEquals(1, created.size(), "Should only be one created post");
		assertEquals("TEST", created.get(0).getMessage(), "Incorrect post");

Note that this will start @zeit/cosmosdb-server within a docker container to emulate CosmosDB. Unfortunately, the Azure provided emulator only runs on windows.