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
static interface	SyncUser.RequestCallback<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 callback) Changes another user's password asynchronously.
RealmAsyncTask	changePasswordAsync(String newPassword, SyncUser.Callback callback) Changes this user's password asynchronously.
static SyncUser	currentUser() 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().
Token	getAccessToken() Returns this user's access token.
URL	getAuthenticationUrl() Returns the URL where this user was authenticated.
String	getIdentity() Returns the identity of this user on the Realm Object Server.
Realm	getManagementRealm() Deprecated. use getPermissionManager() instead.
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 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).
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.RequestCallback<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.
SyncUser	retrieveUser(String provider, String providerId) Deprecated. as of release 3.6.0, replaced by retrieveInfoForUser(String, String)}
RealmAsyncTask	retrieveUserAsync(String provider, String providerId, SyncUser.Callback callback) Deprecated. as of release 3.6.0, replaced by retrieveInfoForUserAsync(String, String, RequestCallback)}
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

currentUser

public static SyncUser 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 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 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.

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

retrieveUser

@Deprecated
public SyncUser retrieveUser(String provider,
                                         String providerId)
                                  throws ObjectServerError

Deprecated. as of release 3.6.0, replaced by retrieveInfoForUser(String, String)}

Helper method for Admin users in order to lookup a SyncUser using the identity provider and the used username.

Parameters:

provider - identity providers SyncCredentials.IdentityProvider used when the account was created.

providerId - username or email used to create the account for the first time, what is needed will depend on what type of SyncCredentials was used.

Returns:

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

Throws:

ObjectServerError - in case of an error.

retrieveUserAsync

@Deprecated
public RealmAsyncTask retrieveUserAsync(String provider,
                                                    String providerId,
                                                    SyncUser.Callback callback)

Deprecated. as of release 3.6.0, replaced by retrieveInfoForUserAsync(String, String, RequestCallback)}

Asynchronously lookup a SyncUser using the identity provider and the used username. This is for Admin users only.

Parameters:

provider - identity providers SyncCredentials.IdentityProvider used when the account was created.

providerId - username or email used to create the account for the first time, what is needed will depend on what type of SyncCredentials was used.

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.

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:

ObjectServerError - in case of an error.

retrieveInfoForUserAsync

public RealmAsyncTask retrieveInfoForUserAsync(String providerUserIdentity,
                                               String provider,
                                               SyncUser.RequestCallback<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:

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

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.

getAccessToken

public Token getAccessToken()

Returns this user's access token. This is the users credential for accessing the Realm Object Server and should be treated as sensitive data.

Returns:

the user's access token. If this user has logged out or the login has expired null is returned.

getManagementRealm

@Deprecated
public Realm getManagementRealm()

Deprecated. use getPermissionManager() instead.

Returns an instance of the Management Realm owned by the user.

This Realm can be used to control access and permissions for Realms owned by the user. This includes giving other users access to Realms.

See Also:

How to control permissions

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