Docs Menu

Docs Home → Develop Applications → Atlas Device SDKs

Class App

On this page

  • io.realm.mongodb
  • Constructors
  • Nested Class Summary
  • Field Summary
  • Method Summary
  • Inherited Methods
  • Field Detail
  • NETWORK_POOL_EXECUTOR
  • Constructor Detail
  • Method Detail
  • addAuthenticationListener
  • allUsers
  • currentUser
  • equals
  • getConfiguration
  • getEmailPassword
  • getFunctions
  • getSync
  • hashCode
  • login
  • loginAsync
  • removeAuthenticationListener
  • removeUser
  • setNetworkTransport
  • switchUser

io.realm.mongodb

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:

  • Register uses and perform various user-related operations through authentication providers (io.realm.mongodb.auth.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 io.realm.mongodb.mongo.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, see https://github.com/realm/realm-java/tree/main/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:

Constructors

Constructor and Description
App (
String appId
)
App (
AppConfiguration config
)

Constructor for creating an App according to the given AppConfiguration.

Nested Class Summary

Modifier and Type
Class and Description
public static
App.Result
public static interface
App.Callback

Field Summary

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.

Method Summary

Modifier and Type
Method and Description
public void
addAuthenticationListener (
AuthenticationListener listener
)

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

public Map
allUsers ()

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

public User
currentUser ()

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

public boolean
equals (
Object o
)

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

public AppConfiguration
getConfiguration ()

Returns the configuration object for this app.

public EmailPasswordAuth
getEmailPassword ()

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

public Functions
getFunctions (
User user
)

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

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.

public int
hashCode ()

public User
login (
Credentials credentials
)

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

public RealmAsyncTask
loginAsync (
Credentials credentials,
io.realm.mongodb.App.Callback<io.realm.mongodb.User> callback
)

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

public void
removeAuthenticationListener (
AuthenticationListener listener
)

Removes the provided global authentication listener.

public User
removeUser (
User user
)

Removes a users credentials from this device.

protected void
setNetworkTransport (
OsJavaNetworkTransport transport
)

Exposed for testing.

public User
switchUser (
User user
)

Switch current user.

Inherited Methods

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

Field Detail

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

public App (
String appId
)
public App (
AppConfiguration config
)

Constructor for creating an App according to the given AppConfiguration.

Parameters

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

Tip

See also:

Method Detail

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

allUsers

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.

currentUser

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.

equals

public boolean equals (
Object o
)

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

getConfiguration

public AppConfiguration getConfiguration ()

Returns the configuration object for this app.

Returns

the configuration for this app.

getEmailPassword

public EmailPasswordAuth getEmailPassword ()

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.

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.

Tip

See also:

public Functions getFunctions (
User user
)

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.

Tip

See also:

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.

hashCode

public int hashCode ()

Overrides

hashCode in class Object

login

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

loginAsync

public RealmAsyncTask loginAsync (
Credentials credentials,
io.realm.mongodb.App.Callback<io.realm.mongodb.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

removeAuthenticationListener

public void removeAuthenticationListener (
AuthenticationListener listener
)

Removes the provided global authentication listener.

Parameters

  • listener - listener to remove.

removeUser

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.

setNetworkTransport

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.

switchUser

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.mongodb
Interface App.Callback →

On this page