Sync HomeBlogTwitterGitHub

Sync Client

How to create an ObjectBox Sync client and connect to an ObjectBox Sync server.

ObjectBox Sync enabled library

Prefer to look at example code? Check out our examples repository.

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, but will not provide any Sync logic due to the missing implementation.

If you have not used ObjectBox before, please also be aware of documentation for the standard (non-sync) edition of ObjectBox (the ObjectBox DB) 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.

It is assumed that you have been in contact 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.

Follow the Getting Started page instructions. Then change the applied Gradle plugin to the sync variant:

// This automatically adds the native dependency:
apply plugin: "io.objectbox.sync"  // instead of "io.objectbox"

This will automatically add the Sync variant of the required JNI library for your platform.

If needed, e.g. to publish a JVM app that supports multiple platforms or to add Linux ARM support, add the libraries manually:

// Android
implementation("io.objectbox:objectbox-sync-android:$objectboxVersion")

// JVM
implementation("io.objectbox:objectbox-sync-linux:$objectboxVersion")
implementation("io.objectbox:objectbox-sync-macos:$objectboxVersion")
implementation("io.objectbox:objectbox-sync-windows:$objectboxVersion")
// JVM Linux on ARM (not added automatically)
implementation("io.objectbox:objectbox-sync-linux-arm64:$objectboxVersion")       
implementation("io.objectbox:objectbox-sync-linux-armv7:$objectboxVersion")

Now it is time to verify the setup using a flag telling if Sync is available; for example, simply log the result:

import io.objectbox.sync.Sync;

String syncAvailable = Sync.isAvailable() ? "available" : "unavailable";
System.out.println("ObjectBox Sync is " + syncAvailable);

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:

@Sync
@Entity
public class User {
    // ...
}

Once the sync annotation is set on the intended types, you need to rebuild (e.g. Java/Kotlin) or trigger the ObjectBox generator (e.g. C and C++). This activates a "sync flag" in the metamodel (e.g. the model JSON file is updated).

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 if this is a scenario you encounter.

Additionally, there may only be relations between sync-enabled or non-sync entities, not across this 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:

SyncClient syncClient = Sync.client(
        boxStore, 
        "ws://127.0.0.1" /* Use wss for encrypted traffic. */, 
        SyncCredentials.none()
).buildAndStart(); // Connect and start syncing.

The example uses ws://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 is separate machines, you need to exchange 127.0.0.1 with a 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() or 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.

Should the client get disconnected, e.g. due to internet connection issues, it will automatically try to reconnect using an exponential back-off. Once the connection succeeds, data synchronization resumes.

Always close the client before closing the store. Closing the store with a still running sync client results in undefined behavior (e.g. crashes). Keep in mind that it typically is fine to leave the sync client and store open; once the application exits, they will be automatically closed properly.

Drop-off, send-only clients

For some use cases, a client should only report data and thus only send updates without ever receiving any data. We call those "drop-off clients". Technically, from an API perspective, these clients do not request updates from the server. Because requesting updates is the default, the sync client API has to be configured to do "manual" updates to actually disable updates from the server. This configuration has to happen before the client starts.

// C++; create syncClient as above, but do not start() just yet
syncClient->setRequestUpdatesMode(OBXRequestUpdatesMode_MANUAL);
syncClient->start();

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

There are currently multiple supported options for authenticating clients with a Sync server.

JWT authentication

Clients can be authenticated using tokens in JWT (JSON web token) format. The general process is outlined in the server-side JWT documentation. Your client application typically will use a JWT authentication provider SDK to get a token in JWT format. This token is then set as a credential using the ObjectBox Sync client API:

String idToken = "<your_jwt_id_token>"; // Get from JWT authentication provider
SyncCredentials credential = SyncCredentials.jwtIdToken(idToken);
// Options for other types of JWT are available:
// jwtAccessToken(token), jwtRefreshToken(token), jwtCustomToken(token)

Shared secret

This can be any pre-shared secret string or a byte sequence.

SyncCredentials credential = SyncCredentials.sharedSecret("<your_secret>");

Google Sign-In

The ObjectBox Sync server supports authenticating users using their Google account. This assumes Google Sign-In is integrated into your app and it has obtained the user's ID token.

SyncCredentials credential = SyncCredentials.google(account.getIdToken());

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.

SyncCredentials credential = SyncCredentials.none();

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.

// Just build the client.
SyncClient syncClient = Sync.client(...).build();

// Start now.
syncClient.start();

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.

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.

SyncLoginListener loginListener = new SyncLoginListener() {
    @Override
    public void onLoggedIn() {
        // Login succesful.
    }

    @Override
    public void onLoginFailed(long syncLoginCode) {
        // Login failed. Returns one of SyncLoginCodes.
    }
};

SyncCompletedListener completedListener = new SyncCompletedListener() {
    @Override
    public void onUpdatesCompleted() {
        // A sync has completed, client is up-to-date.
    }
};

SyncConnectionListener connectListener = new SyncConnectionListener() {
    @Override
    public void onDisconnected() {
        // Client disconnected from the server.
        // Depending on the configuration it will try to re-connect.
    }
};

// Set listeners when building the client.
SyncClient syncClient = Sync.client(...)
  .loginListener(loginListener)
  .completedListener(completedListener)
  .connectionListener(connectListener)
  .build();
  
// Set (or replace) a listener later.
syncClient.setSyncLoginListener(listener);

// Remove an existing listener.
syncClient.setSyncConnectionListener(null);

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.

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).

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 client.
syncBuilder.changeListener(changeListener);
// Or set the listener later.
syncClient.setSyncChangeListener(changeListener);

// Calling again replaces an existing listener.
syncClient.setSyncChangeListener(changeListener);
// Remove an existing listener.
syncClient.setSyncChangeListener(null);

Listeners concurrency

Some events may be issued in parallel, from multiple background threads. To help you understand when and how you need to take care of concurrency (e.g. use mutex/atomic variables), we've grouped the sync listeners to these two groups:

There can be only one event executed at any single moment from a listener in a single group. You can imagine this as if there were two parallel threads, one could only issue "state" events, the other only "data change" events.

Controlling sync updates behavior

By default, after the Sync client is logged in, its database is updated from the server and the client will automatically subscribe for any future changes. For advanced use cases, like unit testing, it is possible to control when the client receives data updates from the server.

To change the default behavior, configure the "Request Updates Mode" before starting the client connection. Three modes are available:

  • automatic (default): receives updates on login and subscribes for future updates.

  • automatic, but no pushes: receives updates on login but doesn't subscribe for future updates.

  • manual: no automatic updates on login or on any updates in the future.

When using one of the non-default modes, synchronization can be controlled after login during application runtime by requesting and cancelling updates using the client:

SyncClient syncClient = syncBuilder
        // Turn off automatic sync updates.
        .requestUpdatesMode(RequestUpdatesMode.MANUAL)
        .build();

// Wait for login attempt, proceed if logged in.
syncClient.awaitFirstLogin(20 * 1000 /* ms */);
if (syncClient.isLoggedIn()) {
    // Turn on automatic sync updates.
    syncClient.requestUpdates();
    
    // Turn off automatic sync updates, cancel ongoing sync.
    syncClient.cancelUpdates();
    
    // Request one-time update.
    // Will update client with latest data.
    syncClient.requestUpdatesOnce();
}
PreviousData SynchronizationNextSync Server

Last updated

Was this helpful?