SyncSession (Realm 5.7.0)

java.lang.Object
- io.realm.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 this SyncConfiguration closes their respective Realms.
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

Nested Classes
Modifier and Type	Class and Description
`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 and 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.
`SyncConfiguration`	`getConfiguration()` Returns the `SyncConfiguration` that is responsible for controlling the session.
`ConnectionState`	`getConnectionState()` Get the current state of the connection used by the session as defined in `ConnectionState`.
`URI`	`getServerUrl()` Returns the `URI` describing the remote Realm which this session connects to and synchronizes changes with.
`SyncSession.State`	`getState()` Get the current session's state, as defined in `SyncSession.State`.
`SyncUser`	`getUser()` Returns the `SyncUser` defined by the `SyncConfiguration` that is used to connect to the Realm Object Server.
`boolean`	`isConnected()` Checks if the session is connected to the server and can synchronize data.
`void`	`removeConnectionChangeListener(ConnectionListener listener)` Removes a previously registered `ConnectionListener`.
`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.

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

- Method Detail
  - getConfiguration
```
public SyncConfiguration getConfiguration()
```
    Returns the SyncConfiguration that is responsible for controlling the session.
    
    Returns:
    
    SyncConfiguration that defines and controls this session.
  - getUser
```
public SyncUser getUser()
```
    Returns the SyncUser defined by the SyncConfiguration that is used to connect to the Realm Object Server.
    
    Returns:
    
    SyncUser used to authenticate the session on the Realm Object Server.
  - 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, example: the authentication token will expire, causing the session to move to SyncSession.State.WAITING_FOR_ACCESS_TOKEN after it was in SyncSession.State.ACTIVE.
    
    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 in ConnectionState.
    
    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 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.
  - 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. See ProgressMode 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. See ProgressMode 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. See ConnectionState for further details.
    
    Parameters:
    
    listener - the listener to register.
    
    Throws:
    
    IllegalArgumentException - if the listener is null.
    
    See Also:
    
    ConnectionState
  - removeConnectionChangeListener
```
public void removeConnectionChangeListener(ConnectionListener listener)
```
    Removes a previously registered ConnectionListener.
    
    Parameters:
    
    listener - listener to remove
    
    Throws:
    
    IllegalArgumentException - if the listener is null.
  - 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.
  - 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 session has been started.
    
    Throws:
    
    IllegalStateException - if called on the Android main thread.
    
    InterruptedException - if the thread was interrupted while downloading was in progress.
  - 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() returns either SyncSession.State.ACTIVE or SyncSession.State.WAITING_FOR_ACCESS_TOKEN. If the session is SyncSession.State.DYING, the session will be moved back to SyncSession.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.

Class SyncSession

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getConfiguration

getUser

getServerUrl

getState

getConnectionState

isConnected

addDownloadProgressListener

addUploadProgressListener

removeProgressListener

addConnectionChangeListener

removeConnectionChangeListener

downloadAllServerChanges

uploadAllLocalChanges

start

stop