Class SyncSession

Realm is now Atlas Device SDK – Learn More

io.realm.mongodb.sync

java.lang.Object

io.realm.mongodb.sync.SyncSession

A session controls how data is synchronized between a single Realm on the device and the server Realm on the Realm Object Server.A Session is created by opening a Realm instance using a SyncConfiguration . Once a session has been created, it will continue to exist until the app is closed or all threads using this SyncConfiguration closes their respective Realm s.

A session is controlled by Realm, but can provide additional information in case of errors. These errors are passed along in the SyncSession.ErrorHandler .

When creating a session, Realm will establish a connection to the server. This connection is controlled by Realm and might be shared between multiple sessions. It is possible to get insight into the connection using addConnectionChangeListener(ConnectionListener) and isConnected() .

The session itself has a different lifecycle than the underlying connection. The state of the session can be found using getState() .

The SyncSession object is thread safe.

Nested Class Summary

Modifier and Type	Class and Description
`public static final`	SyncSession.State
`public static interface`	SyncSession.ErrorHandler
`public static interface`	SyncSession.ClientResetHandler

Method Summary

Modifier and Type	Method and Description
public synchronized void	addConnectionChangeListener ( ConnectionListener listener ) Adds a listener tracking changes to the connection backing this session.
public synchronized void	addDownloadProgressListener ( ProgressMode mode, ProgressListener listener ) Adds a progress listener tracking changes that need to be downloaded from the Realm Object Server.
public synchronized void	addUploadProgressListener ( ProgressMode mode, ProgressListener listener ) Adds a progress listener tracking changes that need to be uploaded from the device to the Realm Object Server.
public boolean	downloadAllServerChanges ( long timeout, TimeUnit unit ) Calling this method will block until all known remote changes have been downloaded and applied to the Realm or the specified timeout is hit.
public void	downloadAllServerChanges () Calling this method will block until all known remote changes have been downloaded and applied to the Realm.
public SyncConfiguration	getConfiguration () Returns the SyncConfiguration that is responsible for controlling the session.
public ConnectionState	getConnectionState () Get the current state of the connection used by the session as defined in ConnectionState .
public URI	getServerUrl () Returns the URI describing the remote Realm which this session connects to and synchronizes changes with.
public SyncSession.State	getState () Get the current session's state, as defined in SyncSession.State .
public User	getUser () Returns the User defined by the SyncConfiguration that is used to connect to MongoDB Realm.
public boolean	isConnected () Checks if the session is connected to the server and can synchronize data.
public synchronized void	removeConnectionChangeListener ( ConnectionListener listener ) Removes a previously registered ConnectionListener .
public synchronized void	removeProgressListener ( ProgressListener listener ) Removes a progress listener.
public synchronized void	start () Attempts to start the session and enable synchronization with the Realm Object Server.
public synchronized void	stop () Stops any synchronization with the Realm Object Server until the Realm is re-opened again after fully closing it.
public boolean	uploadAllLocalChanges ( long timeout, TimeUnit unit ) Calling this method will block until all known local changes have been uploaded to the server or the specified timeout is hit.
public void	uploadAllLocalChanges () Calling this method will block until all known local changes have been uploaded to the server.

Inherited Methods

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

Method Detail

addConnectionChangeListener

public synchronized void addConnectionChangeListener ( ConnectionListener listener )
Adds a listener tracking changes to the connection backing this session. See ConnectionState for further details. Parameters `listener` - the listener to register. Throws IllegalArgumentException - if the listener is `null` . Tip See also: ConnectionState

addDownloadProgressListener

public synchronized void addDownloadProgressListener ( ProgressMode mode, ProgressListener listener )
Adds a progress listener tracking changes that need to be downloaded from the Realm Object Server.The ProgressListener will be triggered immediately when registered, and periodically afterwards. Parameters `mode` - type of mode used. See ProgressMode for more information. `listener` - the listener to register.

addUploadProgressListener

public synchronized void addUploadProgressListener ( ProgressMode mode, ProgressListener listener )
Adds a progress listener tracking changes that need to be uploaded from the device to the Realm Object Server.The ProgressListener will be triggered immediately when registered, and periodically afterwards. Parameters `mode` - type of mode used. See ProgressMode for more information. `listener` - the listener to register.

downloadAllServerChanges

public boolean downloadAllServerChanges ( long timeout, TimeUnit unit )
Calling this method will block until all known remote changes have been downloaded and applied to the Realm or the specified timeout is hit. This will involve network access, so calling this method should only be done from a non-UI thread.This method cannot be called before the Realm has been opened. Returns `true` if the data was downloaded before the timeout. `false` if the operation timed out or otherwise failed. Throws IllegalStateException - if called on the Android main thread. InterruptedException - if the download took longer than the specified timeout or the thread was interrupted while downloading was in progress. The download will continue in the background even after this exception is thrown. IllegalArgumentException - if `timeout` is less than or equal to `0` or `unit` is `null` .

public boolean downloadAllServerChanges (

long timeout,

TimeUnit unit

)

Calling this method will block until all known remote changes have been downloaded and applied to the Realm or the specified timeout is hit. This will involve network access, so calling this method should only be done from a non-UI thread.This method cannot be called before the Realm has been opened.

Returns

true if the data was downloaded before the timeout. false if the operation timed out or otherwise failed.

Throws

IllegalStateException - if called on the Android main thread.
InterruptedException - if the download took longer than the specified timeout or the thread was interrupted while downloading was in progress. The download will continue in the background even after this exception is thrown.
IllegalArgumentException - if timeout is less than or equal to 0 or unit is null .

public void downloadAllServerChanges ()
Calling this method will block until all known remote changes have been downloaded and applied to the Realm. This will involve network access, so calling this method should only be done from a non-UI thread.If the device is offline, this method might never return. This method cannot be called before the session has been started. Throws IllegalStateException - if called on the Android main thread. InterruptedException - if the thread was interrupted while downloading was in progress.

public void downloadAllServerChanges ()

Calling this method will block until all known remote changes have been downloaded and applied to the Realm. This will involve network access, so calling this method should only be done from a non-UI thread.If the device is offline, this method might never return.

This method cannot be called before the session has been started.

Throws

IllegalStateException - if called on the Android main thread.
InterruptedException - if the thread was interrupted while downloading was in progress.

getConfiguration

public SyncConfiguration getConfiguration ()
Returns the SyncConfiguration that is responsible for controlling the session. Returns SyncConfiguration that defines and controls this session.

getConnectionState

public ConnectionState getConnectionState ()
Get the current state of the connection used by the session as defined in ConnectionState . Returns the state of connection used by the session. Tip See also: ConnectionState

getServerUrl

public URI getServerUrl ()
Returns the URI describing the remote Realm which this session connects to and synchronizes changes with. Returns URI describing the remote Realm.

getState

public SyncSession.State getState ()
Get the current session's state, as defined in SyncSession.State . Note that the state may change after this method returns. Returns the state of the session. Tip See also: SyncSession.State

getUser

public User getUser ()
Returns the User defined by the SyncConfiguration that is used to connect to MongoDB Realm. Returns User used to authenticate the session on MongoDB Realm.

isConnected

public boolean isConnected ()
Checks if the session is connected to the server and can synchronize data. This is a best guess effort. To conserve battery the underlying implementation uses heartbeats to detect if the connection is still available. So if no data is actively being synced and some time has elapsed since the last heartbeat, the connection could have been dropped but this method will still return `true` . Returns `true` if the session is connected and ready to synchronize data, `false` if not or if it is in the process of connecting.

public boolean isConnected ()

Checks if the session is connected to the server and can synchronize data. This is a best guess effort. To conserve battery the underlying implementation uses heartbeats to detect if the connection is still available. So if no data is actively being synced and some time has elapsed since the last heartbeat, the connection could have been dropped but this method will still return true .

Returns

true if the session is connected and ready to synchronize data, false if not or if it is in the process of connecting.

removeConnectionChangeListener

public synchronized void removeConnectionChangeListener ( ConnectionListener listener )
Removes a previously registered ConnectionListener . Parameters `listener` - listener to remove Throws IllegalArgumentException - if the listener is `null` .

removeProgressListener

public synchronized void removeProgressListener ( ProgressListener listener )
Removes a progress listener. If the listener wasn't registered, this method will do nothing. Parameters `listener` - listener to remove.

start

public synchronized void start ()
Attempts to start the session and enable synchronization with the Realm Object Server.This happens automatically when opening the Realm instance, so doing it manually should only be needed if the session was stopped using stop() . If the session was already started, calling this method will do nothing. A session is considered started if getState() returns State.ACTIVE . If the session is State.DYING , the session will be moved back to State.ACTIVE . Tip See also: getState() stop()

public synchronized void start ()

Attempts to start the session and enable synchronization with the Realm Object Server.This happens automatically when opening the Realm instance, so doing it manually should only be needed if the session was stopped using stop() .

If the session was already started, calling this method will do nothing.

A session is considered started if getState() returns State.ACTIVE . If the session is State.DYING , the session will be moved back to State.ACTIVE .

Tip

stop

public synchronized void stop ()
Stops any synchronization with the Realm Object Server until the Realm is re-opened again after fully closing it.Synchronization can be re-enabled by calling start() again. If the session is already stopped, calling this method will do nothing.

uploadAllLocalChanges

public boolean uploadAllLocalChanges ( long timeout, TimeUnit unit )
Calling this method will block until all known local changes have been uploaded to the server or the specified timeout is hit. This will involve network access, so calling this method should only be done from a non-UI thread.This method cannot be called before the Realm has been opened. Returns `true` if the data was uploaded before the timeout. `false` if the operation timed out or otherwise failed. Throws IllegalStateException - if called on the Android main thread. InterruptedException - if the upload took longer than the specified timeout or the thread was interrupted while uploading was in progress. The upload will continue in the background even after this exception is thrown. IllegalArgumentException - if `timeout` is less than or equal to `0` or `unit` is `null` .

public boolean uploadAllLocalChanges (

long timeout,

TimeUnit unit

)

Calling this method will block until all known local changes have been uploaded to the server or the specified timeout is hit. This will involve network access, so calling this method should only be done from a non-UI thread.This method cannot be called before the Realm has been opened.

Returns

true if the data was uploaded before the timeout. false if the operation timed out or otherwise failed.

Throws

IllegalStateException - if called on the Android main thread.
InterruptedException - if the upload took longer than the specified timeout or the thread was interrupted while uploading was in progress. The upload will continue in the background even after this exception is thrown.
IllegalArgumentException - if timeout is less than or equal to 0 or unit is null .

public void uploadAllLocalChanges ()
Calling this method will block until all known local changes have been uploaded to the server. This will involve network access, so calling this method should only be done from a non-UI thread.If the device is offline, this method might never return. This method cannot be called before the Realm has been opened. Throws IllegalStateException - if called on the Android main thread. InterruptedException - if the thread was interrupted while downloading was in progress.

public void uploadAllLocalChanges ()

Calling this method will block until all known local changes have been uploaded to the server. This will involve network access, so calling this method should only be done from a non-UI thread.If the device is offline, this method might never return.

This method cannot be called before the Realm has been opened.

Throws

IllegalStateException - if called on the Android main thread.
InterruptedException - if the thread was interrupted while downloading was in progress.

←

→

Class SyncSession.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

io.realm.mongodb.sync

Nested Class Summary

Method Summary

Inherited Methods

Method Detail

addConnectionChangeListener

Tip

See also:

addDownloadProgressListener

addUploadProgressListener

downloadAllServerChanges

getConfiguration

getConnectionState

Tip

See also:

getServerUrl

getState

Tip

See also:

getUser

isConnected

removeConnectionChangeListener

removeProgressListener

start

Tip

See also:

stop

uploadAllLocalChanges

Class SyncSession