Jorge D. Ortiz-Fuentes

Mohit Sharma

## Introduction

So, it's here! The engineering team has [released a major milestone of the Kotlin
SDK](https://www.mongodb.com/developer/article/announcing-realm-kotlin-beta/). The preview is [available to
you](https://github.com/realm/realm-kotlin) to try it and make comments and suggestions.

Until now, if you were using Realm in Android, you were using the Java version of the SDK.  The purpose of the Realm
Kotlin SDK is to be the evolution of the Java one and eventually replace it.  So, you might be wondering if and when you
should migrate to it.  But even more important for your team and your app is what it provides that the Java SDK
doesn't.  The Kotlin SDK has been written from scratch to combine what the engineering team has learned through years of
SDK development, with the expressivity and fluency of the Kotlin language.  They have been successful at that and the
resulting SDK provides a first-class experience that I would summarize in the following points:

- The Kotlin SDK allows you to use expressions that are Kotlin idiomatic&mdash;i.e., more natural to the language.
- It uses Kotlin coroutines and flows to make concurrency easier and more efficient.
- It has been designed and developed with Kotlin Multiplatform in mind.
- It has removed the thread-confinement restriction on Java and it directly integrates with the Android lifecycle hooks
  so the developer doesn't have to spin up and tear down a realm instance on every activity lifecycle.
- It's the way forward.  MongoDB is not discontinuing the Java SDK anytime soon, but Kotlin provides the engineering
  team more resources to implement cooler things going forward. A few of them have been implemented already.  Why wouldn't
  you want to benefit from them?

Are you on board?  I hope you are, because through the rest of this article, I'm going to tell you how to upgrade your
projects to use the Realm Kotlin SDK and take advantage of those benefits that I have just mentioned and some more.  You
can also find a complete code example in this [repo](https://github.com/mongodb-developer/ExpenseManagerToKotlinSDK).

> **Build better mobile apps with Atlas Device Sync**: Atlas Device Sync is a fully-managed mobile backend-as-a-service. Leverage out-of-the-box infrastructure, data synchronization capabilities, built-in network handling, and much more to quickly launch enterprise-grade mobile apps. [Get started now by build: Deploy Sample for Free](https://www.mongodb.com/realm/register?tck=devhub_migratingandroidapps)!


## Gradle build files

First things first.  You need to make some changes to your `build.gradle` files to get access to the Realm Kotlin SDK
within your project, instead of the Realm Java SDK that you were using. The Realm Kotlin SDK uses a gradle plugin that
has been published in the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/io.realm.kotlin), so the prefered way
to add it to your project is using the plugins section of the build configuration of the module &mdash;i.e.,
`app/build.gradle`&mdash; instead of the legacy method of declaring the dependency in the `buildscript` block of the
project `build.gradle`.

After replacing the plugin in the module configuration with the Kotlin SDK one, you need to add an implementation
dependency to your module.  If you want to use [Sync](https://www.mongodb.com/realm/mobile/sync) with your MongoDB
cluster, then you should use `'io.realm.kotlin:library-sync'`, but if you just want to have local persistence, then
`'io.realm.kotlin:library-base'` should be enough.  Also, it's no longer needed to have a `realm` dsl section in the
`android` block to enable sync.


### `build.gradle` Comparison

#### Java SDK

```kotlin
buildscript {
	// ...
    dependencies {
        classpath "com.android.tools.build:gradle:$agp_version"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"

        // Realm Plugin
        classpath "io.realm:realm-gradle-plugin:10.10.1"
    }
}
```

#### Kotlin SDK

```kotlin
buildscript {
	// ...
    dependencies {
        classpath "com.android.tools.build:gradle:$agp_version"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
```

### `app/build.gradle` Comparison

#### Java SDK

```kotlin
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'kotlin-kapt'
    id 'realm-android'
}
android {
	// ...
    realm {
        syncEnabled = true
    }
}
dependencies {
	// ...
}
```

#### Kotlin SDK

```kotlin
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'kotlin-kapt'
    id 'io.realm.kotlin' version '0.10.0'
}
android {
	// ...
}
dependencies {
	// ...
    implementation("io.realm.kotlin:library-base:0.10.0")
}
```


If you have more than one module in your project and want to pin the version number of the plugin for all of them, you
can define the plugin in the project `build.gradle` with the desired version and the attribute `apply false`.  Then, the
`build.gradle` files of the modules should use the same plugin id, but without the version attribute.

### Multimodule Configuration

#### Project build.gradle

```kotlin
plugins {
	// ...
    id 'io.realm.kotlin' version '0.10.0' apply false
}
```

#### Modules build.gradle

```kotlin
plugins {
	// ...
    id 'io.realm.kotlin'
}
```


## Model classes

Kotlin scope functions (i.e., `apply`, `run`, `with`, `let`, and `also`) make object creation and manipulation easier.
That was already available when using the Java SDK from kotlin, because they are provided by the Kotlin language itself.

Defining a model class is even easier with the Realm Kotlin SDK.  You are not required to make the model class `open`
anymore.  The Java SDK was using the Kotlin Annotation Processing Tool to derive proxy classes that took care of
interacting with the persistence.  Instead, the Kotlin SDK uses the `RealmObject` interface as a marker for the plugin.
In the construction process, the plugin identifies the objects that are implementing the marker interface and injects the
required functionality to interact with the persistence.  So, that's another change that you have to put in place:
instead of making your model classes extend &mdash;i.e., inherit&mdash; from `RealmObject`, you just have to implement the interface
with the same name.  In practical terms, this means using `RealmObject` in the class declaration without parentheses.

### Model Class Definition

#### Java SDK

```kotlin
open class ExpenseInfo : RealmObject() {
    @PrimaryKey
    var expenseId: String = UUID.randomUUID().toString()
    var expenseName: String = ""
    var expenseValue: Int = 0
}
```

#### Kotlin SDK

```kotlin
class ExpenseInfo : RealmObject {
    @PrimaryKey
    var expenseId: String = UUID.randomUUID().toString()
    var expenseName: String = ""
    var expenseValue: Int = 0
}
```

There are also changes in terms of the type system.  `RealmList` that was used in the Java SDK to model one-to-many
relationships is extended in the Kotlin SDK to benefit from the typesystem and allow expressing nullables in those
relationships.  So, now you can go beyond `RealmList<String>` and use `RealmList<String?>`.  You will get all the
benefits of the syntax sugar to mean that the strings the object is related to, might be null.  You can check this and
the rest of the supported types in the [documentation](https://docs.mongodb.com) of the Realm Kotlin SDK.


## Opening (and closing) the realm

Using Realm is even easier now.  The explicit initialization of the library that was required by the Realm Java SDK is
not needed for the Realm Kotlin SDK.  You did that invoking `Realm.init()` explicitly.  And in order to ensure that you
did that once and at the beginning of the execution of your app, you normally put that line of code in the `onCreate()`
method of the `Application` subclass.  You can forget about that chore for good.

The configuration of the Realm in the Kotlin SDK requires passing the list of object model classes that conform the
schema, so the `builder()` static method has that as the argument.  The Realm Kotlin SDK also allows setting the logging
level per configuration, should you use more than one.  The rest of the configuration options remain the same.

It's also different the way you get an instance of a Realm when you have defined the configuration that you want to
use.  With the Java SDK, you had to get access to a thread singleton using one of the static methods
`Realm.getInstance()` or `Realm.getDefaultInstance()` (the latter when a default configuration was being set and used).
In most cases, that instance was used and released, by invoking its `close()` method, at the end of the
Activity/Fragment lifecycle.  The Kotlin SDK allows you to use the static method `open()` to get a single instance of a
Realm per configuration.  Then you can inject it and use it everywhere you need it.  This change takes the burden of
Realm lifecycle management off from the shoulders of the developer.  That is huge!  Lifecycle management is often
painful and sometimes difficult to get right.

### Realm SDK Initialization

#### Java SDK

```kotlin
class ExpenseApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Realm.init(this)

        val config = RealmConfiguration.Builder()
            .name("expenseDB.db")
            .schemaVersion(1)
            .deleteRealmIfMigrationNeeded()
            .build()

        Realm.setDefaultConfiguration(config)
        // Realms can now be obtained with Realm.getDefaultInstance()
    }
}
```

#### Kotlin SDK

```kotlin
class ExpenseApplication : Application() {
    lateinit var realm: Realm

    override fun onCreate() {
        super.onCreate()

        val config = RealmConfiguration
            .Builder(schema = setOf(ExpenseInfo::class))
            .name("expenseDB.db")
            .schemaVersion(1)
            .deleteRealmIfMigrationNeeded()
            .log(LogLevel.ALL)
            .build()

        realm = Realm.open(configuration = config)
        // This realm can now be injected everywhere
    }
}
```

Objects in the Realm Kotlin SDK are now frozen to directly integrate seamlessly into Kotlin coroutine and flows.  That
means that they are not live as they used to be in the Realm Java SDK and don't update themselves when they get changed
in some other part of the application or even in the cloud.  Instead, you have to modify them within a write
transaction, i.e., within a `write` or `writeBlocking` block.  When the scope of the block ends, the objects are frozen
again.

Even better, the realms aren't confined to a thread.  No more thread singletons.  Instead, realms are thread-safe, so
they can safely be shared between threads.  That means that you don't need to be opening and closing realms for the
purpose of using them within a thread.  Get your Realm and use it everywhere in your app.  Say goodbye to all those
lifecycle management operations for the realms!

Finally, if you are injecting dependencies of your application, with the Realm Kotlin SDK, you can have a singleton for
the Realm and let the dependency injection framework do its magic and inject it in every view-model.  That's much easier
and more efficient than having to create one each time &mdash;using a factory, for example&mdash; and ensuring that the
close method was called wherever it was injected.


## Writing data

It took a while, but Kotlin brought coroutines to Android and we have learned to use them and enjoy how much easier
they make doing asynchronous things.  Now, it seems that coroutines are _the way_ to do those things and we would like
to use them to deal with operations that might affect the performance of our apps, such as dealing with the persistence
of our data.

Support for coroutines and flows is built-in in the Realm Kotlin SDK as a first-class citizen of the API.  You no longer
need to insert write operations in suspending functions to benefit from coroutines.  The `write {}` method of a realm is
a suspending method itself and can only be invoked from within a coroutine context.  No worries here, since the compiler
will complain if you try to do it outside of a context.  But with no extra effort on your side, you will be performing
all those expensive IO operations asynchronously. Ain't that nice?

You can still use the `writeBlocking {}` of a realm, if you need to perform a synchronous operation.  But, beware that,
as the name states, the operation will block the current thread.  Android might not be very forgiving if you block the
main thread for a few seconds, and it'll present the user with the undesirable "Application Not Responding" dialog.  Please,
be mindful and use this **only when you know it is safe**.

Another additional advantage of the Realm Kotlin SDK is that, thanks to having the objects frozen in the realm, we can
make asynchronous transactions easier.  In the Java SDK, we had to find again the object we wanted to modify inside of
the transaction block, so it was obtained from the realm that we were using on that thread.  The Kotlin SDK makes that
much simpler by using `findLatest()` with that object to get its instance in the mutable realm and then apply the
changes to it.


### Asynchronous Transaction Comparison

#### Java SDK

```kotlin
realm.executeTransactionAsync { bgRealm ->
    val result = bgRealm.where(ExpenseInfo::class.java)
        .equalTo("expenseId", expenseInfo.expenseId)
        .findFirst()

    result?.let {
        result.deleteFromRealm()
    }
}
```

#### Kotlin SDK

```kotlin
viewModelScope.launch(Dispatchers.IO) {
    realm.write {
        findLatest(expenseInfo)?.also {
            delete(it)
        }
    }
}
```


## Queries and listening to updates

One thing where Realm shines is when you have to retrieve information from it.  Data is obtained concatenating three
operations:

1. Creating a RealmQuery for the object class that you are interested in.
2. Optionally adding constraints to that query, like expected values or acceptable ranges for some attributes.
3. Executing the query to get the results from the realm.  Those results can be actual objects from the realm, or
   aggregations of them, like the number of matches in the realm that you get when you use `count()`.

The Realm Kotlin SDK offers you a new query system where each of those steps has been simplified.


The queries in the Realm Java SDK used filters on the collections returned by the `where` method.  The Kotlin SDK offers
the `query` method instead.  This method takes a type parameter using generics, instead of the explicit type parameter
taken as an argument of `where` method.  That is easier to read and to write.

The constraints that allow you to narrow down the query to the results you care about are implemented using a predicate
as the optional argument of the `query()` method.  That predicate can have multiple constraints concatenated with
logical operators like `AND` or `OR` and even subqueries that are a mayor superpower that will boost your ability to
query the data.

Finally, you will execute the query to get the data.  In most cases, you will want that to happen in the background so
you are not blocking the main thread.  If you also want to be aware of changes on the results of the query, not just the
initial results, it's better to get a flow.  That required two steps in the Java SDK.  First, you had to use
`findAllAsync()` on the query, to get it to work in the background, and then convert the results into a flow with the
`toFlow()` method.  The new system simplifies things greatly, providing you with the `asFlow()` method that is a
suspending function of the query.  There is no other step.  Coroutines and flows are built-in from the beginning in the
new query system.

### Query Comparison

#### Java SDK

```kotlin
private fun getAllExpense(): Flow<List<ExpenseInfo>> =
    realm.where(ExpenseInfo::class.java).greaterThan("expenseValue", 0).findAllAsync().toFlow()
```

#### Kotlin SDK

```kotlin
private fun getAllExpense(): Flow<ResultsChange<ExpenseInfo>> =
    realm.query<ExpenseInfo>("expenseValue > 0").asFlow()
```

As it was the case when writing to the Realm, you can also use blocking operations when you need them, invoking `find()`
on the query.  And also in this case, use it **only when you know it is safe**.


## Conclusion

You're probably not reading this, because if I were you, I would be creating a branch in my project and trying the
Realm Kotlin SDK already and benefiting from all these wonderful changes.  But just in case you are, let me summarize the
most relevant changes that the Realm Kotlin SDK provides you with:

- The configuration of your project to use the Realm Kotlin SDK is easier, uses more up-to-date mechanisms, and is more
  explicit.
- Model classes are simpler to define and more idiomatic.
- Working with the realm is much simpler because it requires less ceremonial steps that you have to worry about and
  plays better with coroutines.
- Working with the objects is easier even when doing things asynchronously, because they're frozen, and that helps you
  to do things safely.
- Querying is enhanced with simpler syntax, predicates, and suspending functions and even flows.

Time to code!


This is a guide to help you migrate you apps that are using the Realm Java SDK to the newer Realm Kotlin SDK. It covers the most important changes that you need to put in place to use the Kotlin SDK.

Migrating Android Apps from Realm Java SDK to Kotlin SDK

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.

Getting Started with the MongoDB Kotlin Driver


# Introduction 

### What is Jetpack Compose?

As per [Google](https://developer.android.com/jetpack/compose), *“Jetpack Compose is Android’s modern toolkit for building native UI. It simplifies and accelerates UI development on Android. Quickly bring your app to life with less code, powerful tools, and intuitive Kotlin APIs”.*

In my words, it’s a revolutionary **declarative way** of creating (or should I say composing 😄) UI in Android using Kotlin. Until now, we created layouts using XML and never dared to create via code (except for custom views, no choice) due to its complexity, non-intuitiveness, and maintenance issues.

But now it’s different!

### What is Declarative UI?


>  You know, imperative is like **how** you do something, and declarative is more like **what** you do, or something.

Doesn’t that make sense? It didn’t to me as well in the first go 😄. In my opinion, imperative is more like an algorithm to perform any operation step by step, and declarative is the code that is built using the algorithm, more to do ***what*** works.

In Android, we normally create an XML of a layout and then update (sync) each element every time based on the input received, business rules using findViewById/Kotlin Semantics/View Binding/ Data Binding 😅.

But with **Compose**, we simply write a function that has both elements and rules, which is called whenever information gets updated. In short, a part of the UI is recreated every time **without** **performance** **issues**.

This philosophy or mindset will in turn help you write smaller (Single Responsibility principle) and reusable functions.


### Why is Compose Getting So Popular?

I’m not really sure, but out of the many awesome features, the ones I’ve loved most are:

1. **Faster release cycle**: Bi-weekly, so now there is a real chance that if you get any issue with **composing,** it can be fixed soon. Hopefully!

2. **Interoperable**: Similar to Kotlin, Compose is also interoperable with earlier UI design frameworks.

3. **Jetpack library and material component built-in support**: Reduce developer efforts and time in building beautiful UI with fewer lines of code ❤️.

4. **Declarative UI**: With a new way of building UI, we are now in harmony with all other major frontend development frameworks like SwiftUI, Flutter, and React Native, making it easier for the developer to use concepts/paradigms from other platforms.

### Current state

As of 29th July, the first stable version was [released 1.0](https://android-developers.googleblog.com/2021/07/jetpack-compose-announcement.html), meaning **Compose is production-ready**.


# Get Started with Compose

### For using Compose, we need to set up a few things:


 1. Kotlin v*1.5.10* and above, so let’s update our dependency in the project-level `build.gradle` file.

    ```kotlin
    plugins {
            id 'org.jetbrains.kotlin:android' version '1.5.10'
    } 
    ```

2. Minimum  *API level 21*

    ```kotlin
    android {
         defaultConfig {
             ...
             minSdkVersion 21
        }
    }    
    ```

3. Enable Compose 

    ```kotlin
        android { 

            defaultConfig {
                ...
                minSdkVersion 21
            }

            buildFeatures {
                // Enables Jetpack Compose for this module
                compose true
            }
        }
    ```
    
4. Others like min Java or Kotlin compiler and compose compiler

    ```kotlin
        android {
            defaultConfig {
                ...
                minSdkVersion 21
            }

            buildFeatures {
                // Enables Jetpack Compose for this module
                compose true
            }
            ...

            // Set both the Java and Kotlin compilers to target Java 8.
           compileOptions {
                sourceCompatibility JavaVersion.VERSION_1_8
                targetCompatibility JavaVersion.VERSION_1_8
            }
            kotlinOptions {
                jvmTarget = "1.8"
            }

            composeOptions {
                kotlinCompilerExtensionVersion '1.0.0'
            }
        }
    ```

5. At last compose dependency for build UI

    ```kotlin
        dependencies {

            implementation 'androidx.compose.ui:ui:1.0.0'
            // Tooling support (Previews, etc.)
            implementation 'androidx.compose.ui:ui-tooling:1.0.0'
            // Foundation (Border, Background, Box, Image, Scroll, shapes, animations, etc.)
            implementation 'androidx.compose.foundation:foundation:1.0.0'
            // Material Design
            implementation 'androidx.compose.material:material:1.0.0'
            // Material design icons
            implementation 'androidx.compose.material:material-icons-core:1.0.0'
            implementation 'androidx.compose.material:material-icons-extended:1.0.0'
            // Integration with activities
            implementation 'androidx.activity:activity-compose:1.3.0'
            // Integration with ViewModels
            implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha07'
            // Integration with observables
            implementation 'androidx.compose.runtime:runtime-livedata:1.0.0'

        }
    ```


### Mindset 

While composing UI, you need to unlearn various types of layouts and remember just one thing: Everything is a composition of *rows* and *columns*.

![](https://cdn-images-1.medium.com/max/2108/1*VhWkcj7aUWNdE7e3CYJdQw.png)

But what about ConstraintLayout, which makes life so easy and is very useful for building complex UI? We can still use it ❤️, but in a little different way.


### First Compose Project — Tweet Details Screen



For our learning curve experience, I decided to re-create this screen in Compose.

![](https://cdn-images-1.medium.com/max/2000/1*yeFRhDs5R1CP4zaEomCmjQ.png)



So let’s get started. 

Create a new project with Compose project as a template and open MainActivity.

If you don’t see the Compose project, then update Android Studio to the latest version.

```kotlin
    class MainActivity : ComponentActivity() {
    
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContent {
                ComposeTweetTheme {
               
                    .... 
                }
            }
        }
    }
```

Now to add a view to the UI, we need to create a function with `@Composable` annotation, which makes it a Compose function.

Creating our first layout of the view, toolbar

```kotlin
    @Composable
    fun getAppTopBar() {
        TopAppBar(
            title = {
                Text(text = stringResource(id = R.string.app_name))
            },
            elevation = 0.*dp
        )
    }
```

To preview the UI rendered in Android Studio, we can use `@Preview` annotation.

![](https://cdn-images-1.medium.com/max/4856/1*ukkhEHOGJ2B7WlPpDxHHzg.png)

TopAppBar is an inbuilt material component for adding a topbar to our application.

Let’s create a little more complex view, user profile view

![](https://cdn-images-1.medium.com/max/2000/1*EgdJyqYqrpsl2w67GSrHIw.png)

As discussed earlier, in Compose, we have only rows and columns, so let’s break our UI 👇, where the red border represents columns and green is rows, and complete UI as a row in the screen.

![](https://cdn-images-1.medium.com/max/2000/1*ICvhTxCdsy8RXR8jsMfO3g.png)

So let’s create our compose function for user profile view with our root row.

![](https://cdn-images-1.medium.com/max/3984/1*v-SIoDDh9pQSTtJ6ooSyqQ.png)

You will notice the modifier argument in the Row function. This is the Compose way of adding formatting to the elements, which is uniform across all the elements.

Creating a round imageview is very simple now. No need for any library or XML drawable as an overlay.

```kotlin
Image(
            painter = painterResource(id = R.drawable.ic_profile),
            contentDescription = "Profile Image",
            modifier = Modifier
                .size(36.dp)
                .clip(CircleShape)
                .border(1.dp, Color.Transparent, CircleShape),
            contentScale = ContentScale.Crop
        )
 ```

Again we have a `modifier` for updating our Image (AKA ImageView) with `clip` to make it rounded and `contentScale` to scale the image. 

Similarly, adding a label will be a piece of cake now.

```kotlin
     Text (text = userName, fontSize = 20.sp)
```

Now let’s put it all together in rows and columns to complete the view.

```kotlin
@Composable
fun userProfileView(userName: String, userHandle: String) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(all = 12.dp),
        verticalAlignment = Alignment.CenterVertically
    ) {
        Image(
            painter = painterResource(id = R.drawable.ic_profile),
            contentDescription = "Profile Image",
            modifier = Modifier
                .size(36.dp)
                .clip(CircleShape)
                .border(1.dp, Color.Transparent, CircleShape),
            contentScale = ContentScale.Crop
        )
        Column(
            modifier = Modifier
                .padding(start = 12.dp)
        ) {
            Text(text = userName, fontSize = 20.sp, fontWeight = FontWeight.Bold)
            Text(text = userHandle, fontSize = 14.sp)
        }
    }
}
```


Another great example is to create a Text Label with two styles. We know that traditionally doing that is very painful.

Let’s see the Compose way of doing it.

```kotlin
Text(
            text = buildAnnotatedString {
                withStyle(style = SpanStyle(fontWeight = FontWeight.ExtraBold)) {
                    append("3")
                }
                append(" ")
                withStyle(style = SpanStyle(fontWeight = FontWeight.Normal)) {

                    append(stringResource(id = R.string.retweets))
                }
            },
            modifier = Modifier.padding(end = 8.dp)
        )

```

![](https://cdn-images-1.medium.com/max/2008/1*Sam96dWBFuNELaztMUAf0g.png)

That’s it!! I hope you’ve seen the ease of use and benefit of using Compose for building UI.

![](https://cdn-images-1.medium.com/max/2000/1*eLrryz9etGCak2M3YPi1Ww.png)

Just remember everything in Compose is rows and columns, and the order of attributes matters. You can check out my [Github repo](https://github.com/mongodb-developer/compose-tweets-android) complete example which also demonstrates the rendering of data using `viewModel`.

>If you have questions, please head to our [developer community website](https://www.mongodb.com/community/forums/) where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.

Learn how to get started with Jetpack Compose on Android

Unboxing Jetpack Compose: My First Compose App

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

<br>

## 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.

![Splash Screen placeholder](https://developer.android.com/about/versions/12/images/splash-screen-composition.png)

* 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.

```xml

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

    
    <item name="android:windowSplashScreenBackground">#FFFFFF</item>

    
    <item name="android:windowSplashScreenIconBackgroundColor">#000000</item>

    
    <item name="android:windowSplashScreenAnimatedIcon">@drawable/ic_realm_logo_250</item>

    
    <item name="android:windowSplashScreenBrandingImage">@drawable/relam_horizontal</item>
</style>
```

<br/>
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.

``` xml
<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.

<img src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_1632115543_4547ee45af.png" alt="drawing" width="200"/>

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.

```xml

<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.

``` Kotlin
 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)
```

<br/>

> **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.

1. The splash screen background supports only single colour. We're waiting for support of vector drawable backgrounds.
2. 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.
3. 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](https://github.com/mongodb-developer/SplashScreen-Android)

Hope this was informative and enjoyed reading it.

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

Building Splash Screen Natively, Android 12, Kotlin

## 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:

```kotlin
// 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:

```kotlin

// 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:

```kotlin
//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](https://developer.android.com/reference/androidx/activity/result/contract/package-summary).

---

## 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: 😄

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/giphy_f99f638e0c.webp)

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

```kotlin
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:

1. Improve the code readability, no need to remember to jump to `onActivityResult()` after `startActivityForResult`.

2. `ActivityResultLauncher` returned from `registerForActivityResult` used to launch components, clearly defining the input parameter for desired results.

3. Removed the boilerplate code for requesting permission from the user. 

Hope this was informative and enjoyed reading it.


Learn the benefits and usage of registerForActivityResult for Android in Kotlin.

StartActivityForResult is Deprecated!

> This is a follow-up article in the **[Getting Started Series](https://www.mongodb.com/developer/how-to/introduction-realm-sdk-android/)**.
> 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:

1. How to update database schema post-production release on play store.
2. 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.

```kotlin
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:

1. Update the database version.
2. Make changes to the database schema.
3. 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.

```kotlin
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`.

```kotlin
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:

```kotlin

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.

```kotlin

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.

```kotlin

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 [Realm forum](https://www.mongodb.com/community/forums/c/realm/9) or tweet
me [@codeWithMohit](http://twitter.com/codeWithMohit).

In the next article, we will discuss how to migrate the Realm database with Atlas Device Sync.

If you have an iOS app, do check out the iOS tutorial
on [Realm iOS Migration](https://www.mongodb.com/developer/how-to/realm-schema-migration/). 

In this article, we explore and learn how to make Realm SDK database schema changes. 

How to Update Realm SDK Database Schema for Android

* * *
> Atlas App Services (Formerly MongoDB Realm )
> 
> Atlas Device Sync (Formerly Realm Sync)
> 
* * *
Welcome back! We really appreciate you coming back and showing your interest in Atlas App Services. This is a follow-up article to [Introduction to Realm Java SDK for Android](/how-to/introduction-realm-sdk-android).  If you haven't read that yet, we recommend you go through it first.

This is a beginner-level article, where we introduce you to Atlas Device Sync. As always, we demonstrate its usage by building an Android app using the MVVM architecture.

> **Build better mobile apps with Atlas Device Sync**: Atlas Device Sync is a fully-managed mobile backend-as-a-service. Leverage out-of-the-box infrastructure, data synchronization capabilities, built-in network handling, and much more to quickly launch enterprise-grade mobile apps. [Get started now by build: Deploy Sample for Free](https://www.mongodb.com/realm/register?tck=devhub_devicesyncforandroid)!

## Prerequisites

>
>
>You have created at least one app using Android Studio.
>
>

## What Are We Trying to Solve?

In the [previous article](/how-to/introduction-realm-sdk-android), we learned that the [Realm Java SDK](https://docs.mongodb.com/realm/sdk/android/) is easy to use when working with a local database. But in the world of the internet we want to share our data, so how do we do that with Realm?

>
>
>**MongoDB Atlas Device Sync**
>
>Atlas Device Sync is the solution to our problem. It's one of the many features provided by [MongoDB Atlas App Services](https://docs.mongodb.com/realm/). It synchronizes the data between client-side Realms and the server-side cloud, [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), without worrying about conflict resolution and error handling.
>
>

The illustration below demonstrates how [MongoDB Atlas Device Sync](https://docs.mongodb.com/realm/) has simplified the complex architecture:

![Atlas Device Sync has simplified the complex architecture](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_sync_arch_ffbde178d5.gif)

To demonstrate how to use [Atlas Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/learn/overview/), we will extend our previous application, which tracks app views, to use Atlas Device Sync.

## Step 1: Get the Base Code

Clone the original [repo](https://github.com/mongodb-developer/get-started-realm-android-crud-app.git) and rename it "HelloDeviceSync."

## Step 2: Enable Atlas Device Sync

Update the `syncEnabled` state as shown below in the Gradle file (at the module level):

``` kotlin
android {
// few other things

  realm {
    syncEnabled = true
  }
}
```

Also, add the `buildConfigField` to `buildTypes` in the same file:

``` kotlin
buildTypes {

   debug {
      buildConfigField "String", "RealmAppId", "\"App Key\""
   }

   release {
     buildConfigField "String", "RealmAppId", "\"App Key\""
   }
}
```

You can ignore the value of `App Key` for now, as it will be covered in a later step.

## Step 3: [Set Up Your Free MongoDB Atlas Cloud Database](https://account.mongodb.com/account/login)

![MongoDB Atlas setup](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_sync_android_setup_mongodb_cloud_f4c98b67d2.gif)

Once this is done, we have a cloud database where all our mobile app data can be saved, i.e., [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). Now we are left with linking our cloud database (in Atlas) with the mobile app.

## Step 4: Create a App Services App

![MongoDB Atlas App Service app setup](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_app_setup_5257ea3e24.gif)

In layman's terms, App Services apps on MongoDB Atlas are just links between the data flowing between the mobile apps ([Realm Java SDK](https://docs.mongodb.com/realm/sdk/android/)) and Atlas.

## Step 5: Add the App Services App ID to the Android Project

Copy the  App ID and use it to replace `App Key` in the `build.gradle` file, which we added in **Step 2**.

With this done, MongoDB Atlas and your Android App are connected.

## Step 6: Enable Atlas Device Sync and Authentication

[MongoDB Atlas App Services](https://docs.mongodb.com/realm/) is a very powerful tool and has a bunch of cool features from data security to its manipulation.  This is more than sufficient for one application. Let's enable authentication and sync.

### But Why Authentication?

Device Sync is designed to make apps secure by default, by not allowing an unknown user to access data.

We don't have to force a user to sign up for them to become a known user. We can enable anonymous authentication, which is a win-win for everyone.

So let's enable both of them:

![Enabling anonymous authentication through the MongoDB Atlas UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_auth_enable_35ad60836b.gif)

![Enabling  Atlas Device Sync using the MongoDB Atlas UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_syn_enable_85e1a14d53.gif)

Let's quickly recap what we have done so far.

In the Android app:
-   Added App Services App ID to the Gradle file.
-   Enabled Atlas Device Sync.

In [MongoDB Atlas](https://docs.mongodb.com/realm/):
-   Set up account.
-   Created a free cluster for [MongoDB Atlas](https://www.mongodb.com/cloud/atlas).
-   Created a App Services app.
-   Enabled anonymous authentication.
-   Enabled sync.

Now, the final piece is to make the necessary modifications to our Android app.

## Step 7: Update the Android App Code

The only code change is to get an instance of the Realm mobile database from the App Services app instance.

1.  Get a App Services app instance from which the Realm instance can be derived:

    ``` kotlin
    val realmSync by lazy {
      App(AppConfiguration.Builder(BuildConfig.RealmAppId).build())
    }
    ```

2.  Update the creation of the View Model:

    ``` kotlin
    private val homeViewModel: HomeViewModel by navGraphViewModels(
    R.id.mobile_navigation,
    factoryProducer = {
      object : ViewModelProvider.Factory {
        @Suppress("UNCHECKED_CAST")
        override fun <T : ViewModel?> create(modelClass: Class<T>): T {
          val realmApp = (requireActivity().application as HelloRealmSyncApp).realmSync
          return HomeViewModel(realmApp) as T
        }
      }
    })
    ```

3.  Update the View Model constructor to accept the App Services app instance:

    ``` kotlin
    class HomeViewModel(private val realmApp: App) : ViewModel() {

    }
    ```

4.  Update the `updateData` method in `HomeViewModel`:

    ``` kotlin
    private fun updateData() {
      _isLoading.postValue(true)

      fun onUserSuccess(user: User) {
        val config = SyncConfiguration.Builder(user, user.id).build()

        Realm.getInstanceAsync(config, object : Realm.Callback() {
           override fun onSuccess(realm: Realm) {
               realm.executeTransactionAsync {
                   var visitInfo = it.where(VisitInfo::class.java).findFirst()
                   visitInfo = visitInfo?.updateCount() ?: VisitInfo().apply {
                       partition = user.id
                       visitCount++
                   }
                   _visitInfo.postValue(it.copyFromRealm(visitInfo))
                   it.copyToRealmOrUpdate(visitInfo)
                   _isLoading.postValue(false)
               }
           }

          override fun onError(exception: Throwable) {
            super.onError(exception)
            //TODO: Implementation pending
            _isLoading.postValue(false)
          }
        })
      }

      realmApp.loginAsync(Credentials.anonymous()) {
        if (it.isSuccess) {
          onUserSuccess(it.get())
        } else {
          _isLoading.postValue(false)
        }
      }
    }
    ```

In the above snippet, we are doing two primary things:

1.  Getting a user instance by signing in anonymously.
2.  Getting a Realm instance using `SyncConfiguration.Builder`.

``` kotlin
SyncConfiguration.Builder(user, user.id).build()
```

Where `user.id` is the partition key we defined in our Atlas Device Sync configuration (Step 6). In simple terms, partition key is an identifier that helps you to get the exact data as per client needs. For more details, please refer to the article on [Atlas Device Sync Partitioning Strategies](/how-to/realm-partitioning-strategies/).

## Step 8: View Your Results in [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)

![Viewing the results in Atlas using the MongoDB Atlas UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mongo_cluster_result_005cbea69e.gif)

Thank you for reading. You can find the complete working code in our [GitHub repo](https://github.com/mongodb-developer/get-started-realm-sync-android-app.git).

>
>
>If you have questions, please head to our [developer community website](https://community.mongodb.com/) where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.
>
>


Learn how to use Atlas Device Sync with Android.

Introduction to Atlas Device Sync for Android

This is a beginner article where we introduce you to the [Realm Android SDK](https://docs.mongodb.com/realm/sdk/android/), dive through its features, and illustrate development of the process with a demo application to get you started quickly.

In this article, you will learn how to set up an Android application with the Realm Android SDK, write basic queries to manipulate data, and you'll receive an introduction to Realm Studio, a tool designed to view the local Realm database.

>
>
>Pre-Requisites: You have created at least one app using Android Studio.
>
>

>
>
>**What is Realm?**
>
>Realm is an object database that is simple to embed in your mobile app.  Realm is a developer-friendly alternative to mobile databases such as SQLite and CoreData.
>
>

Before we start, create an Android application. Feel free to skip the step if you already have one.

**Step 0**: Open Android Studio and then select Create New Project. For more information, you can visit the official [Android website](https://developer.android.com/training/basics/firstapp/creating-project).

Now, let's get started on how to add the Realm SDK to your application.

**Step 1**: Add the gradle dependency to the **project** level **build.gradle** file:

``` kotlin
dependencies {
   classpath "com.android.tools.build:gradle:$gradle_version"
   classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
   classpath "io.realm:realm-gradle-plugin:10.4.0" // add this line
}
```

Also, add **mavenCentral** as our dependency, which was previously **jCenter** for Realm 10.3.x and below.

``` kotlin
repositories {
   google()
   mavenCentral() // add this line
}
```

``` kotlin
allprojects {
    repositories {
        google()
        mavenCentral() // add this line
    }
}
```

**Step 2**: Add the Realm plugin to the **app** level **build.gradle** file:

``` kotlin
plugins {
   id 'com.android.application'
   id 'kotlin-android'
   id 'kotlin-kapt' // add this line
   id 'realm-android' // add this line
}
```

Keep in mind that order matters. You should add the **realm-android** plugin after **kotlin-kapt**.

We have completed setting up Realm in the project. Sync Gradle so that we can move to the next step.

**Step 3**: Initialize and create our first database:

The Realm SDK needs to be initialized before use. This can be done anywhere (application class, activity, or fragment) but to keep it simple, we recommend doing it in the application class.

``` kotlin
// Ready our SDK
Realm.init(this)
// Creating our db with custom properties
val config = RealmConfiguration.Builder()
   .name("test.db")
   .schemaVersion(1)
   .build()
Realm.setDefaultConfiguration(config)
```

Now that we have the Realm SDK added to our project, let's explore basic CRUD (Create, Read, Update, Delete) operations. To do this, we'll create a small application, building on MVVM design principles.

The application counts the number of times the app has been opened, which has been manipulated to give an illustration of CRUD operation.

1.  Create app view object when opened the first time — **C** R U D
2.  Read app viewed counts—C **R** U D
3.  Update app viewed counts—C R **U** D
4.  Delete app viewed counts— C R U **D**

<figure align="center">
    <img
        style="border-radius: 10px; width: 50%"
        src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/intro-realm-android/realm-android-app.gif"
        alt="Realm Android App"
    />
</figure>

Once you have a good understanding of the basic operations, then it is fairly simple to apply this to complex data transformation as, in the end, they are nothing but collections of CRUD operations.

Before we get down to the actual task, it's nice to have background knowledge on how Realm works. Realm is built to help developers avoid common pitfalls, like heavy lifting on the main thread, and follow best practices, like reactive programming.

The default configuration of the Realm allows programmers to read data on any thread and write only on the background thread. This configuration can be overwritten with:

``` kotlin
Realm.init(this)
val config = RealmConfiguration.Builder()
   .name("test.db")
   .allowQueriesOnUiThread(false)
   .schemaVersion(1)
   .deleteRealmIfMigrationNeeded()
   .build()
Realm.setDefaultConfiguration(config)
```

In this example, we keep `allowQueriesOnUiThread(true)` which is the default configuration.

Let's get started and create our object class `VisitInfo` which holds the visit count:

``` kotlin
open class VisitInfo : RealmObject() {

   @PrimaryKey
   var id = UUID.randomUUID().toString()

   var visitCount: Int = 0

}
```

In the above snippet, you will notice that we have extended the class with `RealmObject`, which allows us to directly save the object into the Realm.

We can insert it into the Realm like this:

``` kotlin
val db = Realm.getDefaultInstance()
db.executeTransactionAsync {
   val info = VisitInfo().apply {
       visitCount = count
   }
   it.insert(info)
}
```

To read the object, we write our query as:

``` kotlin
val db = Realm.getDefaultInstance()
val visitInfo = db.where(VisitInfo::class.java).findFirst()
```

To update the object, we use:

``` kotlin
val db = Realm.getDefaultInstance()
val visitInfo = db.where(VisitInfo::class.java).findFirst()

db.beginTransaction()
visitInfo.apply {
   visitCount += count
}

db.commitTransaction()
```

And finally, to delete the object:

``` kotlin
val visitInfo = db.where(VisitInfo::class.java).findFirst()
visitInfo?.deleteFromRealm()
```

So now, you will have figured out that it's very easy to perform any operation with Realm. You can also check out the [Github repo](https://github.com/mongodb-developer/get-started-realm-android-crud-app) for the complete application.

The next logical step is how to view data in the database. For that, let's introduce [Realm Studio](https://docs.mongodb.com/realm/studio/).

*Realm Studio is a developer tool for desktop operating systems that allows you to manage Realm database instances.*

Realm Studio is a very straightforward tool that helps you view your local Realm database file. You can install Realm Studio on any platform from <https://docs.mongodb.com/realm/studio/>.

Let's grab our database file from our emulator or real device.

![Animation showing how to get the database file from emulator or real device. The process is explained in the following paragraphs.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/intro-realm-android/android-studio.gif)

Detailed steps are as follows:

**Step 1**: Go to Android Studio, open "Device File Explorer" from the right-side panel, and then select your emulator.

<figure align="center">
    <img
        style="border-radius: 10px"
        src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/intro-realm-android/android-studio-data.png"
        alt="Android Studio Data"
    />
</figure>

**Step 2**: Get the Realm file for our app. For this, open the folder named **data** as highlighted above, and then go to the **data** folder again. Next, look for the folder with your package name. Inside the **files** folder, look for the file named after the database you set up through the Realm SDK. In my case, it is **test.db**.

![Android Studio screenshot](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/intro-realm-android/realm-data.png)

**Step 3**: To export, right-click on the file and select "Save As," and
then open the file in Realm Studio.

![Realm Studio screenshot](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/intro-realm-android/realm-studio.png)

Notice the visit count in the `VisitInfo` class (AKA table) which is equivalent to the visit count of the application. That's all, folks.  Hope it helps to solve the last piece of the puzzle.

If you're an iOS developer, please check out [Accessing Realm Data on iOS Using Realm Studio](/how-to/realm-ios-database-access-using-realm-studio/).

>
>
>If you have questions, please head to our [developer community website](https://community.mongodb.com/) where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.
>
>


Learn how to use the Realm SDK with Android.

Introduction to the Realm SDK for Android


> This article is targeted to existing Realm developers who want to understand how to migrate to Realm Kotlin SDK.

## Introduction

Android has changed a lot in recent years notably after the Kotlin language became a first-class 
citizen, so does the Realm SDK. Realm has recently moved its much-awaited Kotlin SDK to beta 
enabling developers to use Realm more fluently with Kotlin and opening doors to the world of Kotlin 
Multiplatform.

Let's understand the changes required when you migrate from Java to Kotlin SDK starting from setup
till its usage.

## Changes in setup

The new Realm Kotlin SDK is based on Kotlin Multiplatform architecture which enables you to have one
common module for all your data needs for all platforms. But this doesn't mean to use the new SDK
you would have to convert your existing Android app to KMM app right away, you can do that later.

Let's understand the changes needed in the gradle file to use Realm Kotlin SDK, by comparing the
previous implementation with the new one.

In project level `build.gradle`

Earlier with Java SDK

```kotlin
    buildscript {

    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.1.3"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.31"

        // Realm Plugin 
        classpath "io.realm:realm-gradle-plugin:10.10.1"

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}
```

With Kotlin SDK, we can **delete the Realm plugin** from `dependencies`

```kotlin
    buildscript {

    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.1.3"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.31"

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}
```

In the module-level `build.gradle`

With Java SDK, we 

1. Enabled Realm Plugin
2. Enabled Sync, if applicable

```groovy

plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'kotlin-kapt'
    id 'realm-android'
}
```

```groovy
    android {

    ... ....

    realm {
        syncEnabled = true
    }
}
```

With Kotlin SDK,

1. Replace ``id 'realm-android'`` with  ``id("io.realm.kotlin") version "0.10.0"``

```groovy
    plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'kotlin-kapt'
    id("io.realm.kotlin") version "0.10.0"
}
```

2. Remove the Realm block under android tag

```groovy
    android {
    ... ....

    }
```

3. Add Realm dependency under `dependencies` tag

```groovy
    dependencies {

        implementation("io.realm.kotlin:library-sync:0.10.0")

    }
```

> If you are using only Realm local SDK, then you can add
> ```groovy
> dependencies {
>    implementation("io.realm.kotlin:library-base:0.10.0")
> }
>```

With these changes, our Android app is ready to use Kotlin SDK.

## Changes in implementation

### Realm Initialization

Traditionally before using Realm for querying information in our project, we had to initialize and
set up few basic properties like name, version with sync config for database, let's update them 
as well.

Steps with JAVA SDK :

1. Call `Realm.init()`
2. Setup Realm DB properties like name, version, migration rules etc using `RealmConfiguration`.
3. Setup logging
4. Configure Realm Sync

With Kotlin SDK :

1. <s>Call `Realm.init()`</s> _Is not needed anymore_.
2. Setup Realm DB properties like db name, version, migration rules etc. using `RealmConfiguration`-
   _This remains the same apart from a few minor changes_.
3. Setup logging - _This is moved to `RealmConfiguration`_
4. Configure Realm Sync - _No changes_

### Changes to Models

No changes are required in model classes, except you might have to remove a few currently 
unsupported annotations like `@RealmClass` which is used for the embedded object.

> Note: You can remove `Open` keyword against `class` which was mandatory for using Java SDK in
> Kotlin.

### Changes to querying

The most exciting part starts from here 😎(IMO).

Traditionally Realm SDK has been on the top of the latest programming trends like Reactive
programming (Rx), LiveData and many more but with the technological shift in Android programming
language from Java to Kotlin, developers were not able to fully utilize the power of the language 
with Realm as underlying SDK was still in Java, few of the notable were support for the Coroutines, 
Kotlin Flow, etc.

But with the Kotlin SDK that all has changed and further led to the reduction of boiler code. 
Let's understand these by examples.

Example 1: As a user, I would like to register my visit as soon as I open the app or screen.

Steps to complete this operation would be

1. Authenticate with Realm SDK.
2. Based on the user information, create a sync config with the partition key.
3. Open Realm instance.
4. Start a Realm Transaction.
5. Query for current user visit count and based on that add/update count.

With JAVA SDK:

```kotlin
private fun updateData() {
    _isLoading.postValue(true)

    fun onUserSuccess(user: User) {
        val config = SyncConfiguration.Builder(user, user.id).build()

        Realm.getInstanceAsync(config, object : Realm.Callback() {
            override fun onSuccess(realm: Realm) {
                realm.executeTransactionAsync {
                    var visitInfo = it.where(VisitInfo::class.java).findFirst()
                    visitInfo = visitInfo?.updateCount() ?: VisitInfo().apply {
                        partition = user.id
                    }.updateCount()

                    it.copyToRealmOrUpdate(visitInfo).apply {
                        _visitInfo.postValue(it.copyFromRealm(this))
                    }
                    _isLoading.postValue(false)
                }
            }

            override fun onError(exception: Throwable) {
                super.onError(exception)
                // some error handling 
                _isLoading.postValue(false)
            }
        })
    }

    realmApp.loginAsync(Credentials.anonymous()) {
        if (it.isSuccess) {
            onUserSuccess(it.get())
        } else {
            _isLoading.postValue(false)
        }
    }
}
```

With Kotlin SDK:

```kotlin
private fun updateData() {
    viewModelScope.launch(Dispatchers.IO) {
        _isLoading.postValue(true)
        val user = realmApp.login(Credentials.anonymous())
        val config = SyncConfiguration.Builder(
            user = user,
            partitionValue = user.identity,
            schema = setOf(VisitInfo::class)
        ).build()

        val realm = Realm.open(configuration = config)
        realm.write {
            val visitInfo = this.query<VisitInfo>().first().find()
            copyToRealm(visitInfo?.updateCount()
                ?: VisitInfo().apply {
                    partition = user.identity
                    visitCount = 1
                })
        }
        _isLoading.postValue(false)
    }
}
```

Upon quick comparing, you would notice that lines of code have decreased by 30%, and we are using
coroutines for doing the async call, which is the natural way of doing asynchronous programming in
Kotlin. Let's check this with one more example.

Example 2: As user, I should be notified immediately about any change in user visit info. This is
more like observing the change to visit count.

With Java SDK:

```kotlin
 fun onRefreshCount() {
    _isLoading.postValue(true)

    fun getUpdatedCount(realm: Realm) {
        val visitInfo = realm.where(VisitInfo::class.java).findFirst()
        visitInfo?.let {
            _visitInfo.value = it
            _isLoading.postValue(false)
        }
    }

    fun onUserSuccess(user: User) {
        val config = SyncConfiguration.Builder(user, user.id).build()

        Realm.getInstanceAsync(config, object : Realm.Callback() {
            override fun onSuccess(realm: Realm) {
                getUpdatedCount(realm)
            }

            override fun onError(exception: Throwable) {
                super.onError(exception)
                //TODO: Implementation pending
                _isLoading.postValue(false)
            }
        })
    }

    realmApp.loginAsync(Credentials.anonymous()) {
        if (it.isSuccess) {
            onUserSuccess(it.get())
        } else {
            _isLoading.postValue(false)
        }
    }
}
```

With Kotlin SDK :

```kotlin

fun onRefreshCount(): Flow<VisitInfo?> {

    val user = runBlocking { realmApp.login(Credentials.anonymous()) }
    val config = SyncConfiguration.Builder(
        user = user,
        partitionValue = user.identity,
        schema = setOf(VisitInfo::class)
    ).build()

    val realm = Realm.open(config)
    return realm.query<VisitInfo>().first().asFlow()
}

```

Again upon quick comparing you would notice that lines of code have decreased drastically, by more
than **60%**, and apart coroutines for doing async call, we are using _Kotlin Flow_ to observe the
value changes.

With this, as mentioned earlier, we are further able to reduce our boilerplate code,
no [callback hell](http://callbackhell.com) and writing code is more natural now.

## Other major changes

Apart from Realm Kotlin SDK being written in Kotlin language, it is fundamentally little different 
from the JAVA SDK in a few ways:

- **Frozen by default**: All objects are now frozen. Unlike live objects, frozen objects do not
  automatically update after the database writes. You can still access live objects within a write
  transaction, but passing a live object out of a write transaction freezes the object.
- **Thread-safety**: All realm instances, objects, query results, and collections can now be
  transferred across threads.
- **Singleton**: You now only need one instance of each realm.

## Should you migrate now?

There is no straight answer to question, it really depends on usage, complexity of the app and time.
But I think so this the perfect time to evaluate the efforts and changes required to migrate as 
Realm Kotlin SDK would be the future.


This article is targeted to existing Realm developers who want to understand how to migrate to Realm Kotlin SDK.

How to migrate from Realm Java SDK to Realm Kotlin SDK

> 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.

```shell 
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.

![KMM Template](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/multiplatform_mobile_project_wizard_1_8a88adc42c.png)

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

![Enter Project Name](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_08_at_20_50_55_f2ffda28f8.png)

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

![Select Dependency Manager](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/multiplatform_mobile_project_wizard_3_cbf2318af4.png)

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

![iOS app run](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_08_at_21_04_35_01d50b1923.png)

![android app run](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_08_at_21_04_47_abe8543547.png)

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

<img src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/first_multiplatform_project_on_android_1_e53c9f0ee4.png"  width=40%> <img 
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.

![Project structure](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_09_at_06_11_29_53ad58ddc1.png)

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:

```Kotlin 

expect fun getPlatform(): String

```

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

```kotlin
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`.

![shared folder split](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_09_at_09_46_57_237bd899da.png)

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](https://github.com/mongodb-developer/Conference-Queries-App), 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:

1. [JetPack Compose](https://developer.android.com/jetpack/compose) for UI building.
2. [Kotlin Multiplatform](https://kotlinlang.org/lp/mobile/) with Realm as a middle layer.
3. [Atlas Flexible Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/) from MongoDB,
   serverless backend supporting our data sharing.
4. [MongoDB Atlas](https://www.mongodb.com/atlas/database), our cloud database.

<img src="https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_20230109_134623_6ea6a87eec.png"  width=50%>

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`.

```kotlin

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())
    }
}


```

```kotlin
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.

```kotlin
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

```kotlin
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)
}
```

To

```kotlin
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

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

To

```kotlin
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

   ```kotlin
 sourceSets {
    val commonMain by getting {
        dependencies {

        }
    }
    // Other config
}
   ```

To

   ```kotlin
 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.

   ```kotlin
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.

```kotlin
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.

```kotlin
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.

```kotlin

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:

1. Create a [free MongoDB account](https://account.mongodb.com/account/login).
2. Follow the setup wizard after signing up to [create a free cluster](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/).
3. Create an [App with App Service UI](https://www.mongodb.com/docs/atlas/app-services/manage-apps/create/create-with-ui/) to enable Atlas Device Sync.
4. Enable Atlas Device Sync using Flexible Sync. Select the App services tab and enable sync, as shown below. 
   ![Device Sync](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Enable_Sync_ebd2f2ae37.gif)

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:

```kotlin

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

```kotlin
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)
}
```

```kotlin
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.

```kotlin
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.

![Atlas UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_01_10_at_09_17_27_2a1a38dece.png)

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

![Sync](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ezgif_com_gif_maker_0eb33085b5.gif)

## 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](https://github.com/mongodb-developer/Conference-Queries-App).

If you have any queries or comments, you can share them on
the [MongoDB Realm forum](https://www.mongodb.com/community/forums/c/realm/9) or tweet me [@codeWithMohit](http://twitter.com/codeWithMohit).

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

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


> This is an introduction article on how to build a RESTful application in Kotlin using [Spring Boot 3](https://spring.io/) and [MongoDB Atlas](https://www.mongodb.com/atlas/database).

## 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](https://en.wikipedia.org/wiki/Database_schema).

## Prerequisites

This is a getting-started article, so nothing much is needed as a prerequisite. But familiarity with [Kotlin](https://kotlinlang.org/) as a programming language, plus a basic understanding of [Rest API](https://en.wikipedia.org/wiki/Representational_state_transfer) and [HTTP methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol), would be helpful.

To help with development activities, we will be using [Jetbrains IntelliJ IDEA (Community Edition)](https://www.jetbrains.com/idea/download/).

## 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](https://start.spring.io/) 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.

![Spring initializer](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Spring_initializr_dbbfd7e79a.png)

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.

![Spring dependency](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Spring_Depdendency_bb8866de1c.png)

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

![Spring project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Spring_With_Dependency_4137b2515f.png)

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.

![Sample Project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Default_App_c843cf2216.png)

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.

```kotlin
@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.

```kotlin
@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.

![Run icon image](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Run_icon_image_bdb6c52ca8.png)

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

![Hello World Output](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Hello_World_output_279aed0e43.png)

And on cross-validating this from [Postman](https://www.postman.com), we can clearly understand that our `Get` API is working perfectly.  
![Hello World Output](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Postman_output_216cb86538.png)

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](https://spring.io/projects/spring-boot#overview), 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:

1. `@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`.

2. `@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](https://www.mongodb.com/atlas/database), 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](https://www.youtube.com/watch?v=RGfFpQF0NpE&list=PL4RCxklHWZ9v2lcat4oEVGQhZg6r4IQGV) 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](https://www.mongodb.com/docs/guides/atlas/connection-string/) that can be added
as a `spring.data.mongodb.uri` property in `application.properties` file. The connection string can be found as shown below.

![DB URL](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/find_Connect_Stream_URL_e7a6c2257a.gif)

The format for the connection string is:

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

![Connection URL](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Connect_Mongo_DB_Atlas_19305672d4.png)

## 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](https://www.mongodb.com/developer/products/atlas/atlas-sample-datasets/) on Atlas as shown below:

![sample_db](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/load_sample_dataset_95ce8126e0.png)

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.

![model](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/model_from_compass_20b916a09a.png)

```kotlin

@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.

```kotlin
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. 

```kotlin
@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`.

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

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

![model](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Read_72aa6d89de.png)

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.

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

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

And again, we will be using [Postman](https://www.postman.com/) to validate the output against a random `restaurantId` from the sample dataset.

![ready-id](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Read_By_Id_d1752a108b.png)

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

![ready-null](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Read_Null_637f97f167.png)

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.

```kotlin
    @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()
}
```

![ready-404](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Notfound_404_522b7f60ac.png)

### 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.

```kotlin
    @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.

```kotlin
    @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](https://www.mongodb.com/docs/drivers/), 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.

```kotlin
    @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](https://github.com/mongodb-developer/mongodb-springboot3-kotlin).

If you have any queries or comments, you can share them on the [MongoDB forum](https://www.mongodb.com/community/forums/) or tweet me [@codeWithMohit](https://twitter.com/codeWithMohit).

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

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

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

> In this article, you'll learn how to use [MongoDB Atlas](https://www.mongodb.com/atlas/database), a cloud database, when you're getting started with [Azure functions](https://learn.microsoft.com/en-us/azure/azure-functions/functions-overview)  in Java.

## Prerequisites

1. A [Microsoft Azure](https://azure.microsoft.com/en-us) 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.
2. A [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) account, which is a cloud-based document database. You can sign up for an account for free. 
3. [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/)  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.
4. An [Azure supported Java Development Kit (JDK)](https://learn.microsoft.com/en-us/azure/developer/java/fundamentals/java-support-on-azure) for Java, version 8 or 11.
5. A basic understanding of the 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

The Azure plugin can be installed on IntelliJ in a very standard manner using the IntelliJ plugin manager. Open Plugins and then search for "_[Azure Toolkit for IntelliJ](https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij)_" in the Marketplace. Click Install.

![IntelliJ Plugin](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/marketplace_ecdaa3a97e.png)

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

### First Azure function

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

![New Project Wizard](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Auzre_Function_Create_new_Project_2_7149cbb6b5.png)

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

![New Project Wizard Azure function](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Auzre_Function_Create_new_Project_2_de20e0e545.png)

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

![New Project Wizard Create](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Auzre_Function_Create_new_Project_3_c997b16796.png)

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

![Project structure](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Project_Structure_8b2e29a477.png)

### Deploying and 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.

![Hello World output console](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_function_Runing_output_773708fed1.png)

Copy the URL shown in the console log and open it in the browser to run the Azure function.

![Hello World output error](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_Function_Hello_Output_2_ece7024552.png)

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

```java
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();
}
```

Update the URL by appending the query parameter `name` to
`http://localhost:XXXXX/api/HttpExample?name=World`, which will print the desired result.

![Hello World output](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_function_Hello_World_output_3_9fb2d86cb0.png)

To learn more, you can also follow the [official guide](https://learn.microsoft.com/en-us/azure/azure-functions/functions-create-maven-intellij).

## Connecting the 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 will 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 the serverless function, let's use a database that is also on the cloud and has the ability to scale up and down as needed. We'll be using [MongoDB Atlas](https://www.mongodb.com/atlas/database), which is a document-based cloud database.

### Setting up an Atlas account

Creating an [Atlas account](https://www.mongodb.com/cloud/atlas/register) is very straightforward, free forever, and perfect to validate any MVP project idea, but if you need a guide, you can follow [the documentation](https://www.mongodb.com/docs/atlas/getting-started/).

### Adding the Azure function IP address in Atlas Network Config

The Azure function uses multiple IP addresses instead of a single address, so let's add them to Atlas. To get the range of IP addresses, open your [Azure account](https://azure.microsoft.com/en-us/free/) and search networking inside your Azure virtual machine. Copy the outbound addresses from outbound traffic.

One of the steps while creating an account with [Atlas](https://www.mongodb.com/atlas/database) 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 will get all the connection requests from the Azure function, so let's add this address.

![Azure IP address](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Auzre_IP_addres_cf5a3f9897.png)

Add these to the IP individually under Network Access. 

![MongoDB IP Allow List](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Whitelist_IP_address_900cd90939.png)

### 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 is to use [MongoDB Java driver](https://www.mongodb.com/docs/drivers/java-drivers/). So, let's add the dependency for the driver in the `build.gradle` file.

```groovy
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 the prerequisites done, let's build our first real-world function using the [MongoDB sample dataset](https://www.mongodb.com/docs/atlas/sample-data/) for movies. In this project, we'll build two functions: One returns the count of the
total movies in the collection, and the other returns the movie document based on the year of release.

Let's generate the boilerplate code for the function by right-clicking on the package name and then selecting New > Azure function class. We'll call this function class `Movies`.

```java
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's:

1. Update `@FunctionName` parameter from `Movies` to `getMoviesCount`.
2. Rename the function name from `run` to `getMoviesCount`.
3. Remove the `query` and `name` variables, as we don't have any query parameters.

Our updated code looks like this.

```java
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();
    }
}
```

To connect with MongoDB Atlas using the Java driver, we first need a connection string that can be found when we press to connect to our cluster on our [Atlas account](https://account.mongodb.com/account/login?_ga=2.197766374.89042088.1678230173-713092659.1675961706). For details, you can also refer to the [documentation](https://www.mongodb.com/docs/guides/atlas/connection-string/).

![Screenshot connection URL](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Connection_URI_fd9907e2bd.png)

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

```java
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.

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

Updated code for `getMoviesCount` function looks like this.

```java
@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. We'll use [Postman](https://www.postman.com/).

![local deployment](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_function_get_Movie_Count_Build_ce2554944c.png)

Copy the URL from the console output and paste it on Postman to validate the output.

![local postman output](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Auzre_function_Get_Movie_Postman_fa39cbf603.png)

Let's deploy this on the Azure cloud on a `Linux` machine. Click on `Azure Explore` and select Functions App to create a virtual machine (VM).

![Azure explore](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Cloud_deploy_1_4bc140b0a5.png)

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

![create new VM](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deploy_2_d51c469b0f.png)

Change the platform to `Linux` with `Java 1.8`.

![create vm with linux](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deply_3_c60bba1b7c.png)

> 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.
> ```java 
> System.setProperty("java.naming.provider.url", "dns://8.8.8.8"); 
> ```


After a few minutes, you'll notice the VM we just created under `Function App`. Now, we can deploy our app onto it.

![vm deploy](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deploy_4_9a01d01ac1.png)

Press Run to deploy it.

![vm deploy](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deploy_5_5e4417c283.png)

Once deployment is successful, you'll find the `URL` of the serverless function.

![cloud deployment success](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deploy_6_153e7c5ba4.png)

Again, we'll copy this `URL` and validate using Postman.

![cloud postman validation](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/cloud_deploy_7_408716b6a0.png)

With this, we have successfully connected our first function with
[MongoDB Atlas](https://www.mongodb.com/atlas/database). Now, let's take it to next level. We'll create another function that returns a movie document based on the year of release. 

Let's add the boilerplate code again.

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

}
```

To capture the user input year that will be used to query and gather information from the collection, add this code in:

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

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

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

The updated code is:

```java
@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 let's validate this against Postman. 

![get movies by year output](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_2023_03_07_at_22_54_16_81d42caa18.png)

The last step in making our app production-ready is to secure the connection `URI`, as it contains credentials and should be kept private.  One way of securing it is storing it into an environment variable. 

Adding an environment variable in the Azure function can be done via the Azure portal and Azure IntelliJ plugin, as well. For now, we'll use the Azure IntelliJ plugin, so go ahead and open Azure Explore in IntelliJ. 

![Azure Explore](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_Explore_1_c80c9dadc0.png)

Then, we select `Function App` and right-click `Show Properties`.

![Azure Explore VM property](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_Explore_2_231c7f95b8.png)

This will open a tab with all existing properties. We add our property into it.   

![Azure Explore](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Azure_Explore_3_c6fe2182b9.png)

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

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

```java
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](https://github.com/mongodb-developer/starter-azure-function-mongodb).

If you're looking for something similar using the Node.js runtime, check out the other [tutorial](https://techcommunity.microsoft.com/t5/apps-on-azure-blog/getting-started-with-mongodb-atlas-and-azure-functions-using/ba-p/3662099) on the subject.

With MongoDB Atlas on Microsoft Azure, developers receive access to the most comprehensive, secure, scalable, and cloud–based developer data platform on 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](https://www.mongodb.com/community/forums/) or tweet me [@codeWithMohit](https://twitter.com/codeWithMohit).

In this article, you'll learn how to use MongoDB Atlas, a cloud database, when you're getting started with Azure functions in Java.