io.realm

Class SyncUser

java.lang.Object

io.realm.SyncUser

public class SyncUser
extends Object

This class represents a user on the Realm Object Server. The credentials are provided by various 3rd party providers (Facebook, Google, etc.).

A user can log in to the Realm Object Server, and if access is granted, it is possible to synchronize the local and the remote Realm. Moreover, synchronization is halted when the user is logged out.

It is possible to persist a user. By retrieving a user, there is no need to log in to the 3rd party provider again. Persisting a user between sessions, the user's credentials are stored locally on the device, and should be treated as sensitive data.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SyncUser.Callback<T>

Method Summary

Modifier and Type	Method and Description
static Map<String,SyncUser>	all() Returns all valid users known by this device.
List<SyncSession>	allSessions() Returns all the valid sessions belonging to the user.
void	changePassword(String newPassword) Changes this user's password.
void	changePassword(String userId, String newPassword) Changes another user's password.
RealmAsyncTask	changePasswordAsync(String userId, String newPassword, SyncUser.Callback<SyncUser> callback) Changes another user's password asynchronously.
RealmAsyncTask	changePasswordAsync(String newPassword, SyncUser.Callback<SyncUser> callback) Changes this user's password asynchronously.
static void	completePasswordReset(String resetToken, String newPassword, String authenticationUrl) Complete the password reset flow by using the reset token sent to the user's email as a one-time authorization token to change the password.
static RealmAsyncTask	completePasswordResetAsync(String resetToken, String newPassword, String authenticationUrl, SyncUser.Callback<Void> callback) Complete the password reset flow by using the reset token sent to the user's email as a one-time authorization token to change the password.
static void	confirmEmail(String confirmationToken, String authenticationUrl) Complete the email confirmation flow by using the confirmation token sent to the user's email as a one-time authorization token to confirm their email.
static RealmAsyncTask	confirmEmailAsync(String confirmationToken, String authenticationUrl, SyncUser.Callback<Void> callback) Complete the email confirmation flow by using the confirmation token sent to the user's email as a one-time authorization token to confirm their email.
SyncConfiguration.Builder	createConfiguration(String uri) Opening a synchronized Realm requires a SyncConfiguration.
static SyncUser	current() Returns the current user that is logged in and still valid.
boolean	equals(Object o)
static SyncUser	fromJson(String user) Loads a user that has previously been serialized using toJson().
URL	getAuthenticationUrl() Returns the URL where this user was authenticated.
SyncConfiguration	getDefaultConfiguration() Returns the default configuration for this user.
String	getIdentity() Returns the identity of this user on the Realm Object Server.
PermissionManager	getPermissionManager() Returns an instance of the PermissionManager for this user that makes it possible to see, modify and create permissions related to this users Realms.
int	hashCode()
boolean	isAdmin() Returns true if this user is an administrator on the Realm Object Server, false otherwise.
boolean	isValid() Returns true if the user is logged into the Realm Object Server.
static SyncUser	logIn(SyncCredentials credentials, String authenticationUrl) Logs in the user to the Realm Object Server.
static RealmAsyncTask	logInAsync(SyncCredentials credentials, String authenticationUrl, SyncUser.Callback<SyncUser> callback) Logs in the user to the Realm Object Server.
void	logOut() Log a user out, destroying their server state, unregistering them from the SDK, and removing any synced Realms associated with them, from on-disk storage on next app launch (or directly if all instances are closed).
static void	requestEmailConfirmation(String email, String authenticationUrl) Request an email confirmation email to be sent to a user's email.
static RealmAsyncTask	requestEmailConfirmationAsync(String email, String authenticationUrl, SyncUser.Callback<Void> callback) Request an email confirmation email to be sent to a user's email.
static void	requestPasswordReset(String email, String authenticationUrl) Request a password reset email to be sent to a user's email.
static RealmAsyncTask	requestPasswordResetAsync(String email, String authenticationUrl, SyncUser.Callback<Void> callback) Request a password reset email to be sent to a user's email.
SyncUserInfo	retrieveInfoForUser(String providerUserIdentity, String provider) Given a Realm Object Server authentication provider and a provider identifier for a user (for example, a username), look up and return user information for that user.
RealmAsyncTask	retrieveInfoForUserAsync(String providerUserIdentity, String provider, SyncUser.Callback<SyncUserInfo> callback) Given a Realm Object Server authentication provider and a provider identifier for a user (for example, a username), asynchronously look up and return user information for that user.
String	toJson() Returns a JSON token representing this user.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

current

public static SyncUser current()

Returns the current user that is logged in and still valid. A user is invalidated when he/she logs out or the user's access token expires.

Returns:

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

Throws:

IllegalStateException - if multiple users are logged in.

all

public static Map<String,SyncUser> all()

Returns all valid users known by this device. A user is invalidated when he/she logs out or the user's access token expires.

Returns:

a map from user identifier to user. It includes all known valid users.

fromJson

public static SyncUser fromJson(String user)

Loads a user that has previously been serialized using toJson().

Parameters:

user - JSON string representing the user.

Returns:

the user object.

Throws:

IllegalArgumentException - if the JSON couldn't be converted to a valid SyncUser object.

logIn

public static SyncUser logIn(SyncCredentials credentials,
                             String authenticationUrl)
                      throws ObjectServerError

Logs in the user to the Realm Object Server. This is done synchronously, so calling this method on the Android UI thread will always crash. A logged in user is required to be able to create a SyncConfiguration.

Parameters:

credentials - credentials to use.

authenticationUrl - server that can authenticate against.

Throws:

ObjectServerError - if the login failed.

IllegalArgumentException - if the URL is malformed.

logInAsync

public static RealmAsyncTask logInAsync(SyncCredentials credentials,
                                        String authenticationUrl,
                                        SyncUser.Callback<SyncUser> callback)

Logs in the user to the Realm Object Server. A logged in user is required to be able to create a SyncConfiguration.

Parameters:

credentials - credentials to use.

authenticationUrl - server that the user is authenticated against.

callback - callback when login has completed or failed. The callback will always happen on the same thread as this this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalArgumentException - if not on a Looper thread.

createConfiguration

public SyncConfiguration.Builder createConfiguration(String uri)

Opening a synchronized Realm requires a SyncConfiguration. This method creates a SyncConfiguration.Builder that can be used to create it by calling SyncConfiguration.Builder.build().

The default synchronization mode for this Realm is query-based synchronizaton, but see the SyncConfiguration.Builder class for more details on how to configure a Realm.

A synchronized Realm is identified by an unique URI. In the URI, /~/ can be used as a placeholder for a user ID in case the Realm should only be available to one user e.g., "realm://objectserver.realm.io/~/default".

The URL cannot end with .realm, .realm.lock or .realm.management.

The /~/ will automatically be replaced with the user ID when creating the SyncConfiguration.

Moreover, the URI defines the local location on disk. The location of a synchronized Realm file is /data/data/<packageName>/files/realm-object-server/<user-id>/<last-path-segment>, but this behavior can be overwritten using SyncConfiguration.Builder.name(String) and SyncConfiguration.Builder.directory(File).

Many Android devices are using FAT32 file systems. FAT32 file systems have a limitation that file names cannot be longer than 255 characters. Moreover, the entire URI should not exceed 256 characters. If the file name and underlying path are too long to handle for FAT32, a shorter unique name will be generated. See also @{link https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx}.

Parameters:

uri - URI identifying the Realm. If only a path like /~/default is given, the configuration will assume the file is located on the same server returned by getAuthenticationUrl().

Throws:

IllegalStateException - if the user isn't valid. See isValid().

getDefaultConfiguration

public SyncConfiguration getDefaultConfiguration()

Returns the default configuration for this user. The default configuration points to the default query-based Realm on the server the user authenticated against.

Returns:

the default configuration for this user.

Throws:

IllegalStateException - if the user isn't valid. See isValid().

logOut

public void logOut()

Log a user out, destroying their server state, unregistering them from the SDK, and removing any synced Realms associated with them, from on-disk storage on next app launch (or directly if all instances are closed). If the user is already logged out or in an error state, this method does nothing. This method should be called whenever the application is committed to not using a user again unless they are recreated. Failing to call this method may result in unused files and metadata needlessly taking up space. Once the Object Server has confirmed the logout any registered AuthenticationListener will be notified and user credentials will be deleted from this device.

changePassword

public void changePassword(String newPassword)
                    throws ObjectServerError

Changes this user's password. This is done synchronously and involves the network, so calling this method on the Android UI thread will always crash.

WARNING: Changing a user's password through an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

Parameters:

newPassword - the user's new password.

Throws:

ObjectServerError - if the password could not be changed.

changePassword

public void changePassword(String userId,
                           String newPassword)
                    throws ObjectServerError

Changes another user's password. This is done synchronously and involves the network, so calling this method on the Android UI thread will always crash.

This user needs admin privilege in order to change someone else's password.

WARNING: Changing a user's password through an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

Parameters:

userId - identity (getIdentity()) of the user we want to change the password for.

newPassword - the user's new password.

Throws:

ObjectServerError - if the password could not be changed.

changePasswordAsync

public RealmAsyncTask changePasswordAsync(String newPassword,
                                          SyncUser.Callback<SyncUser> callback)

Changes this user's password asynchronously.

WARNING: Changing a users password using an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

Parameters:

newPassword - the user's new password.

callback - callback when login has completed or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalArgumentException - if not on a Looper thread.

changePasswordAsync

public RealmAsyncTask changePasswordAsync(String userId,
                                          String newPassword,
                                          SyncUser.Callback<SyncUser> callback)

Changes another user's password asynchronously.

This user needs admin privilege in order to change someone else's password. WARNING: Changing a users password using an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

Parameters:

userId - identity (getIdentity()) of the user we want to change the password for.

newPassword - the user's new password.

callback - callback when login has completed or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalArgumentException - if not on a Looper thread.

requestPasswordReset

public static void requestPasswordReset(String email,
                                        String authenticationUrl)
                                 throws ObjectServerError

Request a password reset email to be sent to a user's email. This will not fail, even if the email doesn't belong to a Realm Object Server user.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

Parameters:

email - email that corresponds to the user's username.

authenticationUrl - the url used to authenticate the user.

Throws:

IllegalStateException - if this method is called on the UI thread.

IllegalArgumentException - if no email or authenticationUrl was provided.

ObjectServerError - if an error happened on the server.

requestPasswordResetAsync

public static RealmAsyncTask requestPasswordResetAsync(String email,
                                                       String authenticationUrl,
                                                       SyncUser.Callback<Void> callback)

Request a password reset email to be sent to a user's email. This will not fail, even if the email doesn't belong to a Realm Object Server user.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

Parameters:

email - email that corresponds to the user's username.

authenticationUrl - the url used to authenticate the user.

callback - callback when the request has completed or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalStateException - if this method is called on a non-looper thread.

IllegalArgumentException - if no email or authenticationUrl was provided.

completePasswordReset

public static void completePasswordReset(String resetToken,
                                         String newPassword,
                                         String authenticationUrl)

Complete the password reset flow by using the reset token sent to the user's email as a one-time authorization token to change the password.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

By default, Realm Object Server will send a link to the user's email that will redirect to a webpage where they can enter their new password. If you wish to provide a native UX, you may wish to modify the password authentication provider to use a custom URL with deep linking, so you can open the app, extract the token, and navigate to a view that allows to change the password within the app.

Parameters:

resetToken - the token that was sent to the user's email address.

newPassword - the user's new password.

authenticationUrl - the url used to authenticate the user.

Throws:

IllegalStateException - if this method is called on the UI thread.

IllegalArgumentException - if no token or newPassword was provided.

ObjectServerError - if an error happened on the server.

completePasswordResetAsync

public static RealmAsyncTask completePasswordResetAsync(String resetToken,
                                                        String newPassword,
                                                        String authenticationUrl,
                                                        SyncUser.Callback<Void> callback)
                                                 throws ObjectServerError

Complete the password reset flow by using the reset token sent to the user's email as a one-time authorization token to change the password.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

By default, Realm Object Server will send a link to the user's email that will redirect to a webpage where they can enter their new password. If you wish to provide a native UX, you may wish to modify the password authentication provider to use a custom URL with deep linking, so you can open the app, extract the token, and navigate to a view that allows to change the password within the app.

Parameters:

resetToken - the token that was sent to the user's email address.

newPassword - the user's new password.

authenticationUrl - the url used to authenticate the user.

callback - callback when the server has accepted the new password or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalStateException - if this method is called on a non-looper thread.

IllegalArgumentException - if no token or newPassword was provided.

ObjectServerError

requestEmailConfirmation

public static void requestEmailConfirmation(String email,
                                            String authenticationUrl)
                                     throws ObjectServerError

Request an email confirmation email to be sent to a user's email. This will not fail, even if the email doesn't belong to a Realm Object Server user.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

Parameters:

email - the email that corresponds to the user's username.

authenticationUrl - the url used to authenticate the user.

Throws:

IllegalStateException - if this method is called on the UI thread.

IllegalArgumentException - if no email was provided.

ObjectServerError - if an error happened on the server.

requestEmailConfirmationAsync

public static RealmAsyncTask requestEmailConfirmationAsync(String email,
                                                           String authenticationUrl,
                                                           SyncUser.Callback<Void> callback)

Request an email confirmation email to be sent to a user's email. This will not fail, even if the email doesn't belong to a Realm Object Server user.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

Parameters:

email - the email that corresponds to the user's username.

authenticationUrl - the url used to authenticate the user.

callback - callback when the request has completed or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalStateException - if this method is called on a non-looper thread.

IllegalArgumentException - if no email was provided.

confirmEmail

public static void confirmEmail(String confirmationToken,
                                String authenticationUrl)
                         throws ObjectServerError

Complete the email confirmation flow by using the confirmation token sent to the user's email as a one-time authorization token to confirm their email.

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

By default, Realm Object Server will send a link to the user's email that will redirect to a webpage where they can enter their new password. If you wish to provide a native UX, you may wish to modify the password authentication provider to use a custom URL with deep linking, so you can open the app, extract the token, and navigate to a view that allows to confirm the email within the app.

Parameters:

confirmationToken - the token that was sent to the user's email address.

authenticationUrl - the url used to authenticate the user.

Throws:

IllegalStateException - if this method is called on the UI thread.

IllegalArgumentException - if no confirmationToken was provided.

ObjectServerError - if an error happened on the server.

confirmEmailAsync

public static RealmAsyncTask confirmEmailAsync(String confirmationToken,
                                               String authenticationUrl,
                                               SyncUser.Callback<Void> callback)

Complete the email confirmation flow by using the confirmation token sent to the user's email as a one-time authorization token to confirm their email. This functionalit

This can only be used for users who authenticated with the SyncCredentials.IdentityProvider.USERNAME_PASSWORD provider, and passed a valid email address as a username.

By default, Realm Object Server will send a link to the user's email that will redirect to a webpage where they can enter their new password. If you wish to provide a native UX, you may wish to modify the password authentication provider to use a custom URL with deep linking, so you can open the app, extract the token, and navigate to a view that allows to confirm the email within the app.

Parameters:

confirmationToken - the token that was sent to the user's email address.

authenticationUrl - the url used to authenticate the user.

callback - callback when the server has confirmed the email or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

Throws:

IllegalStateException - if this method is called on a non-looper thread.

IllegalArgumentException - if no confirmationToken was provided.

retrieveInfoForUser

public SyncUserInfo retrieveInfoForUser(String providerUserIdentity,
                                        String provider)
                                 throws ObjectServerError

Given a Realm Object Server authentication provider and a provider identifier for a user (for example, a username), look up and return user information for that user.

Parameters:

providerUserIdentity - The username or identity of the user as issued by the authentication provider. In most cases this is different from the Realm Object Server-issued identity.

provider - The authentication provider SyncCredentials.IdentityProvider that manages the user whose information is desired.

Returns:

SyncUser associated with the given identity provider and providerId, or null in case of an invalid provider or providerId.

Throws:

IllegalStateException - if this method is called on the UI thread.

IllegalArgumentException - if no providerUserIdentity or provider string was provided.

ObjectServerError - if an error happened on the server.

retrieveInfoForUserAsync

public RealmAsyncTask retrieveInfoForUserAsync(String providerUserIdentity,
                                               String provider,
                                               SyncUser.Callback<SyncUserInfo> callback)

Given a Realm Object Server authentication provider and a provider identifier for a user (for example, a username), asynchronously look up and return user information for that user.

Parameters:

providerUserIdentity - The username or identity of the user as issued by the authentication provider. In most cases this is different from the Realm Object Server-issued identity.

provider - The authentication provider SyncCredentials.IdentityProvider that manages the user whose information is desired.

callback - callback when the lookup has completed or failed. The callback will always happen on the same thread as this method is called on.

Returns:

representation of the async task that can be used to cancel it if needed.

toJson

public String toJson()

Returns a JSON token representing this user.

Possession of this JSON token can potentially grant access to data stored on the Realm Object Server, so it should be treated as sensitive data.

Returns:

JSON string representing this user. It can be converted back into a real user object using fromJson(String).

See Also:

fromJson(String)

isValid

public boolean isValid()

Returns true if the user is logged into the Realm Object Server. If this method returns true it implies that the user has valid credentials that have not expired.

The user might still have been logged out by the Realm Object Server which will not be detected before the user tries to actively synchronize a Realm. If a logged out user tries to synchronize a Realm, an error will be reported to the SyncSession.ErrorHandler defined by SyncConfiguration.Builder.errorHandler(SyncSession.ErrorHandler).

Returns:

true if the User is logged into the Realm Object Server, false otherwise.

isAdmin

public boolean isAdmin()

Returns true if this user is an administrator on the Realm Object Server, false otherwise.

Administrators can access all Realms on the server as well as change the permissions of the Realms.

Returns:

true if the user is an administrator on the Realm Object Server, false otherwise.

getIdentity

public String getIdentity()

Returns the identity of this user on the Realm Object Server. The identity is a guaranteed to be unique among all users on the Realm Object Server.

Returns:

identity of the user on the Realm Object Server. If the user has logged out or the login has expired null is returned.

allSessions

public List<SyncSession> allSessions()

Returns all the valid sessions belonging to the user.

Returns:

the all valid sessions belong to the user.

getAuthenticationUrl

public URL getAuthenticationUrl()

Returns the URL where this user was authenticated.

Returns:

URL where the user was authenticated.

getPermissionManager

public PermissionManager getPermissionManager()

Returns an instance of the PermissionManager for this user that makes it possible to see, modify and create permissions related to this users Realms.

Every instance returned by this method must be closed by calling PermissionManager.close() when it no longer is needed.

The PermissionManager can only be opened from the main tread, calling this method from any other thread will throw an IllegalStateException.

Returns:

an instance of the PermissionManager.

Throws:

IllegalStateException - if this method is not called from the UI thread.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object