Package io.realm.mongodb

Class App

  • public class App
extends Object
    An App is the main client-side entry point for interacting with a MongoDB Realm App.

    The App can be used to:

    • Register uses and perform various user-related operations through authentication providers (ApiKeyAuth, EmailPasswordAuthImpl)
    • Synchronize data between the local device and a remote Realm App with Synchronized Realms
    • Invoke Realm App functions with Functions
    • Access remote data from MongoDB databases with a MongoClient

    To create an app that is linked with a remote Realm App initialize Realm and configure the App as shown below: 

        class MyApplication extends Application {

         App APP; // The App instance should be a global singleton

         \@Override
         public void onCreate() {
             super.onCreate();

             Realm.init(this);

             AppConfiguration appConfiguration = new AppConfiguration.Builder(BuildConfig.MONGODB_REALM_APP_ID)
                     .appName(BuildConfig.VERSION_NAME)
                     .appVersion(Integer.toString(BuildConfig.VERSION_CODE))
                     .build();

             APP = new App(appConfiguration);
         }

     }

    After configuring the App you can start managing users, configure Synchronized Realms, call remote Realm Functions and access remote data through Mongo Collections. The examples below show the synchronized APIs which cannot be used from the main thread. For the equivalent asynchronous counterparts. The example project in please see https://github.com/realm/realm-java/tree/v10/examples/mongoDbRealmExample.

    To register a new user and/or login with an existing user do as shown below: 

         // Register new user
     APP.getEmailPassword().registerUser(username, password);

     // Login with existing user
     User user = APP.login(Credentials.emailPassword(username, password))

    With an authorized user you can synchronize data between the local device and the remote Realm App by opening a Realm with a SyncConfiguration as indicated below: 

         SyncConfiguration syncConfiguration = new SyncConfiguration.Builder(user, "<partition value>")
              .build();

     Realm instance = Realm.getInstance(syncConfiguration);
     SyncSession session = APP.getSync().getSession(syncConfiguration);

     instance.executeTransaction(realm -> {
         realm.insert(...);
     });
     session.uploadAllLocalChanges();
     instance.close();

    You can call remote Realm functions as shown below: 

         Functions functions = user.getFunctions();
     Integer sum = functions.callFunction("sum", Arrays.asList(1, 2, 3, 4), Integer.class);

    And access collections from the remote Realm App as shown here: 

         MongoClient client = user.getMongoClient(SERVICE_NAME)
     MongoDatabase database = client.getDatabase(DATABASE_NAME)
     MongoCollection<DocumentT> collection = database.getCollection(COLLECTION_NAME);
     Long count = collection.count().get()

    See Also:
    AppConfiguration.Builder, EmailPasswordAuth, SyncConfiguration, User.getFunctions(), User.getMongoClient(String)

    • Field Detail

      • NETWORK_POOL_EXECUTOR

        public static ThreadPoolExecutor NETWORK_POOL_EXECUTOR
        Thread pool used when doing network requests against MongoDB Realm.

        This pool is only exposed for testing purposes and replacing it while the queue is not empty will result in undefined behaviour.

    • Constructor Detail

      • App

        public App​(String appId)

      • App

        public App​(AppConfiguration config)
        Constructor for creating an App according to the given AppConfiguration.
        Parameters:
        config - The configuration to use for this App instance.
        See Also:
        AppConfiguration.Builder

    • Method Detail

      • currentUser

        @Nullable
public User currentUser()
        Returns the current user that is logged in and still valid.

        A user is invalidated when he/she logs out or the user's refresh token expires or is revoked.

        If two or more users are logged in, it is the last valid user that is returned by this method.

        Returns:
        current User that has logged in and is still valid. null if no user is logged in or the user has expired.

      • removeUser

        public User removeUser​(User user)
                throws AppException
        Removes a users credentials from this device. If the user was currently logged in, they will be logged out as part of the process. This is only a local change and does not affect the user state on the server.
        Parameters:
        user - to remove
        Returns:
        user that was removed.
        Throws:
        AppException - if called from the UI thread or if the user was logged in, but could not be logged out.

      • login

        public User login​(Credentials credentials)
           throws AppException
        Logs in as a user with the given credentials associated with an authentication provider.

        The user who logs in becomes the current user. Other App functionality acts on behalf of the current user.

        If there was already a current user, that user is still logged in and can be found in the list returned by allUsers().

        It is also possible to switch between which user is considered the current user by using switchUser(User).

        Parameters:
        credentials - the credentials representing the type of login.
        Returns:
        a User representing the logged in user.
        Throws:
        AppException - if the user could not be logged in.

      • loginAsync

        public RealmAsyncTask loginAsync​(Credentials credentials,
                                 App.Callback<User> callback)
        Logs in as a user with the given credentials associated with an authentication provider.

        The user who logs in becomes the current user. Other App functionality acts on behalf of the current user.

        If there was already a current user, that user is still logged in and can be found in the list returned by allUsers().

        It is also possible to switch between which user is considered the current user by using switchUser(User).

        Parameters:
        credentials - the credentials representing the type of login.
        callback - callback when logging in has completed or failed. The callback will always happen on the same thread as this method is called on.
        Throws:
        IllegalStateException - if not called on a looper thread.

      • addAuthenticationListener

        public void addAuthenticationListener​(AuthenticationListener listener)
        Sets a global authentication listener that will be notified about User events like login and logout.

        Callbacks to authentication listeners will happen on the UI thread.

        Parameters:
        listener - listener to register.
        Throws:
        IllegalArgumentException - if listener is null.

      • removeAuthenticationListener

        public void removeAuthenticationListener​(AuthenticationListener listener)
        Removes the provided global authentication listener.
        Parameters:
        listener - listener to remove.

      • getSync

        public Sync getSync()
        Returns the Sync instance managing the ongoing Realm Sync sessions synchronizing data between the local and the remote Realm App associated with this app.
        Returns:
        the Sync instance associated with this App.

      • getFunctions

        public Functions getFunctions​(User user,
                              CodecRegistry codecRegistry)
        Returns a Functions manager for invoking the Realm App's Realm Functions with a custom codec registry for encoding and decoding arguments and results.
        See Also:
        Functions

      • getConfiguration

        public AppConfiguration getConfiguration()
        Returns the configuration object for this app.
        Returns:
        the configuration for this app.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object