io.realm

Class SyncManager

java.lang.Object

io.realm.SyncManager

public class SyncManager
extends Object

The SyncManager is the central controller for interacting with the Realm Object Server. It handles the creation of SyncSessions and it is possible to configure session defaults and the underlying network client using this class.

Through the SyncManager, it is possible to add authentication listeners. An authentication listener will response to events like user logging in or out.

Default error handling for any SyncConfiguration can be added using the SyncManager.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SyncManager.Debug Debugging related options.

Field Summary

Fields

Modifier and Type	Field and Description
static String	APP_ID APP ID sent to the Realm Object Server.
static ThreadPoolExecutor	NETWORK_POOL_EXECUTOR Thread pool used when doing network requests against the Realm Object Server.

Constructor Summary

Constructors

Constructor and Description
SyncManager()

Method Summary

Modifier and Type	Method and Description
static void	addAuthenticationListener(AuthenticationListener listener) Sets a global authentication listener that will be notified about User events like login and logout.
static void	addCustomRequestHeader(String headerName, String headerValue) Adds an extra HTTP header to append to every request to a Realm Object Server.
static void	addCustomRequestHeader(String headerName, String headerValue, String host) Adds an extra HTTP header to append to every request to a Realm Object Server.
static void	addCustomRequestHeaders(Map<String,String> headers) Adds extra HTTP headers to append to every request to a Realm Object Server.
static void	addCustomRequestHeaders(Map<String,String> headers, String host) Adds extra HTTP headers to append to every request to a Realm Object Server.
static String	getAuthorizationHeaderName(URI objectServerUrl) Returns the authentication header name used for the http request to the given url.
static Map<String,String>	getCustomRequestHeaders(URI serverSyncUrl) Returns all the custom headers added to requests to the given url.
static SyncSession	getOrCreateSession(SyncConfiguration syncConfiguration, URI resolvedRealmURL) Gets any cached SyncSession for the given SyncConfiguration or create a new one if no one exists.
static SyncSession	getSession(SyncConfiguration syncConfiguration) Gets a cached SyncSession for the given SyncConfiguration or throw if no one exists yet.
static UserStore	getUserStore()
static void	refreshConnections() Realm will automatically detect when a device gets connectivity after being offline and resume syncing.
static void	removeAuthenticationListener(AuthenticationListener listener) Removes the provided global authentication listener.
static void	setAuthorizationHeaderName(String headerName) Sets the name of the HTTP header used to send authorization data in when making requests to all Realm Object Servers used by the app.
static void	setAuthorizationHeaderName(String headerName, String host) Sets the name of the HTTP header used to send authorization data in when making requests to the Realm Object Server running on the defined host.
static void	setDefaultSessionErrorHandler(SyncSession.ErrorHandler errorHandler) Sets the default error handler used by all SyncConfiguration objects when they are created.
static void	setUserStore(UserStore userStore) Set the UserStore used by the Realm Object Server to save user information.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

APP_ID

public static String APP_ID

APP ID sent to the Realm Object Server. Is automatically initialized to the package name for the app.

NETWORK_POOL_EXECUTOR

public static ThreadPoolExecutor NETWORK_POOL_EXECUTOR

Thread pool used when doing network requests against the Realm Object Server.

This pool is only exposed for testing purposes and replacing it while the queue is not empty will result in undefined behaviour.

Constructor Detail

SyncManager

public SyncManager()

Method Detail

setUserStore

public static void setUserStore(UserStore userStore)

Set the UserStore used by the Realm Object Server to save user information. If no Userstore is specified SyncUser.current() will always return null.

Parameters:

userStore - UserStore to use.

Throws:

IllegalArgumentException - if userStore is null.

addAuthenticationListener

public static void addAuthenticationListener(AuthenticationListener listener)

Sets a global authentication listener that will be notified about User events like login and logout.

Parameters:

listener - listener to register.

Throws:

IllegalArgumentException - if listener is null.

removeAuthenticationListener

public static void removeAuthenticationListener(AuthenticationListener listener)

Removes the provided global authentication listener.

Parameters:

listener - listener to remove.

setDefaultSessionErrorHandler

public static void setDefaultSessionErrorHandler(SyncSession.ErrorHandler errorHandler)

Sets the default error handler used by all SyncConfiguration objects when they are created.

Parameters:

errorHandler - the default error handler used when interacting with a Realm managed by a Realm Object Server.

getSession

public static SyncSession getSession(SyncConfiguration syncConfiguration)
                              throws IllegalStateException

Gets a cached SyncSession for the given SyncConfiguration or throw if no one exists yet. A session should exist after you open a Realm with a SyncConfiguration.

Parameters:

syncConfiguration - configuration object for the synchronized Realm.

Returns:

the SyncSession for the specified Realm.

Throws:

IllegalArgumentException - if syncConfiguration is null.

IllegalStateException - if the session could not be found using the provided SyncConfiguration.

getOrCreateSession

public static SyncSession getOrCreateSession(SyncConfiguration syncConfiguration,
                                             URI resolvedRealmURL)

Gets any cached SyncSession for the given SyncConfiguration or create a new one if no one exists. Note: This is mainly for internal usage, consider using getSession(SyncConfiguration) instead.

Parameters:

syncConfiguration - configuration object for the synchronized Realm.

resolvedRealmURL - resolved Realm URL with the user specific part if not a global Realm.

Returns:

the SyncSession for the specified Realm.

Throws:

IllegalArgumentException - if syncConfiguration is null.

setAuthorizationHeaderName

public static void setAuthorizationHeaderName(String headerName)

Sets the name of the HTTP header used to send authorization data in when making requests to all Realm Object Servers used by the app. These servers must have been configured to expect a custom authorization header.

The default authorization header is named "Authorization".

Parameters:

headerName - name of the header.

Throws:

IllegalArgumentException - if a null or empty header is provided.

See Also:

Adding a custom proxy

setAuthorizationHeaderName

public static void setAuthorizationHeaderName(String headerName,
                                              String host)

Sets the name of the HTTP header used to send authorization data in when making requests to the Realm Object Server running on the defined host. This server must have been configured to expect a custom authorization header.

The default authorization header is named "Authorization".

Parameters:

headerName - name of the header.

host - if this is provided, the authorization header name will only be used on this particular host. Example of valid values: "localhost", "127.0.0.1" and "myinstance.us1.cloud.realm.io".

Throws:

IllegalArgumentException - if a null or empty header and/or host is provided.

See Also:

Adding a custom proxy

addCustomRequestHeader

public static void addCustomRequestHeader(String headerName,
                                          String headerValue)

Adds an extra HTTP header to append to every request to a Realm Object Server.

Parameters:

headerName - the name of the header.

headerValue - the value of header.

Throws:

IllegalArgumentException - if a non-empty headerName is provided or a null headerValue.

addCustomRequestHeader

public static void addCustomRequestHeader(String headerName,
                                          String headerValue,
                                          String host)

Adds an extra HTTP header to append to every request to a Realm Object Server.

Parameters:

headerName - the name of the header.

headerValue - the value of header.

host - if this is provided, this header will only be used on this particular host. Example of valid values: "localhost", "127.0.0.1" and "myinstance.us1.cloud.realm.io".

Throws:

IllegalArgumentException - If an non-empty headerName, headerValue or host is provided.

addCustomRequestHeaders

public static void addCustomRequestHeaders(Map<String,String> headers)

Adds extra HTTP headers to append to every request to a Realm Object Server.

Parameters:

headers - map of (headerName, headerValue) pairs.

Throws:

IllegalArgumentException - If any of the headers provided are illegal.

addCustomRequestHeaders

public static void addCustomRequestHeaders(Map<String,String> headers,
                                           String host)

Adds extra HTTP headers to append to every request to a Realm Object Server.

Parameters:

headers - map of (headerName, headerValue) pairs.

host - if this is provided, the this header will only be used on this particular host. Example of valid values: "localhost", "127.0.0.1" and "myinstance.us1.cloud.realm.io".

Throws:

IllegalArgumentException - If any of the headers provided are illegal.

getAuthorizationHeaderName

public static String getAuthorizationHeaderName(URI objectServerUrl)

Returns the authentication header name used for the http request to the given url.

Parameters:

objectServerUrl - Url to get header for.

Returns:

the authorization header name used by http requests to this url.

getCustomRequestHeaders

public static Map<String,String> getCustomRequestHeaders(URI serverSyncUrl)

Returns all the custom headers added to requests to the given url.

Returns:

all defined custom headers used when making http requests to the given url.

getUserStore

public static UserStore getUserStore()

refreshConnections

public static void refreshConnections()

Realm will automatically detect when a device gets connectivity after being offline and resume syncing.

However, as some of these checks are performed using incremental backoff, this will in some cases not happen immediately.

In those cases it can be beneficial to call this method manually, which will force all sessions to attempt to reconnect immediately and reset any timers they are using for incremental backoff.