Docs Menu

Class App

On this page

java.lang.Object
io.realm.mongodb.App

An App is the main client-side entry point for interacting with a MongoDB Realm App.The App can be used to:

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 io.realm.mongodb.sync.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()
Tip
See also:
Constructor and Description
App (
String appId
)

Constructor for creating an App according to the given AppConfiguration.

Modifier and Type
Class and Description
public static
public static interface
Modifier and Type
Field and Description
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.

Modifier and Type
Method and Description
public void

Sets a global authentication listener that will be notified about User events like login and logout.

public Map

Returns all known users that are either User.State.LOGGED_IN or User.State.LOGGED_OUT .

public User

Returns the current user that is logged in and still valid.

public boolean

Two Apps are considered equal and will share their underlying state if they both refer to the same AppConfiguration.getAppId() .

Returns the configuration object for this app.

Returns a wrapper for interacting with functionality related to users either being created or logged in using the Credentials.Provider.EMAIL_PASSWORD identity provider.

public Functions
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.

public Functions

Returns a Functions manager for invoking the Realm App's Realm Functions.

public Sync

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

public int
public User
Credentials credentials
)

Logs in as a user with the given credentials associated with an authentication provider.

Logs in as a user with the given credentials associated with an authentication provider.

public void

Removes the provided global authentication listener.

public User

Removes a users credentials from this device.

protected void
OsJavaNetworkTransport transport
)

Exposed for testing.

public User

Switch current user.

  • Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize

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.

public App (
String appId
)
public App (
)

Constructor for creating an App according to the given AppConfiguration.

Parameters

  • config - The configuration to use for this App instance.

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

public Map allUsers ()

Returns all known users that are either User.State.LOGGED_IN or User.State.LOGGED_OUT .

Only users that at some point logged into this device will be returned.

Returns

a map of user identifiers and users known locally.

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.

public boolean equals (
)

Two Apps are considered equal and will share their underlying state if they both refer to the same AppConfiguration.getAppId() .

Overrides

equals in class Object

Returns the configuration object for this app.

Returns

the configuration for this app.

Returns a wrapper for interacting with functionality related to users either being created or logged in using the Credentials.Provider.EMAIL_PASSWORD identity provider.

Returns

wrapper for interacting with the Credentials.Provider.EMAIL_PASSWORD identity provider.

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.

Tip
See also:

Returns a Functions manager for invoking the Realm App's Realm Functions.This will use the app's default codec registry to encode and decode arguments and results.

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.

public int hashCode ()

Overrides

hashCode in class Object

public User login (
Credentials credentials
)

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

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

Removes the provided global authentication listener.

Parameters

  • listener - listener to remove.
public User removeUser (
User user
)

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.
protected void setNetworkTransport (
OsJavaNetworkTransport transport
)
Exposed for testing.Swap the currently configured network transport with the provided one. This should only be done if no network requests are currently running.
public User switchUser (
User user
)

Switch current user.The current user is the user returned by currentUser() .

Parameters

  • user - the new current user.

Throws

←  io.realm.mongodbInterface App.Callback →
Give Feedback
© 2022 MongoDB, Inc.

About

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