How to create an ObjectBox Sync client and connect to an ObjectBox Sync server.
ObjectBox Sync enabled library
The standard ObjectBox (database) library does not include an ObjectBox Sync implementation. Depending on the programming language, it will include the Sync API, but not the implementation. For example, ObjectBox Java in its standard version allows compiling using the Sync API, it won't any Sync logic due to the missing implementation.
If you haven't used ObjectBox before, please also be aware of documentation for the standard (non-sync) edition of ObjectBox for your programming language (Java/Kotlin, Swift, C and C++, Go). You are currently looking at the documentation specific to ObjectBox Sync, which does not cover ObjectBox basics.
By now, you were likely in touch with the ObjectBox team and have access to Sync Server and potentially a special Sync Client version. For some platforms, we maintain packages that you can include as dependencies.
Java/Kotlin (Gradle)
Swift
Flutter
Dart
C/C++
Go
Others
Version 3.0.1 has some important bug fixes for Sync, we recommend to update to this version.
This gives you specific information about how to get the Sync-enabled version of ObjectBox. Please also check our general installation and update docs for in-depth information.
We may distribute ObjectBox Sync for Swift in our Cocoapods staging repository (we let you know). In that case, these are some typical lines to put in your Podfile (please check the version, there might be a newer one available):
System.out.println("ObjectBox Sync is "+ syncAvailable);
Copied!
1
import io.objectbox.sync.Sync
2
3
val syncAvailable =if(Sync.isAvailable())"available"else"unavailable"
4
Log.d(App.TAG,"ObjectBox Sync is $syncAvailable")
Copied!
1
Sync.isAvailable()
Copied!
1
Sync.isAvailable()
Copied!
1
obx::Sync::isAvailable()
Copied!
1
obx_has_feature(OBXFeature_Sync)
Copied!
1
objectbox.SyncIsAvailable()
Copied!
1
// Depending on the platform something like:
2
Sync.isAvailable()
Copied!
Enable your Objects for ObjectBox Sync
ObjectBox Sync allows you to define which objects are synced and which are not. This is done at an object type level (a "class" in many programming languages). By default, an object (type) is local only: objects are kept in the database on the local device and do not get synced to other devices.
To enable sync for an object type, you add a "sync" annotation to the type definition. This is typically the entity source file, or, if you are using ObjectBox Generator, the FlatBuffers schema file:
Java
Kotlin
Swift
Dart/Flutter
C/C++ (using Generator)
Go
1
@Sync
2
@Entity
3
publicclassUser{
4
// ...
5
}
Copied!
1
@Sync
2
@Entity
3
dataclassUser(
4
// ...
5
)
Copied!
1
// objectbox: sync
2
classUser:Entity{
3
...
4
}
Copied!
1
@Entity
2
@Sync
3
classUser{
4
...
5
}
Copied!
1
/// objectbox: sync
2
table User {
3
...
4
}
Copied!
1
// `objectbox:"sync"`
2
type User struct{
3
// ...
4
}
Copied!
At this point, it is not allowed to change a non-synced object type to a synced one. This would raise questions on how to handle pre-existing data, e.g. should it be deleted, synced (how exactly? using how many transactions? ...), or kept locally until objects are put again? We welcome your input on your use case.
Additionally, there may only be relations between sync-enabled or non-sync entities, not across the boundary.
If you already have a non-synced type that you now want to sync (see also the info box above), these are the typical options you have:
1.
If you are still in development, add the sync annotation and wipe your database(s) to start fresh with that new data model
2.
"Replace" the entity type using a new UID (check schema changes docs for the ObjectBox binding you are using). You can keep the type name; to ObjectBox it will be a different type as the UID is different. This will delete all existing data in that type.
3.
Have a second, synced, object type and migrate your data in your code following your rules.
Start the Sync Client
Create a Sync client for your Store and start it. It connects to a given sync server URL using some form of credentials to authenticate with the server. A minimal setup can look like this:
Java
Kotlin
Swift
Dart/Flutter
C++
C
Go
1
SyncClient syncClient =Sync.client(
2
boxStore,
3
"ws://127.0.0.1"/* Use wss for encrypted traffic. */,
4
SyncCredentials.none()
5
).buildAndStart();// Connect and start syncing.
Copied!
1
val syncClient = Sync.client(
2
boxStore,
3
"ws://127.0.0.1"/* Use wss for encrypted traffic. */,
obx_sync_start(sync_client);// connect and start syncing
Copied!
1
syncClient, err := objectbox.NewSyncClient(
2
store,
3
"ws://127.0.0.1",// wss for SSL, ws for unencrypted traffic
4
objectbox.SyncCredentialsNone())
5
6
if err !=nil{
7
err = syncClient.Start()// Connect and start syncing.
8
}
Copied!
The example uses wss://127.0.0.1 for the server endpoint. This is the IP address of localhost and assumes that you run the server and client(s) on the same machine. If it's separate machines, you need to exhange 127.0.0.1 with an reachable IP address of the server, or, some valid DNS name.
Using Android emulator? You can use 10.0.2.2 to reach the host (the machine running the emulator). Details
Sync client is started by calling start()/buildAndStart(). It will then try to connect to the server, authenticate and start syncing. Read below for more configuration options you can use before starting the connection.
Once the client is logged in, the server will push any changes it has missed. The server will also push any future changes while the client remains connected. This sync updates behavior can be configured.
All of this happens asynchronously. To observe these events (log in, sync completed, …) read below on how to configure an event listener.
The client will now also push changes to the server for each Store transaction.
Note: For various reasons, ensure to limit transaction size to around 120 KB (e.g. watch out for BLOB data like pictures). With compression, this limit may be higher depending on your data.
If you cannot avoid large transaction sizes, please reach out to us.
Should the client get disconnected, e.g. due to internet connection issues, it will automatically try to reconnect using an exponential backoff. Once the connection suceeds, data synchronization resumes.
Secure Connection
When using wss as the protocol in the server URL a TLS encrypted connection is established. Use ws instead to turn off transport encryption (insecure, not recommended! e.g. only use for testing).
Authentication options
These are the currently supported options for authentication with a sync server:
var creds = objectbox.SyncCredentialsGoogleAuth([]byte("string"))
3
4
// or a byte vector
5
var secret =[]byte{0,46,79,193,185,65,73,239,15,5,189,186}
6
var creds = objectbox.SyncCredentialsGoogleAuth(secret)
Copied!
The ObjectBox sync server supports authenticating users using their Google account. This assumes Google Sign-In is integrated into the app and it has obtained the user's ID token.
No authentication (insecure)
Never use this option in an app shipped to customers. It is inherently insecure and allows anyone to connect to the sync server.
For development and testing, it is often easier to just have no authentication at all to quickly get things up and running.
Manually start
Using the example above, the sync client automatically connects to the server and starts to sync. It is also possible to just build the client and then start to sync once your code is ready to.
Java
Kotlin
1
// Just build the client.
2
SyncClient syncClient =Sync.client(...).build();
3
4
// Start now.
5
syncClient.start();
Copied!
1
// Just build the client.
2
val syncClient = Sync.client(...).build()
3
4
// Start now.
5
syncClient.start()
Copied!
Note that a started sync client can not be started again. Stop and close an existing one and build a new one instead.
Listening to events
The sync client supports listening to various events, e.g. if authentication has failed or if the client was disconnected from the server. This enables other components of an app, like the user interface, to react accordingly.
Java
Kotlin
Swift
Dart/Flutter
C++
C
Go
It's possible to set one or more specific listeners that observe some events, or a general listener that observes all events. When building a Sync client use:
loginListener(listener) to observe login events.
completedListener(listener) to observe when synchronization has completed.
connectionListener(listener) to observe connection events.
listener(listener) to observe all of the above events. Use AbstractSyncListener and only override methods of interest to simplify your listener implementation.
See the description of each listener class and its methods for details.
Note that listeners can also be set or removed at any later point using SyncClient.setSyncListener(listener) and related methods.
// Depending on the configuration it will try to re-connect.
25
}
26
};
27
28
// Set listeners when building the client.
29
SyncClient syncClient =Sync.client(...)
30
.loginListener(loginListener)
31
.completedListener(completedListener)
32
.connectionListener(connectListener)
33
.build();
34
35
// Set (or replace) a listener later.
36
syncClient.setSyncLoginListener(listener);
37
38
// Remove an existing listener.
39
syncClient.setSyncConnectionListener(null);
Copied!
It's possible to set one or more specific listeners that observe some events, or a general listener that observes all events. When building a Sync client use:
loginListener(listener) to observe login events.
completedListener(listener) to observe when synchronization has completed.
connectionListener(listener) to observe connection events.
listener(listener) to observe all of the above events. Use AbstractSyncListener and only override methods of interest to simplify your listener implementation.
See the description of each listener class and its methods for details.
Note that listeners can also be set or removed at any later point using SyncClient.setSyncListener(listener) and related methods.
1
val loginListener: SyncLoginListener =object: SyncLoginListener {
2
overridefunonLoggedIn(){
3
// Login succesful.
4
}
5
6
overridefunonLoginFailed(syncLoginCode: Long){
7
// Login failed. Returns one of SyncLoginCodes.
8
}
9
}
10
11
val completedListener = SyncCompletedListener {
12
// A sync has completed, client is up-to-date.
13
}
14
15
val connectListener =object: SyncConnectionListener {
16
overridefunonDisconnected(){
17
// Client disconnected from the server.
18
// Depending on the configuration it will try to re-connect.
19
}
20
}
21
22
// Set listeners when building the client.
23
val syncClient = Sync.client(...)
24
.loginListener(loginListener)
25
.completedListener(completedListener)
26
.connectionListener(connectListener)
27
.build()
28
29
// Set (or replace) a listener later.
30
syncClient.setSyncLoginListener(listener)
31
32
// Remove an existing listener.
33
syncClient.setSyncConnectionListener(null)
Copied!
It's possible to set one or more specific listeners that observe some events, or a general listener that observes all events. The SyncClient protocol offers the following properties to attach listeners:
loginListener to observe login events.
completedListener to observe when synchronization has completed.
connectionListener to observe connection events.
listener to observe all of the above events.
There is a protocol for each listener type. Note that listeners can also be set or removed at any later point by setting the listener property to nil.
By implementing a listener protocol and setting the matching property in SyncClient, you are called back. Let's have a look at the available listener protocols for details:
1
/// Listens to login events.
2
publicprotocolSyncLoginListener{
3
/// Called on a successful login.
4
///
5
/// At this point the connection to the sync destination was established and
6
/// entered an operational state, in which data can be sent both ways.
7
funcloggedIn()
8
9
/// Called on a login failure with a `result` code specifying the issue.
10
funcloginFailed(result:SyncCode)
11
}
12
13
/// Listens to sync completed events.
14
publicprotocolSyncCompletedListener{
15
/// Called each time a sync was "completed", in the sense that the client
16
/// caught up with the current server state. The client is "up-to-date".
17
funcupdatesCompleted()
18
}
19
20
/// Listens to sync connection events.
21
publicprotocolSyncConnectionListener{
22
/// Called when connection is established; happens before an actual login
23
funcconnected()
24
25
/// Called when the client is disconnected from the sync server, e.g. due to a network error.
26
///
27
/// Depending on the configuration, the sync client typically tries to reconnect automatically,
28
/// triggering a `SyncLoginListener` again.
29
funcdisconnected()
30
}
31
32
/// Listens to all possible sync events. See each protocol for detailed information.
It's possible to listen to sync-related events on the client. Use the following SyncClient getters to connect to a stream:
Stream<SyncLoginEvent> get loginEvents - such as logged-in, credentials-rejected.
Stream<void> get completionEvents to observe when synchronization has completed.
Stream<SyncConnectionEvent> get connectionEvents to observe connection events.
Note that these streams don't buffer events so unless you're subscribed, no events are collected. Additionally, don't forget to cancel the subscription when you don't care about the information anymore, to free up resources.
1
final client = Sync.client(...);
2
final subscription = client.loginEvents.listen((SycnLoginEvent event){
3
if(event == SyncLoginEvent.loggedIn)print('Logged in successfully');
4
});
5
6
client.start();
7
8
...
9
10
// don't forget unsubscribe if you don't care about the events anymore
// there can be only one listener of a given type, so calling again with a
4
// different callback changes the listener (un-assigns the previous one)
5
syncClient.SetLoginListener(func(){...})
6
7
// reset (remove) a listener
8
syncClient.SetLoginListener(nil)
Copied!
Advanced
Listening to incoming data changes
For advanced use cases, it might be useful to know exactly which objects have changed during an incoming sync update. This is typically not necessary, as observing a box or a query may be easier.
On each sync update received on the client, the listener is called with an array of "Sync Change" objects, one for each affected entity type. It includes a list of affected object IDs - the ones that were put or removed in the incoming update.
Java
Kotlin
Swift
Dart/Flutter
C++
C
Go
Use changeListener(changeListener) when building the client and pass a SyncChangeListener to receive detailed information for each sync update. Or set or remove it at any later point using SyncClient.setSyncChangeListener(changeListener).
// The @Id values of changed and removed entities.
6
long[] changed = syncChange.getChangedIds();
7
long[] removed = syncChange.getRemovedIds();
8
}
9
};
10
// Set the listener when building the client.
11
syncBuilder.changeListener(changeListener);
12
// Or set the listener later.
13
syncClient.setSyncChangeListener(changeListener);
14
15
// Calling again replaces an existing listener.
16
syncClient.setSyncChangeListener(changeListener);
17
// Remove an existing listener.
18
syncClient.setSyncChangeListener(null);
Copied!
Use changeListener(changeListener) when building the client and pass a SyncChangeListener to receive detailed information for each sync update. Or set or remove it at any later point using SyncClient.setSyncChangeListener(changeListener).
1
val changeListener = SyncChangeListener { syncChanges ->
2
for(syncChange in syncChanges){
3
// This is equal to Example_.__ENTITY_ID.
4
val entityId = syncChange.entityTypeId
5
// The @Id values of changed and removed entities.
6
val changed = syncChange.changedIds
7
val removed = syncChange.removedIds
8
}
9
}
10
// Set the listener when building the client.
11
syncBuilder.changeListener(changeListener)
12
// Or set the listener later.
13
syncClient.setSyncChangeListener(changeListener)
14
15
// Calling again replaces an existing listener.
16
syncClient.setSyncChangeListener(changeListener)
17
// Remove an existing listener.
18
syncClient.setSyncChangeListener(null)
Copied!
Coming soon!
Use Stream<List<SyncChange>> get changeEvents on the SyncClient to receive detailed information for each sync update. Make sure to cancel the subscription when you don't need the information anymore to clear up resources.