Class Ditto

java.lang.Object
com.ditto.java.Ditto
All Implemented Interfaces:
DittoResource
public final class Ditto extends Object implements DittoResource

Ditto is the entrypoint for accessing Ditto-related functionality in the Java SDK.

To construct an instance of Ditto, use DittoFactory.create(DittoConfig).

Ditto provides access to:

  • Method Details

    • getAbsolutePersistenceDirectory

      public @NonNull String getAbsolutePersistenceDirectory()

      The absolute path to the persistence directory used by Ditto to persist data. This property returns the final, resolved absolute file path where Ditto stores its data. The value depends on what was provided in DittoConfig.Builder.persistenceDirectory(String):

      • If an absolute path was provided, it returns that path unchanged
      • If a relative path was provided, it returns the path resolved relative to the default root directory
      • If null was provided, it returns the default path This property always returns a consistent value throughout the lifetime of the Ditto instance and represents the actual directory being used for persistence. Note: It is not recommended to directly read from or write to this directory as its structure and contents are managed by Ditto and may change in future versions.
      Returns:
      the absolute path to the persistence directory.

    • getDeviceName

      public @NonNull String getDeviceName()
      Returns the custom identifier used for this peer.
      Returns:
      Custom identifier used for this peer.
      See Also:

    • setDeviceName

      public void setDeviceName(@NonNull String deviceName)
      Configure a custom identifier for this peer. When using DittoPresence, each remote peer is represented by a short UTF-8 "device name". By default, this will be the name of the hardware model (Android) or the network hostname (Java). Changes to this property after startSync() was called will only take effect after the next restart of sync. The value does not need to be unique among peers. Device names longer than 24 bytes will be truncated once startSync() is called.
      Parameters:
      deviceName - the custom identifier for this peer.
      See Also:

    • getPresence

      public @NonNull DittoPresence getPresence()
      Provides access to the SDK's presence functionality.
      Returns:
      a DittoPresence instance for managing presence operations.

    • getCallback

      public @Nullable DittoTransportConditionChangedCallback getCallback()
      Returns the current transport condition changed callback.
      Returns:
      the DittoTransportConditionChangedCallback if set, null otherwise.
      See Also:

    • setCallback

      public void setCallback(@NonNull DittoTransportConditionChangedCallback callback)
      Sets an optional callback that will be called with lifecycle events relating to the SDK.
      Parameters:
      callback - the callback to be notified of transport condition changes.
      See Also:

    • isActivated

      public boolean isActivated()
      Returns a flag indicating whether the SDK has been activated with a valid license token.
      Returns:
      true if the SDK has been activated, false otherwise.
      See Also:

    • isSyncActive

      public boolean isSyncActive()
      Returns a flag indicating whether sync is active. Use startSync() to activate and stopSync() to deactivate sync.
      Returns:
      true if sync is active, false otherwise.

    • getTransportConfig

      public @NonNull DittoTransportConfig getTransportConfig()
      Returns the current transport configuration.
      Returns:
      the current DittoTransportConfig instance.
      See Also:

    • getConfig

      public @NonNull DittoConfig getConfig()
      Returns the configuration used to initialize this Ditto instance. Note: Sensitive data such as passphrases and private keys are redacted from the returned configuration and replaced with the string "[REDACTED]".
      Returns:
      the DittoConfig instance used to create this Ditto object.

    • setTransportConfig

      public void setTransportConfig(@NonNull DittoTransportConfig transportConfig)
      Assigns a new transports configuration. By default peer-to-peer transports (Bluetooth and WiFi) are enabled. You may use this method to alter the configuration at any time. Sync will not begin until startSync() is called.
      Parameters:
      transportConfig - the new transport configuration to apply.
      See Also:

    • getAuth

      public @Nullable DittoAuthenticator getAuth()
      Provides access to authentication information and methods for logging on to Ditto Cloud.
      Returns:
      a DittoAuthenticator instance if authentication is configured, null otherwise.

    • getDiskUsage

      public @NonNull DittoDiskUsage getDiskUsage()
      Provides access to the SDK's disk usage monitoring.
      Returns:
      a DittoDiskUsage instance for monitoring disk usage.

    • getSdkVersion

      public @NonNull String getSdkVersion()
      Returns a string of version metadata for the Ditto SDK.
      Returns:
      a string containing version metadata. Example: "And4.4.3_73d36"

    • startSync

      public void startSync() throws DittoException
      Starts the network transports. Ditto will connect to other devices. By default, Ditto will enable all peer-to-peer transport types available. The default network configuration can be modified via the setTransportConfig(DittoTransportConfig) method. Performance of initial sync when bootstrapping a new peer can be improved by calling disableSyncWithV3() before calling startSync(). Only do this when all peers in the mesh are known to be running Ditto v4 or higher.
      Throws:
      DittoException - Thrown if the Ditto instance hasn't been activated by a successful call to setOfflineOnlyLicenseToken(String).
      See Also:

    • stopSync

      public void stopSync()
      Stops all network transports. You may continue to use the Ditto store locally, but no data will sync to or from other devices.
      See Also:

    • setOfflineOnlyLicenseToken

      public void setOfflineOnlyLicenseToken(@NonNull String licenseToken) throws DittoException
      Activates an offline Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it. The offline license token is only valid for manual, offlinePlayground, and sharedKey identities.
      Parameters:
      licenseToken - the license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).
      Throws:
      DittoException - thrown if the provided licenseToken is expired or invalid.
      See Also:

    • getTransportDiagnostics

      public @NonNull DittoTransportDiagnostics getTransportDiagnostics()
      Requests bulk status information about the transports. This is mostly intended for statistical or debugging purposes.
      Returns:
      an instance of DittoTransportDiagnostics that represents the current state of the network transports that the SDK is using.

    • getStore

      public @NonNull DittoStore getStore()
      Provides access to store-related functionality.
      Returns:
      a DittoStore instance for managing documents and collections.

    • getSync

      public @NonNull DittoSync getSync()
      Provides access to sync-related functionality.
      Returns:
      a DittoSync instance for managing sync subscriptions.

    • refreshPermissions

      public void refreshPermissions()
      Provides a hint to Ditto that app permissions may have changed. If your Activity requests a permission that is relevant to Ditto, such as location access, it is recommended to call this method from onRequestPermissionsResultCallback(). This allows Ditto to detect the new permissions sooner and begin syncing.

    • updateTransportConfig

      public void updateTransportConfig(@NonNull Ditto.UpdateTransportConfig configure)
      Convenience method to update the current transport config of the receiver. Invokes the lambda expression with a copy of the current transport config which you can alter to your liking. The updated transport config is then set upon the receiver. You may use this method to alter the configuration at any time. Sync will not begin until startSync() is invoked.
      Parameters:
      configure - a functional interface that receives a DittoTransportConfig.Builder to modify the transport configuration.
      See Also:

    • close

      public void close()
      Shuts down Ditto and releases all resources. Must be called before recreating a Ditto instance that uses the same persistence directory.
      Specified by:
      close in interface DittoResource

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object