Class DittoAuthenticator

java.lang.Object

com.ditto.java.DittoAuthenticator

public final class DittoAuthenticator
extends Object

Handles authentication with Ditto Cloud for remote synchronization. Use this class to log in to a remote authentication service when using an OnlineWithAuthentication or Online identity.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	DittoAuthenticator.ExpirationHandler	Handler for authentication expiration events.
static interface	DittoAuthenticator.LoginCallback	Callback invoked when a login operation completes.
static interface	DittoAuthenticator.LoginCallbackWithClientInfoJSON	Callback invoked when a login operation completes with client info.
static final record	DittoAuthenticator.LoginResult	Result of a login operation.
static interface	DittoAuthenticator.LogoutCleanup	Function to perform cleanup operations during logout.
static interface	DittoAuthenticator.StatusListener	Listener for authentication status changes.

Method Summary

Modifier and Type	Method	Description
@Nullable DittoAuthenticator.ExpirationHandler	getExpirationHandler()	Returns the current expiration handler, or null if none is set.
@NonNull DittoAuthenticationStatus	getStatus()	Returns the current authentication status.
@NonNull CompletionStage<DittoAuthenticator.LoginResult>	login(@NonNull String token, @NonNull DittoAuthenticationProvider provider)	Logs in to Ditto with a third-party authentication token.
DittoAsyncCancellable	login(@NonNull String token, @NonNull DittoAuthenticationProvider provider, @NonNull DittoAuthenticator.LoginCallbackWithClientInfoJSON callback)	Logs in to Ditto with a third-party authentication token using a callback.
@NonNull CompletionStage<DittoAuthenticator.LoginResult>	login(@NonNull String token, @NonNull String provider)	Logs in to Ditto with a third-party authentication token.
DittoAsyncCancellable	login(@NonNull String token, @NonNull String provider, @NonNull DittoAuthenticator.LoginCallbackWithClientInfoJSON callback)	Logs in to Ditto with a third-party authentication token using a callback.
void	logout()	Logs out of Ditto.
void	logout(@Nullable DittoAuthenticator.LogoutCleanup cleanup)	Logs out of Ditto with optional cleanup.
Flow.Publisher<DittoAuthenticationStatus>	observeStatus()	Returns a Flow Publisher that emits authentication status changes.
AutoCloseable	observeStatus(@NonNull DittoAuthenticator.StatusListener listener)	Observes authentication status changes using a listener.
void	setCallback(@NonNull DittoAuthenticationCallback callback)	Deprecated. This method is deprecated.
void	setExpirationHandler(@Nullable DittoAuthenticator.ExpirationHandler expirationHandler)	Sets a handler to be called when authentication is about to expire.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

setCallback

@Deprecated
public void setCallback(@NonNull DittoAuthenticationCallback callback)

Deprecated.

This method is deprecated. Use the following alternatives:

• For onAuthenticationExpiringSoon: Use setExpirationHandler(com.ditto.java.DittoAuthenticator.@org.checkerframework.checker.nullness.qual.Nullable ExpirationHandler)
• For onAuthenticationStatusDidChange: Use observeStatus()
• For onAuthenticationRequired: Check DittoAuthenticationStatus from observeStatus()

NOTE: legacy callback shouldn't be used together with setExpirationHandler(com.ditto.java.DittoAuthenticator.@org.checkerframework.checker.nullness.qual.Nullable ExpirationHandler).

This method will be removed in a future major version.

Sets the authentication callback to receive authentication events.

Parameters:

callback - the DittoAuthenticationCallback to be notified of authentication events.

getExpirationHandler

public @Nullable DittoAuthenticator.ExpirationHandler getExpirationHandler()

Returns the current expiration handler, or null if none is set.

Returns:

the current DittoAuthenticator.ExpirationHandler, or null.

setExpirationHandler

public void setExpirationHandler(@Nullable DittoAuthenticator.ExpirationHandler expirationHandler)

Sets a handler to be called when authentication is about to expire.

This handler is called when authentication is about to expire and allows you to perform login or other necessary actions before expiration.

Note: This handler must be set when using Server-based connectivity (DittoConfig.Connect.Server), or

invalid reference

Ditto.startSync

will throw a

DittoException.AuthenticationException with reason

invalid reference

ExpirationHandlerMissing

.

Parameters:

expirationHandler - the DittoAuthenticator.ExpirationHandler to handle expiring authentication, or null to clear.

getStatus

public @NonNull DittoAuthenticationStatus getStatus()

Returns the current authentication status.

Returns:

the current DittoAuthenticationStatus.

login

public @NonNull CompletionStage<DittoAuthenticator.LoginResult> login(@NonNull String token,
 @NonNull DittoAuthenticationProvider provider)

Logs in to Ditto with a third-party authentication token. The returned CompletionStage will complete once the login attempt finishes. The DittoAuthenticator.LoginResult contains optional client info JSON from the auth webhook and an error if the login failed.

Parameters:

token - the authentication token required to log in.

provider - the DittoAuthenticationProvider (development or custom).

Returns:

a CompletionStage that completes with the DittoAuthenticator.LoginResult.

login

public @NonNull CompletionStage<DittoAuthenticator.LoginResult> login(@NonNull String token,
 @NonNull String provider)

Logs in to Ditto with a third-party authentication token. The returned CompletionStage will complete once the login attempt finishes. The DittoAuthenticator.LoginResult contains optional client info JSON from the auth webhook and an error if the login failed.

Parameters:

token - the authentication token required to log in.

provider - the name of the authentication provider.

Returns:

a CompletionStage that completes with the DittoAuthenticator.LoginResult.

login

public DittoAsyncCancellable login(@NonNull String token,
 @NonNull String provider,
 @NonNull DittoAuthenticator.LoginCallbackWithClientInfoJSON callback)

Logs in to Ditto with a third-party authentication token using a callback.

Parameters:

token - the authentication token required to log in.

provider - the name of the authentication provider.

callback - the DittoAuthenticator.LoginCallbackWithClientInfoJSON to be called when login completes.

Returns:

a DittoAsyncCancellable that can be used to cancel the login attempt.

login

public DittoAsyncCancellable login(@NonNull String token,
 @NonNull DittoAuthenticationProvider provider,
 @NonNull DittoAuthenticator.LoginCallbackWithClientInfoJSON callback)

Logs in to Ditto with a third-party authentication token using a callback.

Parameters:

token - the authentication token required to log in.

provider - the DittoAuthenticationProvider (development or custom).

callback - the DittoAuthenticator.LoginCallbackWithClientInfoJSON to be called when login completes.

Returns:

a DittoAsyncCancellable that can be used to cancel the login attempt.

logout

public void logout()

Logs out of Ditto. This will stop sync, shut down all replication sessions, and remove any cached authentication credentials. Note that this does not remove any data from the store.

logout

public void logout(@Nullable DittoAuthenticator.LogoutCleanup cleanup)

Logs out of Ditto with optional cleanup. This will stop sync, shut down all replication sessions, and remove any cached authentication credentials. The optional cleanup function allows you to perform any required cleanup of the store as part of the logout process.

Parameters:

cleanup - an optional DittoAuthenticator.LogoutCleanup function to perform cleanup operations.

observeStatus

public Flow.Publisher<DittoAuthenticationStatus> observeStatus()

Returns a Flow Publisher that emits authentication status changes.

Returns:

a Flow.Publisher that emits DittoAuthenticationStatus updates.

observeStatus

public AutoCloseable observeStatus(@NonNull DittoAuthenticator.StatusListener listener)

Observes authentication status changes using a listener.

Parameters:

listener - the DittoAuthenticator.StatusListener to be notified of status changes.

Returns:

an AutoCloseable that can be used to stop observing.