Docs Menu

Quick Start with Sync - Java SDK

On this page

  • Initialize Realm
  • Initialize the App
  • Define Your Object Model
  • Authenticate a User
  • Open a Realm
  • Create, Read, Update, and Delete Objects
  • Watch for Changes
  • Log Out
  • Complete Example
  • Output
Tip
This Guide uses Device Sync

This guide helps you get started with an Android application that communicates with an App backend. The App provides features like Sync, Realm Functions, and user management. If your application requires only local database functionality, check out the Quick Start (Local-only) guide.

This page contains information to quickly get App Services integrated into your app. Before you begin, ensure you have:

Tip
Check Out the Tutorial

This page contains the essential information to interact with an App. 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.

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.

Tip
Register Your Application Subclass in the Android Manifest

If you create your own Application subclass, you must add it to your application's AndroidManifest.xml to execute your custom application logic. 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.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.mongodb.example">
<application
android:name=".MyApplicationSubclass"
...
/>
</manifest>

To use App Services features such as authentication and sync, you must access your App using your App ID. You can find your App ID in the App Services UI.

Note
Android Studio Errors?

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 with Build > Rebuild Project
  • Revisit the Install the Java SDK guide to make sure that you installed the dependencies correctly.

Your application's data model defines the structure of data stored within Realm Database and synchronized to and from App Services. You can define your application's data model in two ways:

This quick start uses the latter approach, which defines your schema using classes in your mobile application code. To define your 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:

Tip
See also:

See Configure Your Data Model for more information on Realm Schema, object models, and Developer Mode.

When you have enabled anonymous authentication in the App Services UI, users can immediately log into your app without providing any identifying information:

Realm provides many additional ways to authenticate, register, and link users.

Tip

Once you have enabled Sync and authenticated a user, you can open a synced realm. Use SyncConfiguration to control the specifics of how your application synchronizes data with App Services, including timeouts, synchronous reads and writes on the UI thread, and more.

Tip
See also:

Once you have opened a realm, you can modify the objects within that realm in a write transaction block.

Important
Synchronous Reads and Writes on the UI Thread

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:

You can watch a realm, collection, or object for changes by attaching a custom OrderedRealmCollectionChangeListener with the addChangeListener() method:

Important
Serverless Limitations

You cannot watch for changes if the data source is an Atlas serverless instance. MongoDB serverless currently does not support change streams, which are used on watched collections to listen for changes.

Once logged in, you can log out:

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 App's App ID
  • update the import statements for Task and TaskStatus if you're using Java

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.
←  Quick Start - Java SDKQuick Start with LiveData - Java SDK →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.