Class SyncSession
- java.lang.Object
-
- io.realm.mongodb.sync.SyncSession
-
public class SyncSession extends Object
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 thisSyncConfiguration
closes their respectiveRealm
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)
andisConnected()
.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
Nested Classes Modifier and Type Class Description static interface
SyncSession.ClientResetHandler
Deprecated.replaced byManuallyRecoverUnsyncedChangesStrategy
static interface
SyncSession.ErrorHandler
Interface used to report any session errors.static class
SyncSession.State
Enum describing the states a SyncSession can be in.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addConnectionChangeListener(ConnectionListener listener)
Adds a listener tracking changes to the connection backing this session.void
addDownloadProgressListener(ProgressMode mode, ProgressListener listener)
Adds a progress listener tracking changes that need to be downloaded from the Realm Object Server.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.void
downloadAllServerChanges()
Calling this method will block until all known remote changes have been downloaded and applied to the Realm.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.SyncConfiguration
getConfiguration()
Returns theSyncConfiguration
that is responsible for controlling the session.ConnectionState
getConnectionState()
Get the current state of the connection used by the session as defined inConnectionState
.URI
getServerUrl()
Returns theURI
describing the remote Realm which this session connects to and synchronizes changes with.SyncSession.State
getState()
Get the current session's state, as defined inSyncSession.State
.User
getUser()
Returns theUser
defined by theSyncConfiguration
that is used to connect to MongoDB Realm.boolean
isConnected()
Checks if the session is connected to the server and can synchronize data.void
removeConnectionChangeListener(ConnectionListener listener)
Removes a previously registeredConnectionListener
.void
removeProgressListener(ProgressListener listener)
Removes a progress listener.void
start()
Attempts to start the session and enable synchronization with the Realm Object Server.void
stop()
Stops any synchronization with the Realm Object Server until the Realm is re-opened again after fully closing it.void
uploadAllLocalChanges()
Calling this method will block until all known local changes have been uploaded to the server.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.
-
-
-
Method Detail
-
getConfiguration
public SyncConfiguration getConfiguration()
Returns theSyncConfiguration
that is responsible for controlling the session.- Returns:
- SyncConfiguration that defines and controls this session.
-
getUser
public User getUser()
Returns theUser
defined by theSyncConfiguration
that is used to connect to MongoDB Realm.- Returns:
User
used to authenticate the session on MongoDB Realm.
-
getServerUrl
public URI getServerUrl()
Returns theURI
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 inSyncSession.State
.Note that the state may change after this method returns.
- Returns:
- the state of the session.
- See Also:
SyncSession.State
-
getConnectionState
public ConnectionState getConnectionState()
Get the current state of the connection used by the session as defined inConnectionState
.- Returns:
- the state of connection used by the session.
- See Also:
ConnectionState
-
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 returntrue
.- Returns:
true
if the session is connected and ready to synchronize data,false
if not or if it is in the process of connecting.
-
addDownloadProgressListener
public 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. SeeProgressMode
for more information.listener
- the listener to register.
-
addUploadProgressListener
public 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. SeeProgressMode
for more information.listener
- the listener to register.
-
removeProgressListener
public void removeProgressListener(ProgressListener listener)
Removes a progress listener. If the listener wasn't registered, this method will do nothing.- Parameters:
listener
- listener to remove.
-
addConnectionChangeListener
public void addConnectionChangeListener(ConnectionListener listener)
Adds a listener tracking changes to the connection backing this session. SeeConnectionState
for further details.- Parameters:
listener
- the listener to register.- Throws:
IllegalArgumentException
- if the listener isnull
.- See Also:
ConnectionState
-
removeConnectionChangeListener
public void removeConnectionChangeListener(ConnectionListener listener)
Removes a previously registeredConnectionListener
.- Parameters:
listener
- listener to remove- Throws:
IllegalArgumentException
- if the listener isnull
.
-
downloadAllServerChanges
public void downloadAllServerChanges() throws InterruptedException
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.
-
downloadAllServerChanges
public boolean downloadAllServerChanges(long timeout, TimeUnit unit) throws InterruptedException
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
- iftimeout
is less than or equal to0
orunit
isnull
.
-
uploadAllLocalChanges
public void uploadAllLocalChanges() throws InterruptedException
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.
-
uploadAllLocalChanges
public boolean uploadAllLocalChanges(long timeout, TimeUnit unit) throws InterruptedException
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
- iftimeout
is less than or equal to0
orunit
isnull
.
-
start
public 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()
returnsSyncSession.State.ACTIVE
. If the session isSyncSession.State.DYING
, the session will be moved back toSyncSession.State.ACTIVE
.- See Also:
getState()
,stop()
-
stop
public 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.
-
-