Package io.realm

Class Realm.Callback

  • Enclosing class:
    Realm
    public abstract static class Realm.Callback
extends io.realm.BaseRealm.InstanceCallback<Realm>
    The Callback used when reporting back the result of loading a Realm asynchronously using either Realm.getInstanceAsync(RealmConfiguration, Realm.Callback) or DynamicRealm.getInstanceAsync(RealmConfiguration, DynamicRealm.Callback).

    Before creating the first Realm instance in a process, there are some initialization work that need to be done such as creating or validating schemas, running migration if needed, copy asset file if RealmConfiguration.Builder.assetFile(String) is supplied and execute the RealmConfiguration.Builder.initialData(Realm.Transaction) if necessary. This work may take time and block the caller thread for a while. To avoid the getInstance() call blocking the main thread, the getInstanceAsync() can be used instead to do the initialization work in the background thread and deliver a Realm instance to the caller thread.

    In general, this method is mostly useful on the UI thread since that should be blocked as little as possible. On any other Looper threads or other threads that don't support callbacks, using the standard getInstance() should be fine.

    Here is an example of using getInstanceAsync() when the app starts the first activity: 

     public class MainActivity extends Activity {

   private Realm realm = null;
   private RealmAsyncTask realmAsyncTask;
   private static RealmConfiguration config = new RealmConfiguration.Builder()
     .schema(42)
     .migration(new MyMigration()) // Potentially lengthy migration
     .build();

   \@Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.layout_main);
     realmAsyncTask = Realm.getInstanceAsync(config, new Callback() {
         \@Override
         public void onSuccess(Realm realm) {
             if (isDestroyed()) {
                 // If the activity is destroyed, the Realm instance should be closed immediately to avoid leaks.
                 // Or you can call realmAsyncTask.cancel() in onDestroy() to stop callback delivery.
                 realm.close();
             } else {
                 MainActivity.this.realm = realm;
                 // Remove the spinner and start the real UI.
             }
         }
     });

     // Show a spinner before Realm instance returned by the callback.
   }

   \@Override
   protected void onDestroy() {
     super.onDestroy();
     if (realm != null) {
         realm.close();
         realm = null;
     } else {
         // Calling cancel() on the thread where getInstanceAsync was called on to stop the callback delivery.
         // Otherwise you need to check if the activity is destroyed to close in the onSuccess() properly.
         realmAsyncTask.cancel();
     }
   }
 }

    • Constructor Detail

      • Callback

        public Callback()

    • Method Detail

      • onSuccess

        public abstract void onSuccess​(Realm realm)
        Deliver a Realm instance to the caller thread.
        Specified by:
        onSuccess in class io.realm.BaseRealm.InstanceCallback<Realm>
        Parameters:
        realm - the Realm instance for the caller thread.

      • onError

        public void onError​(Throwable exception)
        Deliver an error happens when creating the Realm instance to the caller thread. The default implementation will throw an exception on the caller thread.
        Overrides:
        onError in class io.realm.BaseRealm.InstanceCallback<Realm>
        Parameters:
        exception - happened while initializing Realm on a background thread.