Comment on page
Embedded Sync Server
How to set up an ObjectBox Sync server that is embedded in your application.
This page refers to the embedded sync server, not the standalone sync server.
Usually, you want to use the standalone server.
By now, you were likely in touch with the ObjectBox team and were given Sync Server library artifacts. To use them in a Gradle project they have to be included as a local binary dependency. And the ObjectBox plugin has to be prevented from adding conflicting dependencies.
Copy the AAR and JAR files to the
<module_name>/libs directory (the path is relative to the build.gradle file), then modify build.gradle:Groovy
Kotlin
// Prevent the ObjectBox plugin from adding dependencies without Sync server.
configurations {
implementation {
exclude group: "io.objectbox", module: "objectbox-android"
exclude group: "io.objectbox", module: "objectbox-linux"
}
}
dependencies {
// Add any .aar and .jar file from <module_name>/libs as a dependency.
implementation fileTree(dir: "libs", include: ["*.aar", "*.jar"])
}
apply plugin: "io.objectbox.sync"
// Prevent the ObjectBox plugin from adding dependencies without Sync server.
configurations {
"implementation" {
exclude(group = "io.objectbox", module = "objectbox-android")
exclude(group = "io.objectbox", module = "objectbox-linux")
}
}
dependencies {
// Add any .aar and .jar file from <module-dir>/libs as a dependency.
implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar", "*.jar"))))
}
apply(plugin = "io.objectbox.sync")
Use
Sync.server(boxStore, url, authenticatorCredentials) to start a Sync server using a boxStore . The server binds to the address and port given in url.When using
wss as the protocol of the url a TLS encrypted connection is established. Use certificatePath(path) to supply a path to a certificate in PEM format. Use ws instead to turn off transport encryption (insecure, only use for testing!).authenticatorCredentials are required to authenticate clients. It is possible to add more than one set of allowed credentials.Java
C++
SyncServer syncServer = Sync.server(
boxStore,
"wss://0.0.0.0:9999" /* Use ws for unencrypted traffic. */,
SyncCredentials.sharedSecret("<secret>")
) // Builder...
.certificatePath(certPath) // Server PEM certificate
.authenticatorCredentials(cred2) // Additional credentials
.buildAndStart();
// Developer options; use wss and real credentials in production...
obx::SyncServer server(std::move(storeOptions), "ws://0.0.0.0:9999");
server.setCredentials(obx::SyncCredentials::none());
server.start();
obx::Store& store = server.store();
During
buildAndStart() the server will start and become ready to accept connections from clients. Read below for more configuration options you can use before starting the connection. These are the currently supported options to authenticate clients:
SyncCredentials credentials = SyncCredentials.sharedSecret("<secret>");
This can be any pre-shared secret string or a byte sequence.
Not available, yet.
Never use this option to serve an app shipped to customers. It is inherently insecure and allows anyone to access the sync server.
SyncCredentials credentials = SyncCredentials.none();
For development and testing it is often easier to just have no authentication at all to quickly get things up and running.
Using the example above, the server automatically binds to the given address and port and starts listening for clients. It is also possible to just build the server and then start it once your code is ready to.
// Just build the server.
SyncServer syncServer = Sync.server(...).build();
// Start now.
syncServer.start();
Note that a started server can not be started again. Stop and close an existing server and build a new one instead.
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.
To listen to these incoming data changes:
SyncChangeListener changeListener = syncChanges -> {
for (SyncChange syncChange : syncChanges) {
// This is equal to Example_.__ENTITY_ID.
long entityId = syncChange.getEntityTypeId();
// The @Id values of changed and removed entities.
long[] changed = syncChange.getChangedIds();
long[] removed = syncChange.getRemovedIds();
}
};
// Set the listener when building the server.
syncBuilder.changeListener(changeListener);
// Or set the listener later.
syncServer.setSyncChangeListener(changeListener);
// Calling again replaces an existing listener.
syncServer.setSyncChangeListener(changeListener);
// Remove an existing listener.
syncServer.setSyncChangeListener(null);
On each sync update received on the server, 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.
Before using peer servers, please reach out to the ObjectBox team.
It is possible to have multiple sync servers for redundancy and load balancing where one or more secondary servers connect as special clients to a primary server.
To add the primary server when building a secondary server:
syncBuilder.peer(primaryServerUrl, SyncCredentials.sharedSecret("<secret>"));
Last modified 1yr ago