Skip to content

Commit

Permalink
GA readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
@cmelchior
cmelchior committed Jun 7, 2022
1 parent f2a92da commit 0198f3a
Showing 1 changed file with 32 additions and 53 deletions.
85 changes: 32 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,59 +5,36 @@
[![Kotlin](https://img.shields.io/badge/kotlin-1.6.10-blue.svg?logo=kotlin)](http://kotlinlang.org)
[![License](https://img.shields.io/badge/License-Apache-blue.svg)](https://github.com/realm/realm-kotlin/blob/master/LICENSE)

Realm is a mobile database that runs directly inside phones, tablets or wearables.
This repository holds the source code for the Kotlin SDK for Realm, which runs on Kotlin Multiplatform and Android.

# Beta Notice

The Realm Kotlin SDK is in Beta for local database support, with [Device Sync API's](https://www.mongodb.com/atlas/app-services/device-sync)in Alpha.
Realm is a mobile database that runs directly inside phones, tablets or wearables. It allows synchronization of data between devices using [Atlas App Services](https://www.mongodb.com/docs/atlas/app-services/introduction/) and [Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/learn/overview/#atlas-device-sync-overview).

This repository holds the source code for the Kotlin SDK for Realm, which runs on Kotlin Multiplatform and Android.

# Resources

* 🧬 Samples: https://github.com/realm/realm-kotlin-samples
* 📘 Documentation: https://docs.mongodb.com/realm/sdk/kotlin-multiplatform/
# General Availability

The Realm Kotlin SDK is GA.

# Multiplatform Quick Start
Documentation can be found [here](https://docs.mongodb.com/realm/sdk/kotlin-multiplatform/).

## Prerequisite
Sample projects can be found [here](https://github.com/realm/realm-kotlin-samples).

Start a new [KMM](https://kotlinlang.org/docs/mobile/create-first-app.html) project.
If you are upgrading from a previous beta release of Realm Kotlin, please see the [CHANGELOG](CHANGELOG.md) for the full list of changes.

## Setup
If you are migrating from [Realm Java](https://github.com/realm/realm-java), please see the [Migration Guide](https://www.mongodb.com/docs/realm/sdk/kotlin/migrate-from-java-sdk-to-kotlin-sdk/).

*See [Config.kt](buildSrc/src/main/kotlin/Config.kt#L2txt) or the [realm-kotlin releases](https://github.com/realm/realm-kotlin/releases) for the latest version number.*

- In the shared module (`shared/build.gradle.kts`), apply the `io.realm.kotlin` plugin and specify the dependency in the common source set.
# Usage

```Gradle
plugins {
kotlin("multiplatform")
id("com.android.library")
id("io.realm.kotlin") version "<VERSION>"
}
## Installation

kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("io.realm.kotlin:library-base:<VERSION>")
}
}
}
```
Installation differs slightly depending on the type of project and whether or not you are using Device Sync. See the details in the documentation:

- If you use the model classes or query results inside the Android module(`androidApp/build.gradle.kts`) you need to add a compile time dependency as follows:
* [Android](https://www.mongodb.com/docs/realm/sdk/kotlin/install/android/#installation)
* [Kotlin Multiplatform](https://www.mongodb.com/docs/realm/sdk/kotlin/install/kotlin-multiplatform/#installation)

```Gradle
dependencies {
compileOnly("io.realm.kotlin:library-base:<VERSION>")
}
```
## Define model

Start writing your shared database logic in the shared module by defining first your model
Start writing your database logic by first defining your model.

```Kotlin
class Person : RealmObject {
Expand All @@ -76,13 +53,14 @@ class Dog : RealmObject {
Define a _RealmConfiguration_ with the database schema, then open the Realm using it.

```Kotlin
val configuration = RealmConfiguration.with(schema = setOf(Person::class, Dog::class)) // use the RealmConfiguration.Builder for more options
// use the RealmConfiguration.Builder() for more options
val configuration = RealmConfiguration.create(schema = setOf(Person::class, Dog::class))
val realm = Realm.open(configuration)
```

## Write

Persist some data by instantiating the data objects and copying it into the open Realm instance
Persist some data by instantiating the model object and copying it into the open Realm instance.

```Kotlin
// plain old kotlin object
Expand All @@ -91,14 +69,14 @@ val person = Person().apply {
dog = Dog().apply { name = "Fido"; age = 16 }
}

// persist it in a transaction
// Persist it in a transaction
realm.writeBlocking { // this : MutableRealm
val managedPerson = this.copyToRealm(person)
val managedPerson = copyToRealm(person)
}

// asynchronous updates with Kotlin coroutines
// Asynchronous updates with Kotlin coroutines
CoroutineScope(context).async {
realm.write {
realm.write { // this : MutableRealm
val managedPerson = copyToRealm(person)
}
}
Expand All @@ -115,13 +93,13 @@ import io.realm.kotlin.ext.query
val all = realm.query<Person>().find()

// Persons named 'Carlo'
val personsByNameQuery = realm.query<Person>("name = $0", "Carlo")
val filteredByName = personsByNameQuery.find()
val personsByNameQuery: RealmQuery<Person> = realm.query<Person>("name = $0", "Carlo")
val filteredByName: RealmResults<Person> = personsByNameQuery.find()

// Person having a dog aged more than 7 with a name starting with 'Fi'
val filteredByDog = realm.query<Person>("dog.age > $0 AND dog.name BEGINSWITH $1", 7, "Fi").find()

// Observing for changes with Coroutine Flows
// Observing changes with Coroutine Flows
CoroutineScope(context).async {
personsByNameQuery.asFlow().collect { result: ResultsChange<Person> ->
println("Realm updated: Number of persons is ${result.list.size}")
Expand All @@ -146,15 +124,16 @@ realm.query<Person>("dog == NULL LIMIT(1)")

## Delete

Use the result of a query to delete from the database
Use the result of a query to delete from the database.

```Kotlin
// delete all Dogs
realm.writeBlocking {
// Selected by a query
val query = this.query<Dog>()
delete(query)

// From a results
// From a query result
val results = query.find()
delete(results)

Expand Down Expand Up @@ -214,7 +193,7 @@ person.addresses.asFlow()

### RealmQuery

Query results are also observable, and like `RealmList` on each update the inserted, changed and deleted indices are also provided.
Query results are also observable, and like `RealmList` on each update, the inserted, changed and deleted indices are also provided.

```Kotlin
realm.query<Person>().asFlow()
Expand Down Expand Up @@ -289,7 +268,7 @@ apply plugin: "io.realm.kotlin"
See [Config.kt](buildSrc/src/main/kotlin/Config.kt#L2txt) for the latest version number.


## Kotlin Memory Model and Coroutine compatibility
# Kotlin Memory Model and Coroutine compatibility

Realm Kotlin is implemented against Kotlin's default memory model (the old one), but still supports running with the new memory model if enabled in the consuming project. See https://github.com/JetBrains/kotlin/blob/master/kotlin-native/NEW_MM.md#switch-to-the-new-mm for details on enabled the new memory model.

Expand All @@ -303,19 +282,19 @@ kotlin.native.binary.freezing=disabled
See https://github.com/JetBrains/kotlin/blob/master/kotlin-native/NEW_MM.md#unexpected-object-freezing for more details.


## Contributing
# Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for more details!


## Code of Conduct
# Code of Conduct

This project adheres to the [MongoDB Code of Conduct](https://www.mongodb.com/community-code-of-conduct).
By participating, you are expected to uphold this code. Please report
unacceptable behavior to [[email protected]](mailto:[email protected]).


## License
# License

Realm Kotlin is published under the [Apache 2.0 license](LICENSE).

Expand Down

0 comments on commit 0198f3a

Please sign in to comment.