Add missing obxAdminUser credentials, minor cleanup objectbox-java#252

Throw FeatureNotAvailableException if sync is unavailable
Add docs to new credentials builder methods

Author: greenrobot

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

@@ -24,6 +24,7 @@
 
 import io.objectbox.BoxStore;
 import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.exception.FeatureNotAvailableException;
 import io.objectbox.sync.internal.Platform;
 import io.objectbox.sync.listener.SyncChangeListener;
 import io.objectbox.sync.listener.SyncCompletedListener;
@@ -85,15 +86,20 @@ public enum RequestUpdatesMode {
         AUTO_NO_PUSHES
     }
 
-    @Internal
-    public SyncBuilder(BoxStore boxStore, SyncCredentials credentials) {
-        checkNotNull(boxStore, "BoxStore is required.");
-        checkNotNull(credentials, "Sync credentials are required.");
+    private static void checkSyncFeatureAvailable() {
         if (!BoxStore.isSyncAvailable()) {
-            throw new IllegalStateException(
+            throw new FeatureNotAvailableException(
                     "This library does not include ObjectBox Sync. " +
                             "Please visit https://objectbox.io/sync/ for options.");
         }
+    }
+
+
+    @Internal
+    public SyncBuilder(BoxStore boxStore, 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);
@@ -105,11 +111,7 @@ public SyncBuilder(BoxStore boxStore, SyncCredentials[] multipleCredentials) {
         if (multipleCredentials.length == 0) {
             throw new IllegalArgumentException("At least one Sync credential is required.");
         }
-        if (!BoxStore.isSyncAvailable()) {
-            throw new IllegalStateException(
-                    "This library does not include ObjectBox Sync. " +
-                            "Please visit https://objectbox.io/sync/ for options.");
-        }
+        checkSyncFeatureAvailable();
         this.platform = Platform.findPlatform();
         this.boxStore = boxStore;
         this.credentials = Arrays.asList(multipleCredentials);

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

@@ -206,7 +206,7 @@ public void setLoginCredentials(SyncCredentials credentials) {
     public void setLoginCredentials(SyncCredentials[] multipleCredentials) {
         for (int i = 0; i < multipleCredentials.length; i++) {
             SyncCredentials credentials = multipleCredentials[i];
-            boolean isLast = i == multipleCredentials.length - 1;
+            boolean isLast = i == (multipleCredentials.length - 1);
             if (credentials instanceof SyncCredentialsToken) {
                 SyncCredentialsToken credToken = (SyncCredentialsToken) credentials;
                 nativeAddLoginCredentials(getHandle(), credToken.getTypeId(), credToken.getTokenBytes(), isLast);

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

@@ -48,22 +48,44 @@ public static SyncCredentials google(String idToken) {
         return new SyncCredentialsToken(CredentialsType.GOOGLE, idToken);
     }
 
+    /**
+     * ObjectBox admin users (username/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)
+     */
     public static SyncCredentials userAndPassword(String user, String password) {
-        return new SyncCredentialsUserPassword(user, 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.
+     */
     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.
+     */
     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.
+     */
     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.
+     */
     public static SyncCredentials jwtCustomToken(String jwtCustomToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_CUSTOM_TOKEN, jwtCustomToken);
     }

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

@@ -28,8 +28,8 @@ public final class SyncCredentialsUserPassword extends SyncCredentials {
     private final String username;
     private final String password;
 
-    SyncCredentialsUserPassword(String username, String password) {
-        super(CredentialsType.USER_PASSWORD);
+    SyncCredentialsUserPassword(CredentialsType type, String username, String password) {
+        super(type);
         this.username = username;
         this.password = password;
     }
@@ -44,6 +44,6 @@ public String getPassword() {
 
     @Override
     SyncCredentials createClone() {
-        return new SyncCredentialsUserPassword(this.username, this.password);
+        return new SyncCredentialsUserPassword(getType(), this.username, this.password);
     }
 }

objectbox-java/src/main/java/io/objectbox/sync/server/JwtConfig.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 // automatically generated by the FlatBuffers compiler, do not modify
 
 package io.objectbox.sync.server;

objectbox-java/src/main/java/io/objectbox/sync/server/SyncServerBuilder.java

@@ -25,6 +25,7 @@
 
 import io.objectbox.BoxStore;
 import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.exception.FeatureNotAvailableException;
 import io.objectbox.flatbuffers.FlatBufferBuilder;
 import io.objectbox.sync.Credentials;
 import io.objectbox.sync.Sync;
@@ -59,6 +60,14 @@ public final class SyncServerBuilder {
     private String claimIss;
     private String claimAud;
 
+    private static void checkFeatureSyncServerAvailable() {
+        if (!BoxStore.isSyncServerAvailable()) {
+            throw new FeatureNotAvailableException(
+                    "This library does not include ObjectBox Sync Server. " +
+                            "Please visit https://objectbox.io/sync/ for options.");
+        }
+    }
+
     /**
      * Use {@link Sync#server(BoxStore, String, SyncCredentials)} instead.
      */
@@ -67,11 +76,7 @@ public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials authenti
         checkNotNull(boxStore, "BoxStore is required.");
         checkNotNull(url, "Sync server URL is required.");
         checkNotNull(authenticatorCredentials, "Authenticator credentials are required.");
-        if (!BoxStore.isSyncServerAvailable()) {
-            throw new IllegalStateException(
-                    "This library does not include ObjectBox Sync Server. " +
-                            "Please visit https://objectbox.io/sync/ for options.");
-        }
+        checkFeatureSyncServerAvailable();
         this.boxStore = boxStore;
         try {
             this.url = new URI(url);
@@ -89,11 +94,7 @@ public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials[] multip
         checkNotNull(boxStore, "BoxStore is required.");
         checkNotNull(url, "Sync server URL is required.");
         checkNotNull(multipleAuthenticatorCredentials, "Authenticator credentials are required.");
-        if (!BoxStore.isSyncServerAvailable()) {
-            throw new IllegalStateException(
-                    "This library does not include ObjectBox Sync Server. " +
-                            "Please visit https://objectbox.io/sync/ for options.");
-        }
+        checkFeatureSyncServerAvailable();
         this.boxStore = boxStore;
         try {
             this.url = new URI(url);
@@ -179,7 +180,7 @@ public SyncServerBuilder peer(String url) {
     }
 
     /**
-     * @deprecated Use {@link #clusterPeer(String,SyncCredentials)} instead.
+     * @deprecated Use {@link #clusterPeer(String, SyncCredentials)} instead.
      */
     @Deprecated
     public SyncServerBuilder peer(String url, SyncCredentials credentials) {
@@ -263,7 +264,7 @@ public SyncServerBuilder syncServerFlags(int syncServerFlags) {
 
     /**
      * Sets the number of workers for the main task pool.
-     *
+     * <p>
      * If not set or set to 0, this uses a hardware-dependant default, e.g. 3 * CPU "cores".
      */
     public SyncServerBuilder workerThreads(int workerThreads) {

tests/objectbox-java-test/src/test/java/io/objectbox/sync/ConnectivityMonitorTest.java

@@ -155,12 +155,10 @@ public void setSyncTimeListener(@Nullable SyncTimeListener timeListener) {
 
         @Override
         public void setLoginCredentials(SyncCredentials credentials) {
-
         }
 
         @Override
         public void setLoginCredentials(SyncCredentials[] multipleCredentials) {
-
         }
 
         @Override
@@ -170,17 +168,14 @@ public boolean awaitFirstLogin(long millisToWait) {
 
         @Override
         public void start() {
-
         }
 
         @Override
         public void stop() {
-
         }
 
         @Override
         public void close() {
-
         }
 
         @Override

tests/objectbox-java-test/src/test/java/io/objectbox/sync/SyncTest.java

@@ -16,6 +16,7 @@
 
 package io.objectbox.sync;
 
+import io.objectbox.exception.FeatureNotAvailableException;
 import org.junit.Test;
 
 import io.objectbox.AbstractObjectBoxTest;
@@ -53,8 +54,8 @@ public void serverIsNotAvailable() {
 
     @Test
     public void creatingSyncClient_throws() {
-        IllegalStateException exception = assertThrows(
-                IllegalStateException.class,
+        FeatureNotAvailableException exception = assertThrows(
+                FeatureNotAvailableException.class,
                 () -> Sync.client(store, "wss://127.0.0.1", SyncCredentials.none())
         );
         String message = exception.getMessage();
@@ -64,8 +65,8 @@ public void creatingSyncClient_throws() {
 
     @Test
     public void creatingSyncServer_throws() {
-        IllegalStateException exception = assertThrows(
-                IllegalStateException.class,
+        FeatureNotAvailableException exception = assertThrows(
+                FeatureNotAvailableException.class,
                 () -> Sync.server(store, "wss://127.0.0.1", SyncCredentials.none())
         );
         String message = exception.getMessage();