Java V4→V5 API Migration Guide

Overview

This guide covers the essential changes needed to migrate your Ditto Java app from v4 to v5. The main architectural shift is moving from identity-based initialization to a three-phase configuration model with CompletableFuture-based APIs. Also required: v5 uses DQL (Ditto Query Language) for all data operations. See the DQL Migration Guide for query migration steps.

AI Agent Prompt

Use this prompt when working with an AI coding assistant to migrate your Ditto Java app from v4 to v5.

Copy AI Migration Prompt (Click to Expand)

I need help migrating a Ditto Java application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace new Ditto() with DittoFactory.create(config) using Builder pattern
- Create DittoConfig with databaseId and connect mode
- OnlinePlayground → new DittoConfig.Connect.Server(...). Copy the URL from the Ditto Portal (Connect via SDK → **URL**) as-is — don't build it from the database ID.
- OfflinePlayground → new DittoConfig.Connect.SmallPeersOnly(null)
- Remove updateTransportConfig, disableSyncWithV3 calls
- IMPORTANT: If maintaining v4 behavior, set DQL_STRICT_MODE=true BEFORE starting sync

AUTHENTICATION:
Set setExpirationHandler callback after initialization
- Handler called when timeUntilExpiration == 0 (initial) or > 0 (refresh)
- Use DittoAuthenticationProvider.development() for playground tokens
- login() returns CompletableFuture with .thenAccept() and .exceptionally()

BEFORE (V4):
```java
Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);
ditto.updateTransportConfig(config -> {
    config.connect.webSocketURLs.add("wss://...");
});
ditto.disableSyncWithV3();
ditto.startSync();
```

AFTER (V5):
```java
DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .build();

Ditto ditto = DittoFactory.create(config);

ditto.getAuth().setExpirationHandler((expiringDitto, timeUntilExpiration) -> {
    expiringDitto.getAuth().login("your-token", DittoAuthenticationProvider.development())
        .thenAccept(clientInfo -> {
            System.out.println("Authentication successful");
        })
        .exceptionally(error -> {
            System.out.println("Authentication failed: " + error);
            return null;
        });
});

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = true", null);

ditto.getSync().start();
```

CHECKLIST:
- Replace new Ditto() with DittoFactory.create(config)
- Create DittoConfig with databaseId and connect
- Replace ditto.startSync() with ditto.getSync().start()
- Set DQL_STRICT_MODE=true BEFORE getSync().start() if maintaining v4 behavior
- Set setExpirationHandler for authentication
- Remove updateTransportConfig, disableSyncWithV3 calls
- Replace getPeerKeyString() with getPeerKey()

Work through the codebase systematically. Show me each file's changes.

Ditto Instance Initialization

v5 separates initialization into three distinct phases for better clarity and control:

// 1. Configure
DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .build();

// 2. Initialize
Ditto ditto = DittoFactory.create(config);

// 3. Authenticate
ditto.getAuth().setExpirationHandler((expiringDitto, timeUntilExpiration) -> {
    expiringDitto.getAuth().login("your-token", DittoAuthenticationProvider.development())
        .thenAccept(clientInfo -> {
            System.out.println("Authentication successful");
        })
        .exceptionally(error -> {
            System.out.println("Authentication failed: " + error);
            return null;
        });
});

// 4. Start sync
ditto.getSync().start();

// Everything mixed together
Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);

// Workarounds
ditto.updateTransportConfig(config -> {
    config.connect.webSocketURLs.add("wss://...");
});
ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false", null);
ditto.disableSyncWithV3();

ditto.startSync();

These changes provide:

Clear separation of connection, initialization, and authentication concerns
CompletableFuture-based async authentication
No workarounds needed (transport config, DQL strict mode, v3 sync disable)
Type-safe configuration with compile-time validation

Initialization Migration Steps

Replace Initialization

Replace new Ditto() constructor with DittoFactory.create(config).

DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .build();

Ditto ditto = DittoFactory.create(config);
// Set up auth handler before starting sync (see Step 2)
ditto.getSync().start();

Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);
ditto.startSync();

Key changes:

Use DittoConfig.Builder pattern instead of DittoIdentity
appId → databaseId
.OnlinePlayground → new DittoConfig.Connect.Server(...)
.OfflinePlayground → new DittoConfig.Connect.SmallPeersOnly(null)
Remove updateTransportConfig, disableSyncWithV3(), and DQL strict mode queries

Update Authentication

Set authentication handler separately after initialization.

// Set handler after DittoFactory.create()
ditto.getAuth().setExpirationHandler((expiringDitto, timeUntilExpiration) -> {
    if (timeUntilExpiration == 0) {
        // Initial auth
        expiringDitto.getAuth().login(
            "your-token",
            DittoAuthenticationProvider.development()
        ).thenAccept(clientInfo -> {
            System.out.println("Authentication successful");
        }).exceptionally(error -> {
            System.out.println("Authentication failed: " + error);
            return null;
        });
    } else {
        // Token refresh
        refreshToken(expiringDitto);
    }
});

// Auth mixed with identity
Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",  // Token in identity
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);

Key changes:

Authentication now uses setExpirationHandler callback
Handler called when auth required (timeUntilExpiration == 0) or token expiring
Use DittoAuthenticationProvider.development() for playground tokens
Custom auth: new DittoAuthenticationProvider("your-provider")

Additional Changes

DQL Strict Mode Behavior Change

Breaking Change: v5 defaults to DQL_STRICT_MODE=false, which fundamentally changes how DQL queries behave.

v4 default: Objects treated as REGISTER (whole-object replacement)
v5 default: Objects treated as MAP (field-level merging)

This affects the behavior of all DQL SELECT, INSERT, and UPDATE operations.

Choose the appropriate migration path based on your current v4 configuration:

Currently Using DQL with DQL_STRICT_MODE=true (v4 default)

If you’re currently using the v4 default (DQL_STRICT_MODE=true), you must explicitly set strict mode to true in v5 before starting sync or executing any queries.

Failing to set strict mode will cause objects to merge at the field level instead of replacing entirely, which can result in unexpected data behavior and perceived data loss.

To migrate to DQL_STRICT_MODE=false (the new v5 default), contact Ditto Customer Support for guidance.

DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .build();
Ditto ditto = DittoFactory.create(config);

// IMPORTANT: Set strict mode BEFORE starting sync or running queries
ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = true", null);

// Now safe to start sync
ditto.getSync().start();

Currently Using DQL with DQL_STRICT_MODE=false

If you explicitly set DQL_STRICT_MODE=false in v4, no changes are required.v5 uses DQL_STRICT_MODE=false as the default, so your existing DQL queries will behave identically. You can upgrade freely.Optional: You can remove the explicit ALTER SYSTEM SET DQL_STRICT_MODE = false statement in v5 since this is now the default behavior.

DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .build();
Ditto ditto = DittoFactory.create(config);

// No need to set DQL_STRICT_MODE - false is now the default
ditto.getSync().start();

Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);

// You explicitly set this in v4
ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false", null);

ditto.startSync();

Currently Using Legacy Query Builder

The Legacy Query Builder has been removed in v5. All queries must be converted to DQL before upgrading.Good news: Legacy Query Builder functionality has 1:1 support with DQL_STRICT_MODE=false (the v5 default), making migrations straightforward.Migration Steps:

In v4: Set DQL_STRICT_MODE=false after initialization:

Ditto ditto = new Ditto(
    new DittoIdentity.OnlinePlayground(
        context,
        "your-app-id",
        "your-token",
        false,
        "REPLACE_ME_WITH_YOUR_URL"
    )
);

// Set DQL_STRICT_MODE to false for Query Builder compatibility
ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false", null);

ditto.startSync();

Convert all queries from Legacy Query Builder to DQL See the Java Legacy→DQL Migration Guide for detailed conversion examples.
Upgrade to v5 No DQL configuration changes required—v5 defaults to DQL_STRICT_MODE=false.

Default Persistence Directory

v5 includes the database ID in the default directory name: ditto-{databaseId} instead of ditto To maintain v4 compatibility:

DittoConfig config = new DittoConfig.Builder("your-database-id")
    .connect(new DittoConfig.Connect.Server("REPLACE_ME_WITH_YOUR_URL"))
    .persistenceDirectory("/app/data/ditto")  // Old v4 path
    .build();

API Changes

ditto.startSync() → ditto.getSync().start()
ditto.stopSync() → ditto.getSync().stop()
ditto.isSyncActive() → ditto.getSync().isActive()
getPeerKeyString() → getPeerKey()
isConnectedToDittoCloud() → isConnectedToDittoServer()
new Ditto() → DittoFactory.create(config)

Migration Checklist

Initialization

Replace new Ditto() with DittoFactory.create(config)
Create DittoConfig with databaseId and connect mode
Update .OnlinePlayground → new DittoConfig.Connect.Server(...)
Update .OfflinePlayground → new DittoConfig.Connect.SmallPeersOnly(null)
Remove updateTransportConfig calls
Remove disableSyncWithV3() calls
Set DQL_STRICT_MODE=true BEFORE starting sync if maintaining v4 behavior

Authentication

Set setExpirationHandler callback after initialization
Use DittoAuthenticationProvider.development() for playground tokens
Remove authentication from identity configuration

Sync API

Update ditto.startSync() → ditto.getSync().start()
Update ditto.stopSync() → ditto.getSync().stop()
Remove disableSyncWithV3() calls

Breaking Changes

Set persistenceDirectory if maintaining v4 directory structure
Update getPeerKeyString() → getPeerKey()
Update isConnectedToDittoCloud() → isConnectedToDittoServer()

Verification

Build compiles with zero errors
No deprecated API warnings
Observers update data immediately
Authentication works before sync starts
No memory leaks

Release Notes DQL Migration Guide

⌘I

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Java V4→V5 API Migration Guide

Overview

AI Agent Prompt

Ditto Instance Initialization

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

API Changes

Migration Checklist

Initialization

Authentication

Sync API

Breaking Changes

Verification

​Overview

​AI Agent Prompt

​Ditto Instance Initialization

​Additional Changes

​DQL Strict Mode Behavior Change

​Default Persistence Directory

​API Changes

​Migration Checklist

​Initialization

​Authentication

​Sync API

​Breaking Changes

​Verification

Overview

AI Agent Prompt

Ditto Instance Initialization

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

API Changes

Migration Checklist

Initialization

Authentication

Sync API

Breaking Changes

Verification