Quick Start with Sync - Java SDK
On this page
This guide can help you get started with an Android application that communicates with a backend Realm app over the network using features like Sync, Realm Functions, and user management. If your application only requires local Realm Database functionality, you should follow the Quick Start (Local-only) guide.
This page contains information to quickly get Realm Database integrated into your app. Before you begin, ensure you have:
This page contains only the essential information that you need to set up a MongoDB Realm application. If you prefer to follow a guided tutorial that shows you step-by-step how to set up a working app, check out the Java Tutorial where you'll build a mobile app that connects to the Task Tracker backend.
Initialize Realm
Before you can use Realm in your app, you must initialize the Realm library. Your application should initialize Realm just once each time the application runs.
To initialize the Realm library, provide an Android
context
to the Realm.init()
static function. You can provide
an Activity, Fragment, or Application context
for initialization with no
difference in behavior. You can initialize the Realm library
in the onCreate()
method of an application subclass to
ensure that you only initialize Realm once each time the
application runs.
If you create your own Application
subclass, you must add it to your
application's AndroidManifest.xml
to execute your custom
application code. Set the android.name
property of your manifest's
application definition to ensure that Android instantiates your Application
subclass before any other class when a user launches your application.
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.mongodb.example"> <application android:name=".MyApplicationSubclass" ... /> </manifest>
Initialize the App
To use MongoDB Realm features such as authentication and sync, you must access your Realm app using your Realm app ID. You can find your Realm app ID in the Realm UI.
If Android Studio does not recognize the Realm
, App
, or
AppConfiguration
types, there could be a problem with the
your Gradle build configuration. To fix the issue:
- Clean your project with
Build > Clean Project
- Rebuild your project based on your updated
build.gradle
file withBuild > Rebuild Project
- Revisit the Install the Java SDK guide to make sure that you installed the dependencies correctly.
Define Your Object Model
Your application's data model defines the structure of data stored within Realm Database and synchronized to and from MongoDB Realm. You can define your application's data model in two ways:
- Via schemas in MongoDB Realm.
- Via Kotlin or Java classes in your application code with Realm Object Models.
This quick start uses the latter approach, which defines your schema using classes in your mobile application code. To define your Realm app's object model in this way, you need to enable Development Mode.
Once you've enabled Development Mode, add the following class definitions to your application code:
See Configure Your Data Model for more information on Realm Schema, object models, and Developer Mode.
Authenticate a User
When you have enabled anonymous authentication in the Realm UI, users can immediately log into your app without providing any identifying information:
Realm provides many additional ways to authenticate, register, and link users.
Open a Realm
Once you have enabled Realm Sync and authenticated a
user, you can open a synced realm. Use the
SyncConfiguration
to control the specifics of how your application
synchronizes data with MongoDB Realm, including the partition, how long to wait before a request times out, whether
to allow synchronous reads or writes to a realm on the UI thread,
and more.
Create, Read, Update, and Delete Objects
Once you have opened a realm, you can modify the objects within that realm in a write transaction block.
By default, you can only read or write to a realm in your
application's UI thread using
asynchronous transactions. That is,
you can only use Realm
methods whose name ends with the word
Async
in the main thread of your Android application unless you
explicitly allow the use of synchronous methods.
This restriction exists for the benefit of your application users:
performing read and write operations on the UI thread can lead to
unresponsive or slow UI interactions, so it's usually best to handle
these operations either asynchronously or in a background thread.
However, if your application requires the use of synchronous
realm reads or writes on the UI thread, you can explicitly allow
the use of synchronous methods with the following
SyncConfiguration
options:
To create a new Task
, instantiate an instance of the
Task
class and add it to the realm in a write block:
You can retrieve a live collection of all items in the realm:
You can also filter that collection using a filter:
To modify a task, update its properties in a write transaction block:
Finally, you can delete a task by calling the deleteFromRealm()
method in a write transaction block:
Watch for Changes
You can watch a realm, collection, or object for changes by attaching a custom
OrderedRealmCollectionChangeListener
with the addChangeListener()
method:
Log Out
Once logged in, you can log out:
Complete Example
Run the complete example by replacing the appId with your realm app ID.
If you're running this project in a fresh Android Studio project, you can
copy and paste this file into your application's MainActivity
-- just
remember to:
- change the package declaration so it matches your project
- replace the App ID placeholder with your Realm app's App ID
- update the
import
statements forTask
andTaskStatus
if you're using java
Output
Running the above code should produce output resembling the following:
Successfully authenticated anonymously. Updated range: 0 to 1 Deleted range: 0 to 1 Successfully logged out.