{"id":13174,"date":"2022-05-03T09:49:42","date_gmt":"2022-05-03T16:49:42","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=13174"},"modified":"2023-05-22T08:01:08","modified_gmt":"2023-05-22T15:01:08","slug":"couchbase-kotlin-api-released","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/couchbase-kotlin-api-released\/","title":{"rendered":"Designing the Couchbase Kotlin API\u00a0"},"content":{"rendered":"

I\u2019m pleased to announce the GA release of Couchbase Kotlin SDK version 1.0. In truth, I\u2019m over the moon. This project has been a labor of love. After working with Java for decades, I have a new favorite language.<\/span><\/p>\n

In this article, I\u2019ll say some nice things about Kotlin, and then show how to use the Couchbase Kotlin SDK to connect to the Capella Database-as-a-Service. Finally, I\u2019ll share some design decisions that shaped the SDK\u2019s public API. I hope you\u2019ll stick around for that last part, especially if you\u2019re designing the API of your own Kotlin library.<\/span><\/p>\n

Why Kotlin?<\/span><\/h2>\n

Kotlin changed the way we think about asynchronous programming on the JVM. Kotlin\u2019s coroutines and suspending functions are evidence that reactive programming might be a stepping stone to something better, something that doesn\u2019t require sacrificing readable code at the altar of scalability. Kotlin has shown there\u2019s a better way to write high-performance asynchronous code, and we don\u2019t need to wait for Project Loom\u2019s fibers and continuations.<\/span><\/p>\n

Capella + Kotlin<\/span><\/h2>\n

Couchbase Capella<\/span><\/a> is the Database-as-a-Service (DBaaS) for Couchbase Server. It\u2019s solid tech, and when I signed up for a free trial a few weeks ago, the process was completely painless.<\/span><\/p>\n

Let\u2019s say you have a Capella trial cluster and you\u2019ve added your IP to the Allow List, and you\u2019ve created a database user who can read the pre-installed travel-sample<\/em> bucket. Here\u2019s how to connect to your cluster using the Kotlin SDK:\u00a0<\/span><\/p>\n

 \u00a0\u00a0\u00a0val address = \"--your-cluster--.cloud.couchbase.com\"\r\n\u00a0\u00a0\u00a0\u00a0val cluster = Cluster.connect(\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0connectionString = \"couchbases:\/\/$address\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0username = \"harpo\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0password = \"swordfish\",\r\n\u00a0\u00a0\u00a0\u00a0)<\/pre>\n
Once you have a Cluster object, you can execute a N1QL query:<\/span><\/p>\n
 \u00a0\u00a0\u00a0val queryResult = cluster\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.query(\"SELECT * FROM `travel-sample` LIMIT 3\")\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.execute()\r\n\u00a0\u00a0\u00a0\u00a0queryResult.rows.forEach { println(it) }\r\n\u00a0\u00a0\u00a0\u00a0println(queryResult.metadata)<\/pre>\n
Or get a reference to a Collection and read a specific document:<\/span><\/p>\n
 \u00a0\u00a0\u00a0val collection = cluster\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.bucket(\"travel-sample\")\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0.defaultCollection()\r\n\r\n\u00a0\u00a0\u00a0\u00a0val getResult = collection.get(\"airline_10\")\r\n\u00a0\u00a0\u00a0\u00a0println(getResult)\r\n\u00a0\u00a0\u00a0\u00a0println(getResult.contentAs<Map<String, Any?>>())<\/pre>\n
The complete version of this example is included in the <\/span>Kotlin SDK documentation<\/span><\/a>, along with several others.<\/span><\/p>\n
SDK API design decisions<\/span><\/h2>\n
The rest of this article is devoted to sharing some notes on the decisions we made while designing the public API of the Couchbase Kotlin SDK. In some cases, I\u2019ll be comparing the Kotlin SDK to its older sibling, the Java SDK.<\/span><\/p>\n
Extension vs independent SDK<\/span><\/h3>\n
The Couchbase Kotlin SDK depends on the same core-io<\/em> library as the Java SDK but does not depend on the Java SDK.<\/span><\/p>\n
Rejected alternatives<\/span><\/h4>\n
We considered supporting Kotlin by supplying extension functions for classes from the Java SDK. Unfortunately, some design decisions we made for the Java SDK did not translate well to Kotlin, and could not be compensated for just with extension functions.<\/span><\/p>\n
We also considered providing a full native Kotlin API wrapper that simply delegated to the Java SDK, but we were concerned that having two versions of all the classes (one for Kotlin, one for Java) would be confusing for users.<\/span><\/p>\n
Suspend or bust!<\/span><\/h3>\n
The Kotlin SDK does not provide a blocking API; the methods that do network I\/O are all suspend<\/em> functions.<\/span><\/p>\n
Rejected alternatives<\/span><\/h4>\n
We considered adding “blocking” variants of Cluster, Bucket, Scope, Collection, etc. but this seems like something users can do themselves with very little effort just by wrapping calls to the suspend functions with runBlocking<\/em>.<\/span><\/p>\n
Optional parameters<\/span><\/h3>\n
Since Java does not have optional parameters, the Couchbase Java SDK emulates them with an “options block” constructed using the builder pattern.\u00a0<\/span><\/p>\n
In the following example, withExpiry<\/em>\u00a0is an optional boolean parameter that defaults to false. The code snippets show a call site where the developer wants to pass true instead.<\/span><\/p>\n
Java:<\/span><\/p>\n
 \u00a0\u00a0\u00a0GetOptions options = GetOptions.getOptions().withExpiry(true);\r\n\u00a0\u00a0\u00a0\u00a0collection.get(documentId, options);<\/pre>\n
The Kotlin SDK takes advantage of Kotlin’s native support for default parameters:<\/span><\/p>\n
Kotlin:<\/span><\/p>\n
\u00a0\u00a0\u00a0\u00a0collection.get(documentId, withExpiry = true)<\/pre>\n
Rejected alternatives<\/span><\/h4>\n
We considered using method-specific option blocks for Kotlin as well, which would have looked something like:<\/span><\/p>\n
\u00a0\u00a0\u00a0\u00a0collection.get(documentId, GetOptions(withExpiry = true))<\/pre>\n
This was rejected because it was clunky for users and difficult to maintain for SDK developers (consider the impact of adding a new option common to all methods).<\/span><\/p>\n
We also considered using a lambda\/mini-DSL for options, which would have looked something like:<\/span><\/p>\n
 \u00a0\u00a0\u00a0collection.get(documentId) {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0withExpiry = true\r\n\u00a0\u00a0\u00a0\u00a0}<\/pre>\n
This was the most tempting of the rejected alternatives because it would have been excellent for binary compatibility (method signatures wouldn’t change as new optional parameters are added). It also “feels like Kotlin.” It was rejected because:<\/span><\/p>\n