Package io.objectbox.sync

Interface SyncClient

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
SyncClientImpl
public interface SyncClient extends Closeable
ObjectBox sync client. Build a client with Sync.client(io.objectbox.BoxStore, java.lang.String, io.objectbox.sync.SyncCredentials).

Keep the instance around (avoid garbage collection) while you want to have sync ongoing. For a clean shutdown, call close().

SyncClient is thread-safe.

  • Method Details

    • getServerUrl

      String getServerUrl()
      Gets the sync server URL this client is connected to.

    • isStarted

      boolean isStarted()
      Flag indicating if the sync client was started. Started clients try to connect, login, and sync with the sync destination.

    • isLoggedIn

      boolean isLoggedIn()
      Flag indicating if the sync client was started. Logged in clients can sync with the sync destination to exchange data.

    • getLastLoginCode

      long getLastLoginCode()
      Response code of last login attempt. One of SyncLoginCodes.

    • getServerTimeNanos

      long getServerTimeNanos()
      Estimates the current server timestamp in nanoseconds based on the last known server time.
      Returns:
      unix timestamp in nanoseconds (since epoch); or 0 if there has not been a server contact yet and thus the server's time is unknown

    • getServerTimeDiffNanos

      long getServerTimeDiffNanos()
      Returns the estimated difference in nanoseconds between the server time and the local timestamp. urns the difference in nanoseconds between the current local time of this client Equivalent to calculating getServerTimeNanos() - "current time" (nanos since epoch), except for when the server time is unknown, then the result is zero.
      Returns:
      time difference in nanoseconds; e.g. positive if server time is ahead of local time; or 0 if there has not been a server contact yet and thus the server's time is unknown

    • getRoundtripTimeNanos

      long getRoundtripTimeNanos()
      Returns the estimated roundtrip time in nanoseconds to the server and back. This is measured during login.
      Returns:
      roundtrip time in nanoseconds; or 0 if there has not been a server contact yet and thus the roundtrip time could not be estimated

    • setSyncLoginListener

      void setSyncLoginListener(@Nullable SyncLoginListener listener)
      Sets a listener to observe login events. Replaces a previously set listener. Set to null to remove the listener.

    • setSyncCompletedListener

      void setSyncCompletedListener(@Nullable SyncCompletedListener listener)
      Sets a listener to observe Sync completed events. Replaces a previously set listener. Set to null to remove the listener.

    • setSyncConnectionListener

      void setSyncConnectionListener(@Nullable SyncConnectionListener listener)
      Sets a listener to observe Sync connection events. Replaces a previously set listener. Set to null to remove the listener.

    • setSyncListener

      void setSyncListener(@Nullable SyncListener listener)
      Sets a listener to observe all Sync events. Replaces all other previously set listeners, except a SyncChangeListener. Set to null to remove the listener.

    • setSyncChangeListener

      void setSyncChangeListener(@Nullable SyncChangeListener listener)
      Sets a SyncChangeListener. Replaces a previously set listener. Set to null to remove the listener.

    • setSyncTimeListener

      void setSyncTimeListener(@Nullable SyncTimeListener timeListener)
      Sets a SyncTimeListener. Replaces a previously set listener. Set to null to remove the listener.

    • setLoginCredentials

      void setLoginCredentials(SyncCredentials credentials)
      Updates the credentials used to authenticate with the server. This should not be required during regular use. The original credentials were passed when building sync client.

    • setLoginCredentials

      void setLoginCredentials(SyncCredentials[] multipleCredentials)
      Like setLoginCredentials(SyncCredentials), but allows setting multiple credentials.

    • awaitFirstLogin

      boolean awaitFirstLogin(long millisToWait)
      Waits until the sync client receives a response to its first (connection and) login attempt or until the given time has expired. Use isLoggedIn() or getLastLoginCode() afterwards to determine if login was successful. Starts the sync if it is not already.
      Returns:
      true if a response was received in the given time window.

    • start

      void start()
      Starts the client. It will connect to the server, log in (authenticate) and start syncing.

    • stop

      void stop()
      Stops the client. Does nothing if the sync client is already stopped.

    • close

      void close()
      Closes and cleans up all resources used by this sync client. It can no longer be used afterwards, build a new sync client instead. Does nothing if this sync client has already been closed.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • requestUpdates

      boolean requestUpdates()
      Asks the sync server to resume sync updates. This is useful if sync updates were turned off with requestUpdatesMode(MANUAL).
      Returns:
      'true' if the request was likely sent (e.g. the sync client is in "logged in" state) or 'false' if the request was not sent (and will not be sent in the future)
      See Also:

    • requestUpdatesOnce

      boolean requestUpdatesOnce()
      Asks the server to send sync updates until this sync client is up-to-date, then pauses sync updates again. This is useful if sync updates were turned off with requestUpdatesMode(MANUAL).
      Returns:
      'true' if the request was likely sent (e.g. the sync client is in "logged in" state) or 'false' if the request was not sent (and will not be sent in the future)

    • cancelUpdates

      boolean cancelUpdates()
      Asks the server to pause sync updates.
      Returns:
      'true' if the request was likely sent (e.g. the sync client is in "logged in" state) or 'false' if the request was not sent (and will not be sent in the future)
      See Also:

    • requestFullSync

      @Experimental boolean requestFullSync()
      Experimental. This API might change or be removed in the future.

      Temporary only, try not to use it.

      Request a sync of all previous changes from the server.

      Returns:
      'true' if the request was likely sent (e.g. the sync client is in "logged in" state) or 'false' if the request was not sent (and will not be sent in the future).

    • notifyConnectionAvailable

      void notifyConnectionAvailable()
      Lets the sync client know that a working network connection is available.

      This can help speed up reconnecting to the sync server.

    • startObjectsMessage

      @Experimental ObjectsMessageBuilder startObjectsMessage(long flags, @Nullable String topic)
      Experimental. This API might change or be removed in the future.

      Start building a message of Objects with optional flags (set to 0) and topic (set to null).

      Use like 

       syncClient.startObjectsMessage(0, "some-topic")
     .addString(1, "Hello!")
     .addBytes(2, "Hello!".getBytes(StandardCharsets.UTF_8), false)
     .send();