Couchbase Mobile Changes Explorer – Part. 2

Introduction

The Couchbase Mobile Sync Gateway changes feed provides a way to monitor events in a mobile deployment. The feed makes it feasible to write sophisticated business logic. I wrote a tool to help examine and understand the feed. You can read an introduction and description in part one of this two part series. The code also serves as an example of listening to the feed.

The code

I’ve included the major classes from the app code here. This is the first version, so it can use plenty of enhancements. The parameters are all hard-wired. Check the project here on GitHub for updates.  You can also find instructions for building, running, and packaging the app there.

JavaFX: The Controller class

JavaFX breaks simple apps into a controller class and a declarative UI. Let’s walk through the controller.

This first listing shows a bunch of boiler plate code. I implement several listeners for the UI within the class itself to cut down of files. This is for illustration purposes.

The @FXML annotations mark all the fields that the framework will automatically bind to portions of the UI.

Next comes initialization. JavaFX calls this method as part of its standard lifecycle.

I’ve broken out the document list initialization into its own routine. The document list gets bound to the documentList variable. In turn documentList will update the UI whenever the item list we pass in changes.

I set up a live query to monitor the client database for any changes. This happens through an “all docs” query. An all docs query doesn’t require an associated view. I set INCLUDE_DELETED so the tool can show what a deleted document looks like in the database.

With the other bindings in place, we just have to update the documents list. We’ll see the live query listener that does that further along.

The next few lines set the initial state of a couple of toggle buttons. I need an extra listener to keep the Sync button consistent with the actual state of the replications. More on this further along in the article.

I wrote a separate class to monitor Sync Gateway. The initialization code finished by creating a new monitor instance and kicking it off.

The next section contains several listeners.

Here’s the live query listener that gets called whenever the local database changes. I didn’t design the tool for working with massive databases. So, whenever the data changes, I just took the brute force approach of rereading every document. The getRows method returns an enumerator that will index doing just that. JavaFX takes care of updating the UI when documents changes.

This listener takes care of tracking when a user clicks on an entry in the document list. The entries are the document IDs, so we can use a selection to pull the document directly from the database.

I used a callback approach to get the results of the changes feed. The interface is defined in the SGMonitor class. It has just the one method. In this implementation I simply take the body of the feed response and tack it on to the existing text in the changes feed text pane. There’s a little formatting done to make it easier to read, too.

Finally I added a listener for replication activity. The interface comes from the DBService helper class. I wrote a bit about detecting the state of a replication here. For this app I just need to know whether a replication is running or not to keep the Sync button state consistent. This handles cases where a user tries to start a sync but it fails. This can happen if they need to provide authentication credentials but haven’t, for example.

Next we have several methods bound to UI elements. JavaFX handles much of the wiring.

Here I set the use of authentication credentials whenever the corresponding button gets toggled.

This code shows a couple of interesting items. I use a Jackson ObjectMapper instance to convert the text in the content pane to a property map.

Next I check for an entry _id. Couchbase Mobile reserves most properties starting with an “_” for system use (with special exceptions). If the text we’re trying to convert contains _id, I assume this is an edit to an existing document. Otherwise I create a new document.

So, in a nutshell, we have an example of both creating and updating documents. This isn’t the preferred way to update, although it suffices in many cases. You can read more about updates here.

This reacts to toggling the Sync button. Recall though that we use a listener to verify the state elsewhere.

The rest of the code here are just helper bits and a piece to shutdown everything before exiting.

The Database Helper class

This shows the code for a straight-forward database helper class. For the most part I just find this class a nice packaging of the typical operations needed for managing a database and starting a standard bidirectional set of replications. I’m including it here because I find it useful and for clarity.

I do implement the Replication.ChangeListener interface. That’s maybe a little unusual. I mentioned the reason earlier on. This link takes you to the blog post about it.

The Sync Gateway Monitor class

Finally, let’s take a look at the helper class for monitoring Sync Gateway. I’ll walk through this in pieces, too.

I use the OkHttp library from Square. Currently Couchbase Lite uses this library too, internally. OkHttp uses a builder pattern. I prepare a builder instance I’ll use through the rest of the code in the class constructor. You can read about the meaning of all the parameters in the Sync Gateway documentation.

The start method has the most interesting part of the code. It spins up a background thread. Underneath the thread setup and control code I run a continuous loop. The loop does synchronous network calls. The error handling is simple. Just throw an exception if anything goes wrong.

Sync Gateway responds with JSON strings. You can see the code pulls apart the response and parses the JSON into a JsonNode object. This is all to get at the last_seq value in the response.

In order to track what to send next, the changes feed relies on a simple sequence mechanism. You should treat this as an opaque object. Take the value of last_seq from the previous response, and set the since parameter to that same value for the next request.

There’s no real harm in not supplying the since parameter. Sync Gateway will just replay all changes from the start if it’s missing. That’s why you’ll see in this example, I cheat a little and always create the class instance with since set to the string “0”.

In a real world application, you might want to have some way to save the last sequence string your app has processed, rather than churning through the change history every time.

The rest of the code is just a couple of short methods.

And that’s it for the main classes. There are others needed for the complete app.

Check out the GitHub repo to see all the code and instructions to build it.

Read a discussion of the app and how to use it in part one.

Postscript

You can find more resources on our developer portal and follow us on Twitter @CouchbaseDev.

You can post questions on our forums. And we actively participate on Stack Overflow.

Hit me up on Twitter with any questions, comments, topics you’d like to see, etc. @HodGreeley