In the previous blog post we discussed how Couchbase can seamlessly integrate into an Event-Driven Architecture. Using the Couchbase Eventing Service, document mutations can be published to a Solace PubSub+ queue from where the data is made available to subscribing microservices in near real-time.

This post focuses on how microservices as Topic subscribers can leverage Couchbase as a scalable & resilient datastore.

Architecture overview & sample application

In this sample application, we subscribe to a Solace PubSub+ Topic, process the data, and update the document in Couchbase.

In our example application, we store hotel details in Couchbase. Updates to the hotel configuration are published to a Solace PubSub+ topic. We build an application that subscribes to the Topic, retrieves the updated data and updates the existing hotel configuration in Couchbase.

We use the travel-sample bucket that contains sample data such as flights, routes and others. In our example, we focus on the hotel documents stored in the inventory scope in the hotel collection. All hotel documents consist of a JSON document with various attributes.

We will update only a small subset of attributes for this tutorial, such as pets_allowed and free_internet.

Event-driven architecture with Solace and Couchbase

The sample application subscribes to a Solace Topic and updates hotel data in Couchbase. Other applications may provide the hotel configuration changes. We use a simple service that publishes updates to the Topic.

Caption: The sample application subscribes to a Solace Topic and updates hotel data in Couchbase. Other applications may provide the hotel configuration changes. We use a simple service that publishes updates to the Topic.


Please review the prerequisites for this sample application:

Couchbase Capella

Create a free Couchbase Capella trial account and follow the instructions to provision your trial cluster. This only takes a few minutes and gives you a fully-fledged Couchbase cluster, including the Data service and the sample dataset, travel-sample, that we will use throughout this blog post.

You can use this tutorial when not using our managed Couchbase Capella offering. The travel-sample bucket is part of the Couchbase server product and can be imported using the Couchbase console.

Solace PubSub+ Event Broker Cloud

Sign up for a free Solace cloud trial and create a Service/VPN. We will use the VPN to connect to a Solace Topic.


Code review – Solace subscriber & publisher

To subscribe to messages from the Solace Topic we use the Solace Java API. This example implementation is derived from examples in the Solace documentation. For implementation details consult the Solace documentation.

We set up the JCSMPProperties with the relevant access information available in the Solace web interface. We then create a JCSMPSession and a Topic.

To subscribe to the messages on the Topic we implement an XMLMessageConsumer:

In the onReceive method, we take the message, convert it to a string and then call the upsertHotelData method of UpdateHotelData class that contains the Couchbase implementation discussed a bit later in this blog post.

We add the topic subscription to the session and start the message consumer.

In order to be able to test the implementation, we also create a message publisher. For this, we first implement an XMLMessageProducer.

With the message producer in place, we can now send messages as seen below. 

Upserting the data to Couchbase

With the logic to subscribe and publish messages in place, let’s now focus on how to update the hotel documents in Couchbase.

For this example, we assume that the message retrieved from the Topic has the JSON format below. Including a hotel_id that we will use as the document id of the hotel documents stored in Couchbase, as well as a number of attributes that we can change:

To establish a secure connection from our application to Couchbase Capella, we need to:

    • Create a database user and grant this user access to the hotel data.
    • Whitelist the IP address of the host running the application
    • Capture the secure connection URL

You can manage all these details in the Capella management plane. Login to Capella in the browser:

  1. Open the Trial – Cluster cluster and navigate to the Connect tab
  2. Scroll down to the Database Access section and click on Manage CredentialsSet database access credentials in Couchbase Capella
  3. Click on Create Database Credentials and provide a database username and password. Configure the Bucket level access to the inventory scope in the travel-sample bucket and grant Read/Write access.
    Set cluster database credentials in Couchbase Capella
  4. Whitelist the application IP address by clicking on Manage Allowed IP and then Add Allowed IP. When running the application from your local machine, simply click Add My IP and your external IP address will be discovered and added automatically.
    Whitelist an IP address in Couchbase Capella
  5. In the Wide Area Network section copy the connection URL.

Code review – connect to Couchbase and update documents

We connect to Couchbase Capella as the first step by creating a cluster object. We provide the endpoint URL captured in the previous step as well as the database user credentials.

Once the bucket object is created we can retrieve the hotel scope and use it later to upsert the document changes. The hotel scope is within the inventory scope of the travel-sample bucket.

Please note, that I use the singleton pattern in order to use the same collection object for all subsequent requests. See the sample implementation for details in my GitHub project.

Let’s now look into how we can update the hotel documents with the data received from the Topic.

The message received is a String so as the first step we need to convert it into a JSON object.

Since the input data from the Topic contains only a subset of all the attributes of the hotel document, we need to consider how to update the document fields most efficiently. 

There are two possible options:

    1. We use the document ID to retrieve the full document from Couchbase, update the attributes and write the document back.
    2. We use the sub-document API in Couchbase to only update dedicated fields within the document instead of replacing the entire document.

Option one is commonly used to update or upsert documents. However, if we work with bigger documents and we only want to update a small portion of it there is no need to send the entire document over the network. In our implementation below, we will use the sub-document API to resolve and update fields in the hotel document.

We use the lookupIn operation to query the document for certain paths. Whereby different components in the path are separated by dots (.). The pets_ok and free_internet attributes are located at the document root in our scenario. We then traverse through the result and display the current values.

The mutateIn operation allows the update of one or more paths in a document. We identify the document in Couchbase by its ID and provide an array of paths and values we want to set.

Last but not least, we run the lookupIn operation to verify that the update was successful.

Next steps

This article taught us to integrate Solace event broker with Couchbase using the Couchbase & Solace Java SDKs.


Posted by Marian Puhl, Solutions Engineer

Marian Puhl is a Solutions Engineer at Couchbase in the Nordic region.

Leave a reply