Docs Menu
Docs Home
/ /
Atlas Device SDKs
/

Asynchronous API - Java SDK

On this page

  • Asynchronous Calls
  • Realm.Callback
  • App.Callback
  • RealmAsyncTask
  • RealmResults
  • RealmResultTask
  • Coroutines

The Java SDK lets you access network and disk resources in two ways: synchronously and asynchronously. While synchronous, or "sync", requests block execution until the request returns success or failure, asynchronous, or "async", requests assign a callback and proceed execution to the next line of code. When the request returns, the callback runs to process results. In the callback, you can check if the request executed successfully and either access the returned results or the returned error.

Asynchronous API requests in the SDK end with the suffix "Async". There are several different ways an asynchronous request can behave, depending on which part of the SDK you're using.

Asynchronous calls to open a realm, both with and without Sync, use a final parameter of type Realm.Callback. To retrieve returned values after the request completes, implement the onSuccess() method in the callback object passed as the final parameter to these asynchronous methods. You should also implement the onError() method to handle request failures, but it is not required.

When you query Atlas App Services like Functions and user authentication, asynchronous calls accept a final parameter of type App.Callback. You can handle this callback with a lambda function that accepts a single parameter of type App.Result. To retrieve a returned values from App.Callback requests:

  1. Use the isSuccess() method of the App.Result passed to the callback function to determine if the query completed successfully.

  2. If the query was successful, use the get() method to retrieve the result of the query. If the query failed, use getError() to retrieve the exception that caused the query to fail.

Asynchronous calls to execute transactions on a realm return an instance of RealmAsyncTask. You can optionally specify an error handler or a success notification for RealmAsyncTask by passing additional parameters to the asynchronous call. Additionally, you use the cancel() method to stop a transaction from completing. The lambda function passed to a RealmAsyncTask contains the write operations to include in the transaction.

Asynchronous reads from a realm using findAllAsync() immediately return an empty RealmResults instance. The SDK executes the query on a background thread and populates the RealmResults instance with the results when the query completes. You can register a listener with addChangeListener() to receive a notification when the query completes.

Asynchronous queries to Atlas return an instance of RealmResultTask. You can cancel RealmResultTask instances just like RealmAsyncTask. To access the values returned by your query, you can use:

The SDK provides a set of Kotlin extensions to request asynchronously using coroutines and flows instead of callbacks. You can use these extensions to execute transactions, watch for changes, read, and write.

// open a realm asynchronously
Realm.getInstanceAsync(config, object : Realm.Callback() {
override fun onSuccess(realm: Realm) {
Log.v("EXAMPLE", "Successfully fetched realm instance")
CoroutineScope(Dispatchers.Main).launch {
// asynchronous transaction
realm.executeTransactionAwait(Dispatchers.IO) { transactionRealm: Realm ->
if (isActive) {
val item = transactionRealm.createObject<Item>()
}
}
}
// asynchronous query
val items: Flow<RealmResults<Item>> = realm.where<Item>().findAllAsync().toFlow()
}
fun onError(e: Exception) {
Log.e("EXAMPLE", "Failed to get realm instance: $e")
}
})

Tip

Kotlin Flows use Frozen Objects Across Multiple Threads

The toFlow() extension method passes frozen Realm objects to safely communicate between threads.

Tip

See also:

The SDK also includes Kotlin extensions that make specifying type parameters for Realm reads and writes easier.

← 
 →