Merge branch '252-jwt-and-multi-credentials-fixes' into 'dev'

JWT and multi-credential API fixes and improvements #252

See merge request objectbox/objectbox-java!154

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/sync/Sync.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -64,13 +64,9 @@ public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials
     }
 
     /**
-     * Starts building a {@link SyncClient}. Once done, complete with {@link SyncBuilder#build() build()}.
+     * Like {@link #client(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods.
      *
-     * @param boxStore The {@link BoxStore} the client should use.
-     * @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
-     * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
-     * {@code ws://127.0.0.1:9999}.
-     * @param multipleCredentials An array of {@link SyncCredentials} to be used to authenticate the user.
+     * @param multipleCredentials An array of {@link SyncCredentials} to be used to authenticate with the server.
      */
     public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials[] multipleCredentials) {
         return new SyncBuilder(boxStore, url, multipleCredentials);
@@ -87,24 +83,16 @@ public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials[
      * {@code ws://0.0.0.0:9999}.
      * @param authenticatorCredentials An authentication method available to Sync clients and peers. Additional
      * authenticator credentials can be supplied using the returned builder. For the embedded server, currently only
-     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
+     * {@link SyncCredentials#sharedSecret}, any JWT method like {@link SyncCredentials#jwtIdTokenServer()} as well as
+     * {@link SyncCredentials#none} are supported.
      */
     public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials authenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, authenticatorCredentials);
     }
 
     /**
-     * Starts building a {@link SyncServer}. Once done, complete with {@link SyncServerBuilder#build() build()}.
-     * <p>
-     * Note: when also using Admin, make sure it is started before the server.
-     *
-     * @param boxStore The {@link BoxStore} the server should use.
-     * @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
-     * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
-     * {@code ws://0.0.0.0:9999}.
-     * @param multipleAuthenticatorCredentials An authentication method available to Sync clients and peers. Additional
-     * authenticator credentials can be supplied using the returned builder. For the embedded server, currently only
-     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
+     * Like {@link #server(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods
+     * for clients and peers.
      */
     public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials[] multipleAuthenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, multipleAuthenticatorCredentials);
@@ -125,8 +113,8 @@ public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCreden
      * {@code ws://0.0.0.0:9999}.
      * @param authenticatorCredentials An authentication method available to Sync clients and peers. The client of the
      * hybrid is pre-configured with them. Additional credentials can be supplied using the client and server builder of
-     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret} and
-     * {@link SyncCredentials#none} are supported.
+     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret}, any JWT
+     * method like {@link SyncCredentials#jwtIdTokenServer()} as well as {@link SyncCredentials#none} are supported.
      * @return An instance of {@link SyncHybridBuilder}.
      */
     public static SyncHybridBuilder hybrid(BoxStoreBuilder storeBuilder, String url,

objectbox-java/src/main/java/io/objectbox/sync/SyncBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,7 +42,7 @@ public final class SyncBuilder {
 
     final Platform platform;
     final BoxStore boxStore;
-    String url;
+    @Nullable private String url;
     final List<SyncCredentials> credentials;
 
     @Nullable SyncLoginListener loginListener;
@@ -94,41 +94,32 @@ private static void checkSyncFeatureAvailable() {
         }
     }
 
-
-    @Internal
-    public SyncBuilder(BoxStore boxStore, SyncCredentials credentials) {
+    private SyncBuilder(BoxStore boxStore, @Nullable String url, @Nullable List<SyncCredentials> credentials) {
         checkNotNull(boxStore, "BoxStore is required.");
         checkNotNull(credentials, "Sync credentials are required.");
-        checkSyncFeatureAvailable();
-        this.platform = Platform.findPlatform();
         this.boxStore = boxStore;
-        this.credentials = Collections.singletonList(credentials);
+        this.url = url;
+        this.credentials = credentials;
+        checkSyncFeatureAvailable();
+        this.platform = Platform.findPlatform(); // Requires APIs only present in Android Sync library
     }
 
     @Internal
-    public SyncBuilder(BoxStore boxStore, SyncCredentials[] multipleCredentials) {
-        checkNotNull(boxStore, "BoxStore is required.");
-        if (multipleCredentials.length == 0) {
-            throw new IllegalArgumentException("At least one Sync credential is required.");
-        }
-        checkSyncFeatureAvailable();
-        this.platform = Platform.findPlatform();
-        this.boxStore = boxStore;
-        this.credentials = Arrays.asList(multipleCredentials);
+    public SyncBuilder(BoxStore boxStore, String url, @Nullable SyncCredentials credentials) {
+        this(boxStore, url, credentials == null ? null : Collections.singletonList(credentials));
     }
 
     @Internal
-    public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
-        this(boxStore, credentials);
-        checkNotNull(url, "Sync server URL is required.");
-        this.url = url;
+    public SyncBuilder(BoxStore boxStore, String url, @Nullable SyncCredentials[] multipleCredentials) {
+        this(boxStore, url, multipleCredentials == null ? null : Arrays.asList(multipleCredentials));
     }
 
+    /**
+     * When using this constructor, make sure to set the server URL before starting.
+     */
     @Internal
-    public SyncBuilder(BoxStore boxStore, String url, SyncCredentials[] multipleCredentials) {
-        this(boxStore, multipleCredentials);
-        checkNotNull(url, "Sync server URL is required.");
-        this.url = url;
+    public SyncBuilder(BoxStore boxStore, @Nullable SyncCredentials credentials) {
+        this(boxStore, null, credentials == null ? null : Collections.singletonList(credentials));
     }
 
     /**
@@ -140,6 +131,12 @@ SyncBuilder serverUrl(String url) {
         return this;
     }
 
+    @Internal
+    String serverUrl() {
+        checkNotNull(url, "Sync Server URL is null.");
+        return url;
+    }
+
     /**
      * Configures a custom set of directory or file paths to search for trusted certificates in.
      * The first path that exists will be used.
@@ -261,7 +258,7 @@ public SyncClient buildAndStart() {
         return syncClient;
     }
 
-    private void checkNotNull(Object object, String message) {
+    private void checkNotNull(@Nullable Object object, String message) {
         //noinspection ConstantConditions Non-null annotation does not enforce, so check for null.
         if (object == null) {
             throw new IllegalArgumentException(message);

objectbox-java/src/main/java/io/objectbox/sync/SyncClient.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -128,14 +128,13 @@ public interface SyncClient extends Closeable {
     void setSyncTimeListener(@Nullable SyncTimeListener timeListener);
 
     /**
-     * Updates the login credentials. This should not be required during regular use.
+     * 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.
      */
     void setLoginCredentials(SyncCredentials credentials);
 
     /**
-     * Updates the login credentials. This should not be required during regular use.
-     * It allows passing login credentials that the client can use to authenticate with the server.
+     * Like {@link #setLoginCredentials(SyncCredentials)}, but allows setting multiple credentials.
      */
     void setLoginCredentials(SyncCredentials[] multipleCredentials);
 

objectbox-java/src/main/java/io/objectbox/sync/SyncClientImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,7 +61,7 @@ public final class SyncClientImpl implements SyncClient {
 
     SyncClientImpl(SyncBuilder builder) {
         this.boxStore = builder.boxStore;
-        this.serverUrl = builder.url;
+        this.serverUrl = builder.serverUrl();
         this.connectivityMonitor = builder.platform.getConnectivityMonitor();
 
         long boxStoreHandle = builder.boxStore.getNativeStore();
@@ -189,6 +189,9 @@ public void setSyncListener(@Nullable SyncListener listener) {
 
     @Override
     public void setLoginCredentials(SyncCredentials credentials) {
+        if (credentials == null) {
+            throw new IllegalArgumentException("credentials must not be null");
+        }
         if (credentials instanceof SyncCredentialsToken) {
             SyncCredentialsToken credToken = (SyncCredentialsToken) credentials;
             nativeSetLoginInfo(getHandle(), credToken.getTypeId(), credToken.getTokenBytes());
@@ -204,6 +207,9 @@ public void setLoginCredentials(SyncCredentials credentials) {
 
     @Override
     public void setLoginCredentials(SyncCredentials[] multipleCredentials) {
+        if (multipleCredentials == null) {
+            throw new IllegalArgumentException("credentials must not be null");
+        }
         for (int i = 0; i < multipleCredentials.length; i++) {
             SyncCredentials credentials = multipleCredentials[i];
             boolean isLast = i == (multipleCredentials.length - 1);

objectbox-java/src/main/java/io/objectbox/sync/SyncCredentials.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -49,47 +49,111 @@ public static SyncCredentials google(String idToken) {
     }
 
     /**
-     * ObjectBox admin users (username/password)
+     * ObjectBox Admin user (username and password).
      */
     public static SyncCredentials obxAdminUser(String user, String password) {
         return new SyncCredentialsUserPassword(CredentialsType.OBX_ADMIN_USER, user, password);
     }
 
     /**
-     * Generic credential type suitable for ObjectBox admin (and possibly others in the future)
+     * Generic credentials type suitable for ObjectBox Admin (and possibly others in the future).
      */
     public static SyncCredentials userAndPassword(String user, String password) {
         return new SyncCredentialsUserPassword(CredentialsType.USER_PASSWORD, user, password);
     }
 
     /**
-     * JSON Web Token (JWT): an ID token that typically provides identity information about the authenticated user.
+     * Authenticate with a JSON Web Token (JWT) that is an ID token.
+     * <p>
+     * An ID token typically provides identity information about the authenticated user.
+     * <p>
+     * Use this and the other JWT methods that accept a token to configure JWT auth for a Sync client or server peer.
+     * To configure Sync server auth options, use the server variants, like {@link #jwtIdTokenServer()}, instead.
+     * <p>
+     * See the <a href="https://sync.objectbox.io/sync-server-configuration/jwt-authentication">JWT authentication documentation</a>
+     * for details.
      */
     public static SyncCredentials jwtIdToken(String jwtIdToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_ID_TOKEN, jwtIdToken);
     }
 
     /**
-     * JSON Web Token (JWT): an access token that is used to access resources.
+     * Authenticate with a JSON Web Token (JWT) that is an access token.
+     * <p>
+     * An access token is used to access resources.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtAccessToken(String jwtAccessToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_ACCESS_TOKEN, jwtAccessToken);
     }
 
     /**
-     * JSON Web Token (JWT): a refresh token that is used to obtain a new access token.
+     * Authenticate with a JSON Web Token (JWT) that is a refresh token.
+     * <p>
+     * A refresh token is used to obtain a new access token.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtRefreshToken(String jwtRefreshToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_REFRESH_TOKEN, jwtRefreshToken);
     }
 
     /**
-     * JSON Web Token (JWT): a token that is neither an ID, access, nor refresh token.
+     * Authenticate with a JSON Web Token (JWT) that is neither an ID, access, nor refresh token.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtCustomToken(String jwtCustomToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_CUSTOM_TOKEN, jwtCustomToken);
     }
 
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is an ID token.
+     * <p>
+     * An ID token typically provides identity information about the authenticated user.
+     * <p>
+     * Use this and the other JWT server credentials types to configure a Sync server.
+     * For Sync clients, use the ones that accept a token, like {@link #jwtIdToken(String)}, instead.
+     * <p>
+     * See the <a href="https://sync.objectbox.io/sync-server-configuration/jwt-authentication">JWT authentication documentation</a>
+     * for details.
+     */
+    public static SyncCredentials jwtIdTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_ID_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is an access token.
+     * <p>
+     * An access token is used to access resources.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtAccessTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_ACCESS_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is a refresh token.
+     * <p>
+     * A refresh token is used to obtain a new access token.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtRefreshTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_REFRESH_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is neither an ID, access, nor refresh token.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtCustomTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_CUSTOM_TOKEN);
+    }
+
     /**
      * No authentication, unsecured. Use only for development and testing purposes.
      */

objectbox-java/src/main/java/io/objectbox/sync/SyncCredentialsToken.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,6 +51,10 @@ public final class SyncCredentialsToken extends SyncCredentials {
         this(type, token.getBytes(StandardCharsets.UTF_8));
     }
 
+    public boolean hasToken() {
+        return token != null;
+    }
+
     @Nullable
     public byte[] getTokenBytes() {
         if (cleared) {