DEV Community: Mohit Sharma

Getting Started With the MongoDB Kotlin Driver

Mohit Sharma — Tue, 27 Jun 2023 11:14:47 +0000

This is an introductory article on how to build an application in Kotlin using MongoDB Atlas and the MongoDB Kotlin driver, the latest addition to our list of official drivers. Together, we'll build a CRUD application that covers the basics of how to use MongoDB as a database, while leveraging the benefits of Kotlin as a programming language, like data classes, coroutines, and flow.

Prerequisites

This is a getting-started article. Therefore, not much is needed as a prerequisite, but familiarity with Kotlin as a programming language will be helpful.

Also, we need an Atlas account, which is free forever. Create an account if you haven't got one. This provides MongoDB as a cloud database and much more. Later in this tutorial, we'll use this account to create a new cluster, load a dataset, and eventually query against it.

In general, MongoDB is an open-source, cross-platform, and distributed document database that allows building apps with flexible schema. In case you are not familiar with it or would like a quick recap, I recommend exploring
the MongoDB Jumpstart series to get familiar with MongoDB and its various services in under 10 minutes. Or if you prefer to read, then you can follow our guide.

And last, to aid our development activities, we will be using Jetbrains IntelliJ IDEA (Community Edition), which has default support for the Kotlin language.

MongoDB Kotlin driver vs MongoDB Realm Kotlin SDK

Before we start, I would like to touch base on Realm Kotlin SDK, one of the SDKs used to create client-side mobile applications using the MongoDB ecosystem. It shouldn't be confused with the MongoDB Kotlin driver for server-side programming. The MongoDB Kotlin driver, a language driver, enables you to seamlessly interact with Atlas, a cloud database, with the benefits of the Kotlin language paradigm. It's appropriate to create backend apps, scripts, etc.

To make learning more meaningful and practical, we'll be building a CRUD application. Feel free to check out our Github repo if you would like to follow along together. So, without further ado, let's get started.

Create a project

To create the project, we can use the project wizard, which can be found under the File menu options. Then, select New, followed by Project. This will open the New Project screen, as shown below, then update the project and language to Kotlin.

After the initial Gradle sync, our project is ready to run. So, let's give it a try using the run icon in the menu bar, or simply press CTRL + R on Mac. Currently, our project won't do much apart from printing Hello World! and arguments supplied, but the BUILD SUCCESSFUL message in the run
console is what we're looking for, which tells us that our project setup is complete.

Now, the next step is to add the Kotlin driver to our project, which allows us to interact with MongoDB Atlas.

Adding the MongoDB Kotlin driver

Adding the driver to the project is simple and straightforward. Just update the dependencies block with the Kotlin driver dependency in the build file —i.e.,build.gradle.

dependencies {
    // Kotlin coroutine dependency
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4'

    // MongoDB Kotlin driver dependency
    implementation 'org.mongodb:mongodb-driver-kotlin-coroutine:4.10.0-SNAPSHOT'
}

And now, we are ready to connect with MongoDB Atlas using the Kotlin driver.

Connecting to the database

To connect with the database, we first need the Connection URI that can be found by pressing connect to cluster in our Atlas account, as shown below.

For more details, you can also refer to our documentation.

With the connection URI available, the next step is to create a Kotlin file. Setup.kt is where we write the code for connecting to MongoDB Atlas.

Connection with our database can be split into two steps. First, we create a MongoClient instance using Connection URI.

val connectionString = "mongodb+srv://<username>:<enter your password>@cluster0.sq3aiau.mongodb.net/?retryWrites=true&w=majority"
val client = MongoClient.create(connectionString = connectString)

And second, use client to connect with the database, sample_restaurants, which is a sample dataset for
restaurants. A sample dataset is a great way to explore the platform and build a more realistic POC to validate your ideas. To learn how to seed your first Atlas database with sample data, visit the docs.

val databaseName = "sample_restaurants"
val db: MongoDatabase = client.getDatabase(databaseName = databaseName)

Hardcoding connectionString isn't a good approach and can lead to security risks or an inability to provide role-based access. To avoid such issues and follow the best practices, we will be using environment variables. Other common approaches are the use of Vault, build configuration variables, and CI/CD environment variables.

To add environment variables, use Modify run configuration, which can be found by right-clicking on the file.

Together with code to access the environment variable, our final code looks like this.

suspend fun setupConnection(
    databaseName: String = "sample_restaurants",
    connectionEnvVariable: String = "MONGODB_URI"
): MongoDatabase? {
    val connectString = if (System.getenv(connectionEnvVariable) != null) {
        System.getenv(connectionEnvVariable)
    } else {
        "mongodb+srv://<usename>:<password>@cluster0.sq3aiau.mongodb.net/?retryWrites=true&w=majority"
    }

    val client = MongoClient.create(connectionString = connectString)
    val database = client.getDatabase(databaseName = databaseName)

    return try {
        // Send a ping to confirm a successful connection
        val command = Document("ping", BsonInt64(1))
        database.runCommand(command)
        println("Pinged your deployment. You successfully connected to MongoDB!")
        database
    } catch (me: MongoException) {
        System.err.println(me)
        null
    }
}

In the code snippet above, we still have the ability to use a hardcoded string. This is only done for demo purposes, allowing you to use a connection URI directly for ease and to run this via any online editor. But it is strongly recommended to avoid hardcoding a connection URI.

With the setupConnection function ready, let's test it and query the database for the collection count and name.

suspend fun listAllCollection(database: MongoDatabase) {

    val count = database.listCollectionNames().count()
    println("Collection count $count")

    print("Collection in this database are -----------> ")
    database.listCollectionNames().collect { print(" $it") }
}

Upon running that code, our output looks like this:

By now, you may have noticed that we are using the suspend keyword with listAllCollection(). listCollectionNames() is an asynchronous function as it interacts with the database and therefore would ideally run on a different thread. And since the MongoDB Kotlin driver supports Coroutines, the native Kotlin asynchronous language paradigm, we can benefit from it by using suspend functions.

Similarly, to drop collections, we use the suspend function.

suspend fun dropCollection(database: MongoDatabase) {
    database.getCollection<Objects>(collectionName = "restaurants").drop()
}

With this complete, we are all set to start working on our CRUD application. So to start with, we need to create a data class that represents restaurant information that our app saves into the database.

data class Restaurant(
    @BsonId
    val id: ObjectId,
    val address: Address,
    val borough: String,
    val cuisine: String,
    val grades: List<Grade>,
    val name: String,
    @BsonProperty("restaurant_id")
    val restaurantId: String
)

data class Address(
    val building: String,
    val street: String,
    val zipcode: String,
    val coord: List<Double>
)

data class Grade(
    val date: LocalDateTime,
    val grade: String,
    val score: Int
)

In the above code snippet, we used two annotations:

@BsonId, which represents the unique identity or _id of a document.
@BsonProperty, which creates an alias for keys in the document — for example, restaurantId represents restaurant_id.

Note: Our Restaurant data class here is an exact replica of a restaurant document in the sample dataset, but a few fields can be skipped or marked as optional — e.g., grades and address — while maintaining the ability to perform CRUD operations. We are able to do so, as MongoDB’s document model allows flexible schema for our data.

Create

With all the heavy lifting done (10 lines of code for connecting), adding a new document to the database is really simple and can be done with one line of code using insertOne. So, let's create a new file called Create.kt, which will contain all the create operations.

suspend fun addItem(database: MongoDatabase) {

    val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
    val item = Restaurant(
        id = ObjectId(),
        address = Address(
            building = "Building", street = "street", zipcode = "zipcode", coord =
            listOf(Random.nextDouble(), Random.nextDouble())
        ),
        borough = "borough",
        cuisine = "cuisine",
        grades = listOf(
            Grade(
                date = LocalDateTime.now(),
                grade = "A",
                score = Random.nextInt()
            )
        ),
        name = "name",
        restaurantId = "restaurantId"
    )

    collection.insertOne(item).also {
        println("Item added with id - ${it.insertedId}")
    }
}

When we run it, the output on the console is:

Again, don't forget to add an environment variable again for this file, if you had trouble while running it.

If we want to add multiple documents to the collection, we can use insertMany, which is recommended over running insertOne in a loop.

suspend fun addItems(database: MongoDatabase) {
    val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
    val newRestaurants = collection.find<Restaurant>().first().run {
        listOf(
            this.copy(
                id = ObjectId(), name = "Insert Many Restaurant first", restaurantId = Random
                    .nextInt().toString()
            ),
            this.copy(
                id = ObjectId(), name = "Insert Many Restaurant second", restaurantId = Random
                    .nextInt().toString()
            )
        )
    }

    collection.insertMany(newRestaurants).also {
        println("Total items added ${it.insertedIds.size}")
    }
}

With these outputs on the console, we can say that the data has been added successfully.

But what if we want to see the object in the database? One way is with a read operation, which we would do shortly or use MongoDB Compass to view the information.

MongoDB Compass is a free, interactive GUI tool for querying, optimizing, and analyzing the MongoDB data from your system. To get started, download the tool and use the connectionString to connect with the
database.

Read

To read the information from the database, we can use the find operator. Let's begin by reading any document.

val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
collection.find<Restaurant>().limit(1).collect {
    println(it)
}

The find operator returns a list of results, but since we are only interested in a single document, we can use the limit operator in conjunction to limit our result set. In this case, it would be a single document.

If we extend this further and want to read a specific document, we can add filter parameters over the top of it:

val queryParams = Filters
    .and(
        listOf(
            eq("cuisine", "American"),
            eq("borough", "Queens")
        )
    )

Or, we can use any of the operators from our list. The final code looks like this.

suspend fun readSpecificDocument(database: MongoDatabase) {
    val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
    val queryParams = Filters
        .and(
            listOf(
                eq("cuisine", "American"),
                eq("borough", "Queens")
            )
        )


    collection
        .find<Restaurant>(queryParams)
        .limit(2)
        .collect {
            println(it)
        }

}

For the output, we see this:

Don't forget to add the environment variable again for this file, if you had trouble while running it.

Another practical use case that comes with a read operation is how to add pagination to the results. This can be done with the limit and offset
operators.

suspend fun readWithPaging(database: MongoDatabase, offset: Int, pageSize: Int) {
    val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
    val queryParams = Filters
        .and(
            listOf(
                eq(Restaurant::cuisine.name, "American"),
                eq(Restaurant::borough.name, "Queens")
            )
        )

    collection
        .find<Restaurant>(queryParams)
        .limit(pageSize)
        .skip(offset)
        .collect {
            println(it)
        }
}

But with this approach, often, the query response time increases with value of the offset. To overcome this, we can benefit by creating an Index, as shown below.

val collection = database.getCollection<Restaurant>(collectionName = "restaurants")
val options = IndexOptions().apply {
    this.name("restaurant_id_index")
    this.background(true)
}

collection.createIndex(
    keys = Indexes.ascending("restaurant_id"),
    options = options
)

Update

Now, let's discuss how to edit/update an existing document. Again, let's quickly create a new Kotlin file, Update.Kt.

In general, there are two ways of updating any document:

Perform an update operation, which allows us to update specific fields of the matching documents without impacting the other fields.
Perform a replace operation to replace the matching document with the new document.

For this exercise, we'll use the document we created earlier with the create operation {restaurant_id: "restaurantId"} and update the restaurant_id with a more realistic value. Let's split this into two sub-tasks for clarity.

First, using Filters, we query to filter the document, similar to the read operation earlier.

val collection = db.getCollection<Restaurant>("restaurants")
val queryParam = Filters.eq("restaurant_id", "restaurantId")

Then, we can set the restaurant_id with a random integer value using Updates.

val updateParams = Updates.set("restaurant_id", Random.nextInt().toString())

And finally, we use updateOne to update the document in an atomic operation.

collection.updateOne(filter = queryParam, update = updateParams).also {
    println("Total docs modified ${it.matchedCount} and fields modified ${it.modifiedCount}")
}

In the above example, we were already aware of which document we wanted to update — the restaurant with an id restauratantId — but there could be a few use cases where that might not be the situation. In such cases, we would first look up the document and then update it. findOneAndUpdate can be handy. It allows you to combine both of these processes into an atomic operation, unlocking additional performance.

Another variation of the same could be updating multiple documents with one call. updateMany is useful for such use cases — for example, if we want to update the cuisine of all restaurants to your favourite type of cuisine and borough to Brooklyn.

suspend fun updateMultipleDocuments(db: MongoDatabase) {
    val collection = db.getCollection<Restaurant>("restaurants")
    val queryParam = Filters.eq(Restaurant::cuisine.name, "Chinese")
    val updateParams = Updates.combine(
        Updates.set(Restaurant::cuisine.name, "Indian"),
        Updates.set(Restaurant::borough.name, "Brooklyn")
    )

    collection.updateMany(filter = queryParam, update = updateParams).also {
        println("Total docs matched ${it.matchedCount} and modified ${it.modifiedCount}")
    }
}

In these examples, we used set and combine with Updates. But there are many more types of update operator to explore that allow us to do many intuitive operations, like set the currentDate or timestamp, increase or decrease the value of the field, and so on. To learn more about the different
types of update operators you can perform with Kotlin and MongoDB, refer to our docs.

Delete

Now, let's explore one final CRUD operation: delete. We'll start by exploring how to delete a single document. To do this, we'll use findOneAndDelete instead of deleteOne. As an added benefit, this also returns the deleted document as output. In our example, we delete the
restaurant:

val collection = db.getCollection<Restaurant>(collectionName = "restaurants")
val queryParams = Filters.eq("restaurant_id", "restaurantId")

collection.findOneAndDelete(filter = queryParams).also {
    it?.let {
        println(it)
    }
}

To delete multiple documents, we can use deleteMany. We can, for example, use this to delete all the data we created earlier with our create operation.

suspend fun deleteRestaurants(db: MongoDatabase) {
    val collection = db.getCollection<Restaurant>(collectionName = "restaurants")

    val queryParams = Filters.or(
        listOf(
            Filters.regex(Restaurant::name.name, Pattern.compile("^Insert")),
            Filters.regex("restaurant_id", Pattern.compile("^restaurant"))
        )
    )
    collection.deleteMany(filter = queryParams).also {
        println("Document deleted : ${it.deletedCount}")
    }
}

Summary

Congratulations! You now know how to set up your first Kotlin application with MongoDB and perform CRUD operations. The complete source code of the app can be found on GitHub.

If you have any feedback on your experience working with the MongoDB Kotlin driver, please submit a comment in our user feedback portal or reach out to me on Twitter: @codeWithMohit.

How to use Azure functions with MongoDB Atlas in Java

Mohit Sharma — Fri, 14 Apr 2023 12:26:33 +0000

Cloud computing is one of the most discussed topics in the tech industry. Its ability to scale up and down infrastructure instantly, serverless
apps are just a few benefits to start with. In this article, we are going write the function as a service(FaaS)e i.e. serverless function that
would interact with data via a database to produce meaningful results. FaaS can be also very useful in A/B testing where you want to
release quickly an independent function without going into actual implementation or release.

In this article we will learn how to use MongoDB atlas, a cloud database,
when you are getting started with Azure functions
in Java.

Prerequisites

Microsoft Azure account that we will be using for running and deploying our serverless function, if you don't have one you can sign up for free.
MongoDB Atlas account which is a cloud based document database, and you can sign up for an account for free.
IntelliJ IDEA Community Edition to aid our development activities for this tutorial. If this is not your preferred IDE then you can use other IDEs like Eclipse, Visual Studio, etc., but the steps will be slightly different.
An Azure supported Java Development Kit (JDK) for Java, version 8 or 11.
Basic understanding of Java programming language.

Serverless function: Hello World!

Getting started with the Azure serverless function is very simple, thanks to the Azure IntelliJ plugin which offers various features from generating
boilerplate code to the deployment of the Azure function. So before we jump into actual code let's install the plugin.

Installing the Azure plugin

Azure plugin can be installed on IntelliJ in a very standard manner using the IntelliJ plugin
manager. So open Plugins and then search for "Azure Toolkit for IntelliJ" in the Marketplace
and click Install.

With this, we are ready to create our first Azure function.

First Azure function

Now let's create a project that would contain our function and have the necessary
dependencies to execute it. Go ahead and select File > New > Project from the menu bar and select Azure
functions from Generators as shown below and hit next.

Now we can edit the project details if needed, or you can leave them to default.

In the last step, update name of the project and location.

With this complete, we have a bootstrapped project with a sample function implementation. So without
further ado let's run this and see it in action.

Deploying & running

We can deploy the Azure function either locally or on the cloud, let's start by deploying it locally. To deploy and run locally press the play icon
against the function name, on line 20 as shown in the above screenshot, and select run from the dialogue.

Now go ahead and copy the URL shown in the console log and open it in the browser to run the azure function.

This would prompt passing the name as a query parameter as defined in the bootstrapped function.

if (name == null) {
    return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
        .body("Please pass a name on the query string or in the request body").build();
} else {
    return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
}

So update the URL by appending the query parameter name to
http://localhost:XXXXX/api/HttpExample?name=World which would print the desired result.

To learn more in detail you can also follow this official
guide.

Connecting serverless function with MongoDB Atlas

In the previous step, we created our first Azure function which takes user input and returns a result but real-world
applications are far more complicated than this. In order to create a real-world function, which we would do in the next section, we need to
understand how to connect our function with a database, as logic operates over data and databases hold the data.

Similar to serverless function, let's use a database which is also on the cloud and has the ability to scale up and down with the needs. Therefore,
we would be using MongoDB Atlas which is a document-based cloud database.

Setting up Atlas account

Creating an Atlas account is very straightforward, free forever and perfect to validate
any MVP project idea, but if you need a guide you can follow this documentation.

Adding Azure function IP address in Atlas Network Config

Azure function uses multiple IP addresses instead of single address, so let's add these to Atlas. To get the range of IP address open your
Azure account and search networking inside your Azure Virtual machine and copy the Outbound addresses from
Outbound traffic.

One of the steps while creating an account with Atlas is to add the IP address for accepting incoming
connection requests. This is essential to prevent unwanted access to our database. In our case, Atlas would get all the connection requests from the
Azure function so let's add this addresses.

And add these to IP individually under Network Access.

Installing dependency to interact with Atlas

There are various ways of interacting with Atlas, since we are building a service using a serverless function in Java my preference would be to use
MongoDB Java driver. So let's add the dependency for the driver in the build.gradle file.

dependencies {
    implementation 'com.microsoft.azure.functions:azure-functions-java-library:3.0.0'
    // dependency for MongoDB Java driver
    implementation 'org.mongodb:mongodb-driver-sync:4.9.0'
}

With this, our project is ready to connect and interact with our cloud database.

Building an Azure function with Atlas

With all prerequisites done, let us build our first real-world function using the MongoDB sample
datasetfor movies. In this project, we would be building two functions one returns the count of the
total movies in the collection and the other would return the movie document based on the year of release.

So let's generate the boilerplate code for the function by right-clicking on the package name
and then selecting New > Azure function class, we would be calling this function class as Movies.

public class Movies {
    /**
     * This function listens at endpoint "/api/Movie". Two ways to invoke it using "curl" command in bash:
     * 1. curl -d "HTTP Body" {your host}/api/Movie
     * 2. curl {your host}/api/Movie?name=HTTP%20Query
     */
    @FunctionName("Movies")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");

        // Parse query parameter
        String query = request.getQueryParameters().get("name");
        String name = request.getBody().orElse(query);

        if (name == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST).body("Please pass a name on the query string or in the request body").build();
        } else {
            return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
        }
    }
}

Now let us update the

@FunctionName parameter from Movies to getMoviesCount.
Rename the function name from run to getMoviesCount.
Remove the query & name variables as we don't have any query parameters.

So our update code looks like this.

public class Movies {

    @FunctionName("getMoviesCount")
    public HttpResponseMessage getMoviesCount(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");

        return request.createResponseBuilder(HttpStatus.OK).body("Hello").build();
    }
}

Now to connect with MongoDB Atlas using Java driver we first need a connection string that can be found when we press to connect to our cluster on our
Atlas account, for details you can also refer
to this documentation.

Using the connection string we can create an instance of MongoClients that can be used to open connection
from the database.

public class Movies {

    private static final String MONGODB_CONNECTION_URI = "mongodb+srv://xxxxx@cluster0.xxxx.mongodb.net/?retryWrites=true&w=majority";
    private static final String DATABASE_NAME = "sample_mflix";
    private static final String COLLECTION_NAME = "movies";
    private static MongoDatabase database = null;

    private static MongoDatabase createDatabaseConnection() {
        if (database == null) {
            try {
                MongoClient client = MongoClients.create(MONGODB_CONNECTION_URI);
                database = client.getDatabase(DATABASE_NAME);
            } catch (Exception e) {
                throw new IllegalStateException("Error in creating MongoDB client");
            }
        }
        return database;
    }

    /*@FunctionName("getMoviesCount")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");

        return request.createResponseBuilder(HttpStatus.OK).body("Hello").build();
    }*/
}

We can query our database for the total number of movies in the collection as shown below.

long totalRecords=database.getCollection(COLLECTION_NAME).countDocuments();

And updated code for getMoviesCount the function looks like this.

@FunctionName("getMoviesCount")
public HttpResponseMessage getMoviesCount(
      @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS
      ) HttpRequestMessage<Optional<String>> request,
      final ExecutionContext context) {

  if (database != null) {
      long totalRecords = database.getCollection(COLLECTION_NAME).countDocuments();
      return request.createResponseBuilder(HttpStatus.OK).body("Total Records, " + totalRecords + " - At:" + System.currentTimeMillis()).build();
  } else {
      return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR).build();
  }
}

Now let's deploy this code locally and on the cloud to validate the output and would be using
Postman.

Now copy the URL from the console output and paste it on the postman to validate the output.

Now let's deploy this on Azure cloud on a Linux machine. So click on Azure Explore and select Functions App to
create a Virtual machine (VM).

Now right-click on the Azure function and select create.

Now change the platform to Linux with Java 1.8

If for some reason you don't want to change the platform and would like use Window OS, then add standard DNS route before making a network request.
System.setProperty("java.naming.provider.url", "dns://8.8.8.8"); 

After a few minutes, you would notice the VM we just created under Function App, now we can deploy
our app onto it.

And press run to deploy it.

Once deployment is successful you find the URL of the serverless function.

Again we would copy this URL and validate using postman.

With this we have successfully connected our first function with
MongoDB Atlas. Now lets take to next level, we would
create another function that returns a movie document based on the year of release.

so let's add the boilerplate code again

@FunctionName("getMoviesByYear")
public HttpResponseMessage getMoviesByYear(
      @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS
      ) HttpRequestMessage<Optional<String>> request,
      final ExecutionContext context) {

}

Now to capture user input year that would be used to query and gather information from the collection.

final int yearRequestParam = valueOf(request.getQueryParameters().get("year"));

To use this information for querying, we create a Filters object that can passed as input for find function.

Bson filter = Filters.eq("year", yearRequestParam);
Document result = collection.find(filter).first();

And the updated code is

@FunctionName("getMoviesByYear")
public HttpResponseMessage getMoviesByYear(
      @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS
      ) HttpRequestMessage<Optional<String>> request,
      final ExecutionContext context) {

  final int yearRequestParam = valueOf(request.getQueryParameters().get("year"));
  MongoCollection<Document> collection = database.getCollection(COLLECTION_NAME);

  if (database != null) {
      Bson filter = Filters.eq("year", yearRequestParam);
      Document result = collection.find(filter).first();
      return request.createResponseBuilder(HttpStatus.OK).body(result.toJson()).build();
  } else {
      return request.createResponseBuilder(HttpStatus.BAD_REQUEST).body("Year missing").build();
  }
}

Now lets validate this against postman.

Last step in making our app production ready is to secure the connection URI, as it contain credentials and should be kept private. One of ways
of securing it could be storing this into environment variable.

Adding environment variable in Azure function can be done via Azure portal and Azure IntelliJ plugin as well. For now, we would be using Azure
IntelliJ Plugin, so go ahead and open Azure Explore in IntelliJ.

And then we select Function App and after right click select Show Properties.

This would open a tab with all existing properties, we add our property into it.

Now we can update our function code to use this variable.

From

private static final String MONGODB_CONNECTION_URI = "mongodb+srv://xxxxx:xxxx@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority";

private static final String MONGODB_CONNECTION_URI = System.getenv("MongoDB_Connection_URL");

After redeploying the code, we are all set to use this app in production.

Summary

Thank you for reading, hopefully you find this article informative! The complete source code of the app can be found on GitHub.

If you're looking for something similar using the Node.js runtime, check out this other tutorial on the subject.

With MongoDB Atlas on Microsoft Azure , developers receive access to the most comprehensive, secure, scalable, and cloud–based developer data platform in the market. Now, with the availability of Atlas on the Azure Marketplace, it’s never been easier for users to start building with Atlas while
streamlining procurement and billing processes. Get started today through the Atlas on Azure Marketplace listing.

If you have any queries or comments, you can share them on the MongoDB forum or tweet me @codeWithMohit.

Getting Started with Backend Development in Kotlin Using Spring Boot 3 & MongoDB

Mohit Sharma — Wed, 15 Feb 2023 11:46:03 +0000

This is an introduction article on how to build a RESTful application in Kotlin using Spring Boot 3 and MongoDB Atlas.

Introduction

Today, we are going to build a basic RESTful application that does a little more than a CRUD operation, and for that, we will use:

Spring Boot 3, which is one of the popular frameworks based on Spring, allowing developers to build production grades quickly.
MongoDB, which is a document oriented database, allowing developers to focus on building apps rather than on database schema.

Prerequisites

This is a getting-started article, so nothing much is needed as a prerequisite. But familiarity with Kotlin as a programming language, plus a basic understanding of Rest API and HTTP methods, would be helpful.

To help with development activities, we will be using Jetbrains IntelliJ IDEA (Community Edition).

HelloWorld app!

Building a HelloWorld app in any programming language/technology, I believe, is the quickest and easiest way to get familiar with it. This helps you cover the basic concepts, like how to build, run, debug, deploy, etc.

Since we are using the community version of IDEA, we cannot create the HelloWorld project directly from IDE itself using the New Project. But we can use the Spring initializer app instead, which allows us to create a Spring
project out of the box.

Once you are on the website, you can update the default selected parameters for the project, like the name of the project, language, version of Spring Boot, etc., to something similar as shown below.

And since we want to create REST API with MongoDB as a database, let's add the dependency using the Add Dependency button on the right.

After all the updates, our project settings will look like this.

Now we can download the project folder using the generate button and open it using the IDE. If we scan the project folder, we will only find one class — i.e., HelloBackendWorldApplication.kt, which has the main function, as well.

The next step is to print HelloWorld on the screen. Since we are building a restful
application, we will create a GET request API. So, let's add a function to act as a GET API call.

@GetMapping("/hello")
fun hello(@RequestParam(value = "name", defaultValue = "World") name: String?): String {
    return String.format("Hello %s!", name)
}

We also need to add an annotation of @RestController to our class to make it a Restful client.

@SpringBootApplication
@RestController
class HelloBackendWorldApplication {
    @GetMapping("/hello")
    fun hello(): String {
        return "Hello World!"
    }
}

fun main(args: Array<String>) {
    runApplication<HelloBackendWorldApplication>(*args)
}

Now, let's run our project using the run icon from the toolbar.

Now load https://localhost:8080/hello on the browser once the build is complete, and that will print Hello World on your screen.

And on cross-validating this from Postman, we can clearly understand that our Get API is working perfectly.

It's time to understand the basics of Spring Boot that made it so easy to create our first API call.

What is Spring Boot ?

As per official docs, Spring Boot makes it easy to create stand-alone, production-grade, Spring-based applications that you can "just run."

This implies that it's a tool built on top of the Spring framework, allowing us to build web applications quickly.

Spring Boot uses annotations, which do the heavy lifting in the background. A few of them, we have used already, like:

@SpringBootApplication: This annotation is marked at class level, and declares to the code reader (developer) and Spring that it's a Spring Boot project. It allows an enabling feature, which can also be done using @EnableAutoConfiguration,@ComponentScan, and @Configuration.
@RequestMapping and @RestController: This annotation provides the routing information. Routing is nothing but a mapping of a HTTP request path (text after host/) to classes that have the implementation of these across various HTTP methods.

These annotations are sufficient for building a basic application. Using Spring Boot, we will create a RESTful web service with all business logic, but we don't have a data container that can store or provide data to run these operations.

Introduction to MongoDB

For our app, we will be using MongoDB as the database. MongoDB is an open-source, cross-platform, and distributed document database, which allows building apps with flexible schema. This is great as we can focus on building the app rather than defining the schema.

We can get started with MongoDB really quickly using MongoDB Atlas, which is a database as a service in the cloud and has a free forever tier.

I recommend that you explore the MongoDB Jumpstart series to get familiar with MongoDB and its various services in under 10 minutes.

Connecting with the Spring Boot app and MongoDB

With the basics of MongoDB covered, now let's connect our Spring Boot project to it. Connecting with MongoDB is really simple, thanks to the Spring Data MongoDB plugin.

To connect with MongoDB Atlas, we just need a database URL that can be added
as a spring.data.mongodb.uri property in application.properties file. The connection string can be found as shown below.

The format for the connection string is:

spring.data.mongodb.uri = mongodb + srv ://<username>:<pwd>@<cluster>.mongodb.net/<dbname>

Creating a CRUD RESTful app

With all the basics covered, now let's build a more complex application than HelloWorld! In this app, we will be covering all CRUD operations and tweaking them along the way to make it a more realistic app. So, let's create a new project similar to the HelloWorld app we created earlier. And for this app, we will use one of the sample datasets provided by MongoDB — one of my favourite features that enables quick learning.

You can load a sample dataset on Atlas as shown below:

We will be using the sample_restaurants collection for our CRUD application. Before we start with the actual CRUD operation, let's create the restaurant model class equivalent to it in the collection.


@Document("restaurants")
data class Restaurant(
    @Id
    val id: ObjectId = ObjectId(),
    val address: Address = Address(),
    val borough: String = "",
    val cuisine: String = "",
    val grades: List<Grade> = emptyList(),
    val name: String = "",
    @Field("restaurant_id")
    val restaurantId: String = ""
)

data class Address(
    val building: String = "",
    val street: String = "",
    val zipcode: String = "",
    @Field("coord")
    val coordinate: List<Double> = emptyList()
)

data class Grade(
    val date: Date = Date(),
    @Field("grade")
    val rating: String = "",
    val score: Int = 0
)

You will notice there is nothing fancy about this class except for the annotation. These annotations help us to connect or co-relate classes with databases like:

@Document: This declares that this data class represents a document in Atlas.
@Field: This is used to define an alias name for a property in the document, like coord for coordinate in Address model.

Now let's create a repository class where we can define all methods through which we can access data. Spring Boot has interface MongoRepository, which helps us with this.

interface Repo : MongoRepository<Restaurant, String> {

    fun findByRestaurantId(id: String): Restaurant?
}

After that, we create a controller through which we can call these queries. Since this is a bigger project, unlike the HelloWorld app, we will create a separate controller where the MongoRepository instance is passed using @Autowired, which provides annotations-driven dependency injection.

@RestController
@RequestMapping("/restaurants")
class Controller(@Autowired val repo: Repo) {

}

Read operation

Now our project is ready to do some action, so let's count the number of restaurants in the collection using GetMapping.

@RestController
@RequestMapping("/restaurants")
class Controller(@Autowired val repo: Repo) {

    @GetMapping
    fun getCount(): Int {
        return repo.findAll().count()
    }
}

Taking a step further to read the restaurant-based restaurantId. We will have to add a method in our repo as restaurantId is not marked @Id in the restaurant class.

interface Repo : MongoRepository<Restaurant, String> {
    fun findByRestaurantId(restaurantId: String): Restaurant?
}

@GetMapping("/{id}")
fun getRestaurantById(@PathVariable("id") id: String): Restaurant? {
    return repo.findByRestaurantId(id)
}

And again, we will be using Postman to validate the output against a random restaurantId from the sample dataset.

Let's also validate this against a non-existing restaurantId.

As expected, we haven't gotten any results, but the API response code is still 200, which is incorrect! So, let's fix this.

In order to have the correct response code, we will have to check the result before sending it back with the correct response code.

    @GetMapping("/{id}")
fun getRestaurantById(@PathVariable("id") id: String): ResponseEntity<Restaurant> {
    val restaurant = repo.findByRestaurantId(id)
    return if (restaurant != null) ResponseEntity.ok(restaurant) else ResponseEntity
        .notFound().build()
}

Write operation

To add a new object to the collection, we can add a write function in the repo we created earlier, or we can use the inbuilt method insert provided by MongoRepository. Since we will be adding a new object to the collection, we'll be using @PostMapping for this.

    @PostMapping
fun postRestaurant(): Restaurant {
    val restaurant = Restaurant().copy(name = "sample", restaurantId = "33332")
    return repo.insert(restaurant)
}

Update operation

Spring doesn't have any specific in-built update similar to other CRUD operations, so we will be using the read and write operation in combination to perform the update function.

    @PatchMapping("/{id}")
fun updateRestaurant(@PathVariable("id") id: String): Restaurant? {
    return repo.findByRestaurantId(restaurantId = id)?.let {
        repo.save(it.copy(name = "Update"))
    }
}

This is not an ideal way of updating items in the collection as it requires two operations and can be improved further if we use the MongoDB native driver, which allows us to perform complicated operations with the minimum number of steps.

Delete operation

Deleting a restaurant is also similar. We can use the MongoRepository delete function of the item from the collection, which takes the item as input.

@DeleteMapping("/{id}")
fun deleteRestaurant(@PathVariable("id") id: String) {
    repo.findByRestaurantId(id)?.let {
        repo.delete(it)
    }
}

Summary

Thank you for reading and hopefully you find this article informative! The complete source code of the app can be found on GitHub.

If you have any queries or comments, you can share them on the MongoDB forum or tweet me @codeWithMohit.

Getting Started Guide for Kotlin Multiplatform Mobile (KMM) with Flexible Sync

Mohit Sharma — Thu, 26 Jan 2023 09:24:22 +0000

This is an introductory article on how to build your first Kotlin Multiplatform Mobile using Atlas Device Sync.

Introduction

Mobile development has evolved a lot in recent years and in this tutorial, we are going discuss Kotlin Multiplatform Mobile (KMM), one such platform which disrupted the development communities by its approach and thoughts on how to build mobile apps.

Traditional mobile apps, either built with a native or hybrid approach, have their tradeoffs from development time to performance. But with the Kotlin Multiplatform approach, we can have the best of both worlds.

What is Kotlin Multiplatform Mobile (KMM)?

Kotlin Multiplatform is all about code sharing within apps for different environments (iOS, Android). Some common use cases for shared code are getting data from the network, saving it into the device, filtering or manipulating data, etc. This is different from other cross-development frameworks as this enforces developers to share only business logic code rather than complete code which often makes things complicated, especially when it comes to building different complex custom UI for each platform.

Setting up your environment

If you are an Android developer, then you don't need to do much. The primary development of KMM apps is done using Android Studio. The only additional step for you is to install the KMM plugin via IDE plugin manager. One of the key benefits of this is it allows to you build and run the iOS app as well from Android Studio.

To enable iOS building and running via Android Studio, your system should have Xcode installed, which is development IDE for iOS development.

To verify all dependencies are installed correctly, we can use kdoctor, which can be installed using brew.

brew install kdoctor

Building Hello World!

With our setup complete, it's time to get our hands dirty and build our first Hello World application.

Creating a KMM application is very easy. Open Android Studio and then select Kotlin Multiplatform App from the New Project template. Hit Next.

On the next screen, add the basic application details like the name of the application, location of the project, etc.

Finally, select the dependency manager for the iOS app, which is recommended for Regular framework, and then hit finish.

Once gradle sync is complete, we can run both iOS and Android app using the run button from the toolbar.

That will start the Android emulator or iOS simulator, where our app will run.

src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/first_multiplatform_project_on_ios_1_cda32945d8.png" width=40%>

Basics of the Kotlin Multiplatform

Now it's time to understand what's happening under the hood to grasp the basic concepts of KMM.

Understanding project structure

Any KMM project can be split into three logic folders — i.e., androidApp, iosApp, and shared — and each of these folders has a specific purpose.

Since KMM is all about sharing business-/logic-related code, all the shared code is written under shared the folder. This code is then exposed as libs to androidApp and iosApp folders, allowing us to use shared logic by calling classes or functions and building a user interface on top of it.

Writing platform-specific code

There can be a few use cases where you like to use platform-specific APIs for writing business logic like in the Hello World! app where we wanted to know the platform type and version. To handle such use cases, KMM has introduced the concept of actual and expect, which can be thought of as KMM's way of interface or Protocols.

In this concept, we define expect for the functionality to be exposed, and then we write its implementation actual for the different environments. Something like this:


expect fun getPlatform(): String

actual fun getPlatform(): String = "Android ${android.os.Build.VERSION.SDK_INT}"

actual fun getPlatform(): String =
    UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion

In the above example, you'll notice that we are using platform-specific APIs like android.os or UIDevice in shared folder. To keep this organised and readable, KMM has divided the shared folder into three subfolders: commonMain, androidMain, iOSMain.

With this, we covered the basics of KMM (and that small learning curve for KMM is especially for people coming from an android background) needed before building a complex and full-fledged real app.

Building a more complex app

Now let's build our first real-world application, Querize, an app that helps you collect queries in real time during a session. Although this is a very simple app, it still covers all the basic use cases highlighting the benefits of the KMM app with a complex one, like accessing data in real time.

The tech stack for our app will be:

JetPack Compose for UI building.
Kotlin Multiplatform with Realm as a middle layer.
Atlas Flexible Device Sync from MongoDB, serverless backend supporting our data sharing.
MongoDB Atlas, our cloud database.

We will be following a top to bottom approach in building the app, so let's start building the UI using Jetpack compose with ViewModel.


class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                Container()
            }
        }
    }
}


@Preview
@Composable
fun Container() {
    val viewModel = viewModel<MainViewModel>()


    Scaffold(
        topBar = {
            CenterAlignedTopAppBar(
                title = {
                    Text(
                        text = "Querize",
                        fontSize = 24.sp,
                        modifier = Modifier.padding(horizontal = 8.dp)
                    )
                },
                colors = TopAppBarDefaults.centerAlignedTopAppBarColors(MaterialTheme.colorScheme.primaryContainer),
                navigationIcon = {
                    Icon(
                        painterResource(id = R.drawable.ic_baseline_menu_24),
                        contentDescription = ""
                    )
                }
            )
        },
        containerColor = (Color(0xffF9F9F9))
    ) {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(it),
        ) {

            Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.Center) {
                Image(
                    painter = painterResource(id = R.drawable.ic_realm_logo),
                    contentScale = ContentScale.Fit,
                    contentDescription = "App Logo",
                    modifier = Modifier
                        .width(200.dp)
                        .defaultMinSize(minHeight = 200.dp)
                        .padding(bottom = 20.dp),
                )
            }

            AddQuery(viewModel)

            Text(
                "Queries",
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(bottom = 8.dp),
                textAlign = TextAlign.Center,
                fontSize = 24.sp
            )

            QueriesList(viewModel)
        }
    }
}


@Composable
fun AddQuery(viewModel: MainViewModel) {

    val queryText = remember { mutableStateOf("") }

    TextField(
        modifier = Modifier
            .fillMaxWidth()
            .padding(8.dp),
        placeholder = { Text(text = "Enter your query here") },
        trailingIcon = {
            Icon(
                painterResource(id = R.drawable.ic_baseline_send_24),
                contentDescription = "",
                modifier = Modifier.clickable {
                    viewModel.saveQuery(queryText.value)
                    queryText.value = ""
                })
        },
        value = queryText.value,
        onValueChange = {
            queryText.value = it
        })
}

@Composable
fun QueriesList(viewModel: MainViewModel) {

    val queries = viewModel.queries.observeAsState(initial = emptyList()).value

    LazyColumn(
        verticalArrangement = Arrangement.spacedBy(12.dp),
        contentPadding = PaddingValues(8.dp),
        content = {
            items(items = queries, itemContent = { item: String ->
                QueryItem(query = item)
            })
        })
}

@Preview
@Composable
fun QueryPreview() {
    QueryItem(query = "Sample text")
}

@Composable
fun QueryItem(query: String) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .background(Color.White)
            .padding(8.dp)
            .clip(RoundedCornerShape(8.dp))
    ) {
        Text(text = query, modifier = Modifier.fillMaxWidth())
    }
}

class MainViewModel : ViewModel() {

    private val repo = RealmRepo()
    val queries: LiveData<List<String>> = liveData {
        emitSource(repo.getAllData().flowOn(Dispatchers.IO).asLiveData(Dispatchers.Main))
    }

    fun saveQuery(query: String) {
        viewModelScope.launch {
            repo.saveInfo(query)
        }
    }
}

In our viewModel, we have a method saveQuery to capture the user queries and share them with the speaker. This information is then passed on to our logic layer, RealmRepo, which is built using Kotlin Multiplatform for Mobile (KMM) as we would like to reuse this for code when building an iOS app.

class RealmRepo {

    suspend fun saveInfo(query: String) {

    }
}

Now, to save and share this information, we need to integrate it with Atlas Device Sync, which will automatically save and share it with our clients in real time. To connect with Device Sync, we need to add Realm SDK first to our project, which provides us integration with Device Sync out of the box.

Realm is not just SDK for integration with Atlas Device Sync, but it's a very powerful object-oriented mobile database built using KMM. One of the key advantages of using this is it makes our app work offline without any effort.

Adding Realm SDK

This step is broken down further for ease of understanding.

Adding Realm plugin

Open the build.gradle file under project root and add the Realm plugin.

From

plugins {
    id("com.android.application").version("7.3.1").apply(false)
    id("com.android.library").version("7.3.1").apply(false)
    kotlin("android").version("1.7.10").apply(false)
    kotlin("multiplatform").version("1.7.20").apply(false)
}

plugins {
    id("com.android.application").version("7.3.1").apply(false)
    id("com.android.library").version("7.3.1").apply(false)
    kotlin("android").version("1.7.10").apply(false)
    kotlin("multiplatform").version("1.7.20").apply(false)
    // Added Realm plugin 
    id("io.realm.kotlin") version "0.10.0"
}

Enabling Realm plugin

Now let's enable the Realm plugin for our project. We should make corresponding changes to the build.gradle file under the shared module.

From

plugins {
    kotlin("multiplatform")
    kotlin("native.cocoapods")
    id("com.android.library")
}

plugins {
    kotlin("multiplatform")
    kotlin("native.cocoapods")
    id("com.android.library")
    // Enabled Realm Plugin
    id("io.realm.kotlin")
}

Adding dependencies

With the last step done, we are just one step away from completing the Realm setup. In this step, we add the Realm dependency to our project.

Since the Realm database will be shared across all platforms, we will be adding the Realm dependency to the common source shared. In the same build.gradle file, locate the sourceSet tag and update it to:

From

 sourceSets {
    val commonMain by getting {
        dependencies {

        }
    }
    // Other config
}

 sourceSets {
   val commonMain by getting {
      dependencies {
         implementation("io.realm.kotlin:library-sync:1.4.0")
      }
   }
}

With this, we have completed the Realm setup for our KMM project. If you would like to use any part of the SDK inside the Android module, you can add the dependency in Android Module build.gradle file.

dependencies {
    compileOnly("io.realm.kotlin:library-sync:1.4.0")
}

Since Realm is an object-oriented database, we can save objects directly without getting into the hassle of converting them into different formats. To save any object into the Realm database, it should be derived from RealmObject class.

class QueryInfo : RealmObject {

    @PrimaryKey
    var _id: String = ""
    var queries: String = ""
}

Now let's save our query into the local database, which will then be synced using Atlas Device Sync and saved into our cloud database, Atlas.

class RealmRepo {

    suspend fun saveInfo(query: String) {
        val info = QueryInfo().apply {
            _id = RandomUUID().randomId
            queries = query
        }
        realm.write {
            copyToRealm(info)
        }
    }
}

The next step is to create a Realm instance, which we use to save the information. To create a Realm, an instance of Configuration is needed which in turn needs a list of classes that can be saved into the database.


val realm by lazy {
    val config = RealmConfiguration.create(setOf(QueryInfo::class))
    Realm.open(config)
}

This Realm instance is sufficient for saving data into the device but in our case, we need to integrate this with Atlas Device Sync to save and share our data into the cloud. To do this, we take four more steps:

Create a free MongoDB account.
Follow the setup wizard after signing up to create a free cluster.
Create an App with App Service UI to enable Atlas Device Sync.
Enable Atlas Device Sync using Flexible Sync. Select the App services tab and enable sync, as shown below.

Now let's connect our Realm and Atlas Device Sync. To do this, we need to modify our Realm instance creation. Instead of using RealmConfiguration, we need to use SyncConfiguration.

SyncConfiguration instance can be created using its builder, which needs a user instance and initialSubscriptions as additional information. Since our application doesn't have a user registration form, we can use anonymous sign-in provided by Atlas App Services to identify as user session. So our updated code looks like this:


private val appServiceInstance by lazy {
    val configuration =
        AppConfiguration.Builder("application-0-elgah").log(LogLevel.ALL).build()
    App.create(configuration)
}

lateinit var realm: Realm

private suspend fun setupRealmSync() {
    val user = appServiceInstance.login(Credentials.anonymous())
    val config = SyncConfiguration
        .Builder(user, setOf(QueryInfo::class))
        .initialSubscriptions { realm ->
            // information about the data that can be read or modified. 
            add(
                query = realm.query<QueryInfo>(),
                name = "subscription name",
                updateExisting = true
            )
        }
        .build()
    realm = Realm.open(config)
}

suspend fun saveInfo(query: String) {
    if (!this::realm.isInitialized) {
        setupRealmSync()
    }

    val info = QueryInfo().apply {
        _id = RandomUUID().randomId
        queries = query
    }
    realm.write {
        copyToRealm(info)
    }
}

Now, the last step to complete our application is to write a read function to get all the queries and show it on UI.

suspend fun getAllData(): CommonFlow<List<String>> {
    if (!this::realm.isInitialized) {
        setupRealmSync()
    }
    return realm.query<QueryInfo>().asFlow().map {
        it.list.map { it.queries }
    }.asCommonFlow()
}

Also, you can view or modify the data received via the saveInfo function using the Atlas UI.

With this done, our application is ready to send and receive data in real time. Yes, in real time. No additional implementation is required.

Summary

Thank you for reading this article! I hope you find it informative. The complete source code of the app can be found on GitHub.

If you have any queries or comments, you can share them on
the MongoDB Realm forum or tweet me @codeWithMohit.

Migrating Realm SDK database - Local Database

Mohit Sharma — Thu, 21 Oct 2021 09:44:49 +0000

This is a follow-up article in the Getting Started Series.
In this article, we learn how to modify/migrate Realm local database schema.

Introduction

As you add and change application features, you need to modify database schema, and the need for
migrations arises, which is very important for a seamless user experience.

By the end of this article, you will learn:

How to update database schema post-production release on play store.
How to migrate user data from one schema to another.

Before we get down to business, let's quickly recap how we set Realm in our application.

const val REALM_SCHEMA_VERSION: Long = 1
const val REALM_DB_NAME = "rMigrationSample.db"

fun setupRealm(context: Context) {
    Realm.init(context)

    val config = RealmConfiguration.Builder()
        .name(REALM_DB_NAME)
        .schemaVersion(REALM_SCHEMA_VERSION)
        .build()

    Realm.setDefaultConfiguration(config)
}

Doing migration in Realm is very straightforward and simple. The high-level steps for the successful
migration of any database are:

Update the database version.
Make changes to the database schema.
Migrate user data from old schema to new.

Update the Database Version

This is the simplest step, which can be done by incrementing the version of
REALM_SCHEMA_VERSION, which notifies Relam about database changes. This, in turn, runs triggers
migration, if provided.

To add migration, we use the migration function available in RealmConfiguration.Builder, which
takes an argument of RealmMigration, which we will review in the next step.

val config = RealmConfiguration.Builder()
    .name(REALM_DB_NAME)
    .schemaVersion(REALM_SCHEMA_VERSION)
    .migration(DBMigrationHelper())
    .build()

Make Changes to the Database Schema

In Realm, all the migration-related operation has to be performed within the scope
of RealmMigration.

class DBMigrationHelper : RealmMigration {

    override fun migrate(realm: DynamicRealm, oldVersion: Long, newVersion: Long) {
        migration1to2(realm.schema)
        migration2to3(realm.schema)
        migration3to4(realm.schema)
    }

    private fun migration3to4(schema: RealmSchema?) {
        TODO("Not yet implemented")
    }

    private fun migration2to3(schema: RealmSchema?) {
        TODO("Not yet implemented")
    }

    private fun migration1to2(schema: RealmSchema) {
        TODO("Not yet implemented")
    }
}

To add/update/rename any field:


private fun migration1to2(schema: RealmSchema) {
    val userSchema = schema.get(UserInfo::class.java.simpleName)
    userSchema?.run {
        addField("phoneNumber", String::class.java, FieldAttribute.REQUIRED)
        renameField("phoneNumber", "phoneNo")
        removeField("phoneNo")
    }
}

Migrate User Data from Old Schema to New

All the data transformation during migration can be done with transform function with the help
of set and get methods.


private fun migration2to3(schema: RealmSchema) {
    val userSchema = schema.get(UserInfo::class.java.simpleName)
    userSchema?.run {
        addField("fullName", String::class.java, FieldAttribute.REQUIRED)
        transform {
            it.set("fullName", it.get<String>("firstName") + it.get<String>("lastName"))
        }
    }
}

In the above snippet, we are setting the default value of fullName by extracting the value from
old data, like firstName and lastName.

We can also use transform to update the data type.


val personSchema = schema!!["Person"]

// Change type from String to int
schema["Pet"]?.run {
    addField("type_tmp", Int::class.java)
    transform { obj ->
        val oldType = obj.getString("type")
        if (oldType == "dog") {
            obj.setLong("type_tmp", 1)
        } else if (oldType == "cat") {
            obj.setInt("type_tmp", 2)
        } else if (oldType == "hamster") {
            obj.setInt("type_tmp", 3)
        }
    }
    removeField("type")
    renameField("type_tmp", "type")
}

In case you want to delete the complete Realm, you can use deleteRealmIfMigrationNeeded with
RealmConfiguration.Builder, but that should be considered as the last resort.

Thank you for reading! If you have any queries or comments, you can share them on the MongoDB Realm forum or tweet
me @codeWithMohit.

In the next article, we will discuss how to migrate the Realm database with sync.

If you have an iOS app, do check out the iOS tutorial
on Realm iOS Migration.

StartActivityForResult is deprecated !!

Mohit Sharma — Fri, 24 Sep 2021 06:18:15 +0000

Introduction

Android has been on the edge of evolution for a while recently, with updates to androidx.activity:activity-ktx
to 1.2.0. It has deprecated startActivityForResult in favour of registerForActivityResult.

It was one of the first fundamentals that any Android developer has learned, and the backbone of Android's way of
communicating between two components. API design was simple enough to get started quickly but had its cons, like how
it’s hard to find the caller in real-world applications (except for cmd+F in the project 😂), getting results on the
fragment, results missed if the component is recreated, conflicts with the same request code, etc.

Let’s try to understand how to use the new API with a few examples.

Example 1: Activity A calls Activity B for the result

Old School:

// Caller 
val intent = Intent(context, Activity1::class.java)
startActivityForResult(intent, REQUEST_CODE)

// Receiver 
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (resultCode == Activity.RESULT_OK && requestCode == REQUEST_CODE) {
        val value = data?.getStringExtra("input")
    }
}

New Way:


// Caller 
val intent = Intent(context, Activity1::class.java)
getResult.launch(intent)

// Receiver 
private val getResult =
    registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) {
        if (it.resultCode == Activity.RESULT_OK) {
            val value = it.data?.getStringExtra("input")
        }
    }

As you would have noticed, registerForActivityResult takes two parameters. The first defines the type of
action/interaction needed (ActivityResultContracts) and the second is a callback function where we receive the result.

Nothing much has changed, right? Let’s check another example.

Example 2: Start external component like the camera to get the image:

//Caller
getPreviewImage.launch(null)

//Receiver 
private val getPreviewImage = registerForActivityResult(ActivityResultContracts.TakePicture { bitmap ->
    // we get bitmap as result directly
})

The above snippet is the complete code getting a preview image from the camera. No need for permission request code, as
this is taken care of automatically for us!

Another benefit of using the new API is that it forces developers to use the right contract. For example,
with ActivityResultContracts.TakePicture() — which returns the full image — you need to pass a URI as a parameter
to launch, which reduces the development time and chance of errors.

Other default contracts available can be
found here.

Example 3: Fragment A calls Activity B for the result

This has been another issue with the old system, with no clean implementation available, but the new API works
consistently across activities and fragments. Therefore, we refer and add the snippet from example 1 to our fragments.

Example 4: Receive the result in a non-Android class

Old Way: 😄

With the new API, this is possible using ActivityResultRegistry directly.

class MyLifecycleObserver(private val registry: ActivityResultRegistry) : DefaultLifecycleObserver {

    lateinit var getContent: ActivityResultLauncher<String>

    override fun onCreate(owner: LifecycleOwner) {
        getContent = registry.register("key", owner, GetContent()) { uri ->
            // Handle the returned Uri
        }
    }

    fun selectImage() {
        getContent.launch("image/*")
    }
}

class MyFragment : Fragment() {
    lateinit var observer: MyLifecycleObserver

    override fun onCreate(savedInstanceState: Bundle?) {
        // ...

        observer = MyLifecycleObserver(requireActivity().activityResultRegistry)
        lifecycle.addObserver(observer)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        val selectButton = view.findViewById<Button>(R.id.select_button)

        selectButton.setOnClickListener {
            // Open the activity to select an image
            observer.selectImage()
        }
    }
}

Summary

I have found the registerForActivityResult useful and clean. Some of the pros, in my opinion, are:

Improve the code readability, no need to remember to jump to onActivityResult() after startActivityForResult.
ActivityResultLauncher returned from registerForActivityResult used to launch components, clearly defining the
input parameter for desired results.
Removed the boilerplate code for requesting permission from the user.

Hope this was informative and enjoyed reading it.

Building Splash Screen natively, Android 12, Kotlin

Mohit Sharma — Thu, 23 Sep 2021 14:51:36 +0000

In this article, we will explore and learn how to build a splash screen with SplashScreen API, which was introduced in Android 12.

What is a Splash Screen?

It is the first view that is shown to a user as soon as you tap on the app icon. If you notice a blank white screen (for a
short moment) after tapping on your favourite app, it means it doesn't have a splash screen.

Why/When Do I Need It?

Often, the splash screen is seen as a differentiator between normal and professional apps. Some use cases where a splash screen fits perfectly are:

When we want to download data before users start using the app.
If we want to promote app branding and display your logo for a longer period of time, or just have a more immersive experience that smoothly takes you from the moment you tap on the icon to whatever the app has to offer.

Until now, creating a splash screen was never straightforward and always required some amount of boilerplate code added to the application, like creating SplashActivity with no view, adding a timer for branding promotion purposes, etc. With SplashScreen API, all of this is set to go.

Show Me the Code

Step 1: Creating a Theme

Even for the new SplashScreen API, we need to create a theme but in the value-v31 folder as a few parameters are supported only in Android 12. Therefore, create a folder named value-v31 under res folder and add theme.xml to it.

And before that, let’s break our splash screen into pieces for simplification.

Point 1 represents the icon of the screen.
Point 2 represents the background colour of the splash screen icon.
Point 3 represents the background colour of the splash screen.
Point 4 represents the space for branding logo if needed.

Now, let's assign some values to the corresponding keys that describe the different pieces of the splash screen.


<style name="SplashActivity" parent="Theme.AppCompat.NoActionBar">

    <!-- Point 3-->
    <item name="android:windowSplashScreenBackground">#FFFFFF</item>

    <!-- Point 2-->
    <item name="android:windowSplashScreenIconBackgroundColor">#000000</item>

    <!-- Point 1-->
    <item name="android:windowSplashScreenAnimatedIcon">@drawable/ic_realm_logo_250</item>

    <!-- Point 4-->
    <item name="android:windowSplashScreenBrandingImage">@drawable/relam_horizontal</item>
</style>

In case you want to use an app icon (or don't have a separate icon) as windowSplashScreenAnimatedIcon, you ignore this
parameter and by default, it will take your app icon.

Tips & Tricks: If your drawable icon is getting cropped on the splash screen, create an app icon from the image
and then replace the content of windowSplashScreenAnimatedIcon drawable with the ic_launcher_foreground.xml.

For windowSplashScreenBrandingImage, I couldn't find any alternative. Do share in the comments if you find one.

Step 2: Add the Theme to Activity

Open AndroidManifest file and add a theme to the activity.

<activity
 android:theme="@style/SplashActivity">
</activity>

In my view, there is no need for a new activity class for the splash screen, which traditionally was required.

And now we are all set for the new Android 12 splash screen.

Adding animation to the splash screen is also a piece of cake. Just update the icon drawable with
AnimationDrawable and AnimatedVectorDrawable drawable and custom parameters for the duration of the animation.

<item name="android:windowSplashScreenAnimationDuration">1000</item>

Earlier, I mentioned that the new API helps with the initial app data download use case, so let's see that in action.

In the splash screen activity, we can register for addOnPreDrawListener listener which will help to hold off the first
draw on the screen, until data is ready.

 private val viewModel: MainViewModel by viewModels()

 override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     addInitialDataListener()
     loadAppView()
 }

 private fun addInitialDataListener() {
     val content: View = findViewById(android.R.id.content)
     // This would be called until true is not returned from the condition
     content.viewTreeObserver.addOnPreDrawListener {
         return@addOnPreDrawListener viewModel.isAppReady.value ?: false
     }
 }

 private fun loadAppView() {
     binding = ActivityMainBinding.inflate(layoutInflater)
     setContentView(binding.root)

Tips & Tricks: While developing Splash screen you can return false for addOnPreDrawListener, so the next screen is not rendered and you can validate the splash screen easily.

Summary

I really like the new SplashScreen API, which is very clean and easy to use, getting rid of SplashScreen activity altogether. There are a few things I disliked, though.

The splash screen background supports only single colour. We're waiting for support of vector drawable backgrounds.
There is no design spec available for icon and branding images, which makes for more of a hit and trial game. I still couldn't fix the banding image, in my example.
Last but not least, SplashScreen UI side feature(theme.xml) is only supported from Android 12 and above, so we can't get rid of the old code for now.

You can also check out the complete working example from my GitHub repo. Note: Just running code on the device will show you white. To see the example, close the app recent tray and then click on the app icon again.

Github Repo link

Hope this was informative and enjoyed reading it. Do share your queries in the comment below.