Align APIs: split up Sync listeners, group in listener package.

Make change listener part of general listener.

Author: greenrobot-team

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

@@ -5,6 +5,11 @@
 import io.objectbox.BoxStore;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.sync.internal.Platform;
+import io.objectbox.sync.listener.SyncChangeListener;
+import io.objectbox.sync.listener.SyncCompletedListener;
+import io.objectbox.sync.listener.SyncConnectionListener;
+import io.objectbox.sync.listener.SyncListener;
+import io.objectbox.sync.listener.SyncLoginListener;
 
 /**
  * A builder to create a {@link SyncClient}; the builder itself should be created via
@@ -19,8 +24,11 @@ public class SyncBuilder {
     final String url;
     final SyncCredentials credentials;
 
-    SyncClientListener listener;
-    SyncChangesListener changesListener;
+    @Nullable SyncLoginListener loginListener;
+    @Nullable SyncCompletedListener completedListener;
+    @Nullable SyncChangeListener changeListener;
+    @Nullable SyncConnectionListener connectionListener;
+    @Nullable SyncListener listener;
 
     @Nullable
     String[] trustedCertPaths;
@@ -103,24 +111,59 @@ public SyncBuilder uncommittedAcks() {
     }
 
     /**
-     * Sets a listener to observe sync events like login or sync completion.
-     * This listener can also be set (or removed) on the sync client directly.
-     *
-     * @see SyncClient#setSyncListener(SyncClientListener)
+     * Sets a listener to only observe Sync login events.
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncLoginListener(SyncLoginListener) set or removed}
+     * on the Sync client directly.
      */
-    public SyncBuilder listener(SyncClientListener listener) {
-        this.listener = listener;
+    public SyncBuilder loginListener(SyncLoginListener loginListener) {
+        this.loginListener = loginListener;
+        return this;
+    }
+
+    /**
+     * Sets a listener to only observe Sync completed events.
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncCompletedListener(SyncCompletedListener) set or removed}
+     * on the Sync client directly.
+     */
+    public SyncBuilder completedListener(SyncCompletedListener completedListener) {
+        this.completedListener = completedListener;
         return this;
     }
 
     /**
      * Sets a listener to observe fine granular changes happening during sync.
-     * This listener can also be set (or removed) on the sync client directly.
-     *
-     * @see SyncClient#setSyncChangesListener(SyncChangesListener)
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncChangeListener(SyncChangeListener) set or removed}
+     * on the Sync client directly.
      */
-    public SyncBuilder changesListener(SyncChangesListener changesListener) {
-        this.changesListener = changesListener;
+    public SyncBuilder changeListener(SyncChangeListener changeListener) {
+        this.changeListener = changeListener;
+        return this;
+    }
+
+    /**
+     * Sets a listener to only observe Sync connection events.
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncConnectionListener(SyncConnectionListener) set or removed}
+     * on the Sync client directly.
+     */
+    public SyncBuilder connectionListener(SyncConnectionListener connectionListener) {
+        this.connectionListener = connectionListener;
+        return this;
+    }
+
+    /**
+     * Sets a listener to observe all Sync events like login or sync completion.
+     * <p>
+     * Note: this will replace any login, completed or connection listener.
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncListener(SyncListener) set or removed}
+     * on the Sync client directly.
+     */
+    public SyncBuilder listener(SyncListener listener) {
+        this.listener = listener;
         return this;
     }
 

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

@@ -1,10 +1,12 @@
 package io.objectbox.sync;
 
 import io.objectbox.annotation.apihint.Experimental;
+import io.objectbox.sync.listener.SyncChangeListener;
 
+// Note: this class is expected to be in this package by JNI, check before modifying/removing it.
 /**
  * A collection of changes made to one entity type during a sync transaction.
- * Delivered via {@link SyncChangesListener}.
+ * Delivered via {@link SyncChangeListener}.
  * IDs of changed objects are available via {@link #getChangedIds()} and those of removed objects via
  * {@link #getRemovedIds()}.
  */

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

@@ -2,9 +2,16 @@
 
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.sync.SyncBuilder.RequestUpdatesMode;
+import io.objectbox.sync.listener.SyncChangeListener;
+import io.objectbox.sync.listener.SyncCompletedListener;
+import io.objectbox.sync.listener.SyncConnectionListener;
+import io.objectbox.sync.listener.SyncListener;
+import io.objectbox.sync.listener.SyncLoginListener;
 
 import java.io.Closeable;
 
+import javax.annotation.Nullable;
+
 /**
  * ObjectBox sync client. Build a client with {@link Sync#client}.
  *
@@ -40,24 +47,35 @@ public interface SyncClient extends Closeable {
     long getLastLoginCode();
 
     /**
-     * Sets a {@link SyncClientListener}. Replaces a previously set listener.
+     * Sets a listener to observe login events. Replaces a previously set listener.
+     * Set to {@code null} to remove the listener.
+     */
+    void setSyncLoginListener(@Nullable SyncLoginListener listener);
+
+    /**
+     * Sets a listener to observe Sync completed events. Replaces a previously set listener.
+     * Set to {@code null} to remove the listener.
      */
-    void setSyncListener(SyncClientListener listener);
+    void setSyncCompletedListener(@Nullable SyncCompletedListener listener);
 
     /**
-     * Removes a previously set {@link SyncClientListener}. Does nothing if no listener was set.
+     * Sets a listener to observe Sync connection events. Replaces a previously set listener.
+     * Set to {@code null} to remove the listener.
      */
-    void removeSyncListener();
+    void setSyncConnectionListener(@Nullable SyncConnectionListener listener);
 
     /**
-     * Sets a {@link SyncChangesListener}. Replaces a previously set listener.
+     * Sets a listener to observe all Sync events.
+     * Replaces all other previously set listeners, except a {@link SyncChangeListener}.
+     * Set to {@code null} to remove the listener.
      */
-    void setSyncChangesListener(SyncChangesListener listener);
+    void setSyncListener(@Nullable SyncListener listener);
 
     /**
-     * Removes a previously set {@link SyncChangesListener}. Does nothing if no listener was set.
+     * Sets a {@link SyncChangeListener}. Replaces a previously set listener.
+     * Set to {@code null} to remove the listener.
      */
-    void removeSyncChangesListener();
+    void setSyncChangeListener(@Nullable SyncChangeListener listener);
 
     /**
      * Updates the login credentials. This should not be required during regular use.

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

@@ -4,6 +4,11 @@
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.sync.SyncBuilder.RequestUpdatesMode;
+import io.objectbox.sync.listener.SyncChangeListener;
+import io.objectbox.sync.listener.SyncCompletedListener;
+import io.objectbox.sync.listener.SyncConnectionListener;
+import io.objectbox.sync.listener.SyncListener;
+import io.objectbox.sync.listener.SyncLoginListener;
 
 import javax.annotation.Nullable;
 import java.util.concurrent.CountDownLatch;
@@ -17,13 +22,17 @@
 public class SyncClientImpl implements SyncClient {
 
     private final String serverUrl;
-    private final InternalListener internalListener;
+    private final InternalSyncClientListener internalListener;
     @Nullable
     private final ConnectivityMonitor connectivityMonitor;
 
     private volatile long handle;
     @Nullable
-    private volatile SyncClientListener listener;
+    private volatile SyncLoginListener loginListener;
+    @Nullable
+    private volatile SyncCompletedListener completedListener;
+    @Nullable
+    private volatile SyncConnectionListener connectionListener;
     private volatile long lastLoginCode;
     private volatile boolean started;
 
@@ -47,15 +56,20 @@ public class SyncClientImpl implements SyncClient {
             nativeSetUncommittedAcks(handle, true);
         }
 
-        this.listener = builder.listener;
+        if (builder.listener != null) {
+            setSyncListener(builder.listener);
+        } else {
+            this.loginListener = builder.loginListener;
+            this.completedListener = builder.completedListener;
+            if (builder.changeListener != null) {
+                setSyncChangeListener(builder.changeListener);
+            }
+            this.connectionListener = builder.connectionListener;
+        }
 
-        this.internalListener = new InternalListener();
+        this.internalListener = new InternalSyncClientListener();
         nativeSetListener(handle, internalListener);
 
-        if (builder.changesListener != null) {
-            setSyncChangesListener(builder.changesListener);
-        }
-
         setLoginCredentials(builder.credentials);
     }
 
@@ -82,25 +96,31 @@ public SyncClientState getSyncState() {
     }
 
     @Override
-    public void setSyncListener(SyncClientListener listener) {
-        checkNotNull(listener, "Listener must not be null. Use removeSyncListener to remove existing listener.");
-        this.listener = listener;
+    public void setSyncLoginListener(@Nullable SyncLoginListener listener) {
+        this.loginListener = listener;
     }
 
     @Override
-    public void removeSyncListener() {
-        this.listener = null;
+    public void setSyncCompletedListener(@Nullable SyncCompletedListener listener) {
+        this.completedListener = listener;
     }
 
     @Override
-    public void setSyncChangesListener(SyncChangesListener changesListener) {
-        checkNotNull(changesListener, "Listener must not be null. Use removeSyncChangesListener to remove existing listener.");
+    public void setSyncChangeListener(@Nullable SyncChangeListener changesListener) {
         nativeSetSyncChangesListener(handle, changesListener);
     }
 
     @Override
-    public void removeSyncChangesListener() {
-        nativeSetSyncChangesListener(handle, null);
+    public void setSyncConnectionListener(@Nullable SyncConnectionListener listener) {
+        this.connectionListener = listener;
+    }
+
+    @Override
+    public void setSyncListener(@Nullable SyncListener listener) {
+        this.loginListener = listener;
+        this.completedListener = listener;
+        this.connectionListener = listener;
+        setSyncChangeListener(listener);
     }
 
     @Override
@@ -203,13 +223,6 @@ public void notifyConnectionAvailable() {
         nativeTriggerReconnect(handle);
     }
 
-    private void checkNotNull(Object object, String message) {
-        //noinspection ConstantConditions Non-null annotation does not enforce, so check for null.
-        if (object == null) {
-            throw new IllegalArgumentException(message);
-        }
-    }
-
     /**
      * Creates a native sync client for the given store handle ready to connect to the server at the given URI.
      * Uses certificate authorities trusted by the host if no trusted certificate paths are passed.
@@ -224,9 +237,9 @@ private void checkNotNull(Object object, String message) {
 
     private native void nativeSetLoginInfo(long handle, long credentialsType, @Nullable byte[] credentials);
 
-    private native void nativeSetListener(long handle, @Nullable SyncClientListener listener);
+    private native void nativeSetListener(long handle, @Nullable InternalSyncClientListener listener);
 
-    private native void nativeSetSyncChangesListener(long handle, @Nullable SyncChangesListener advancedListener);
+    private native void nativeSetSyncChangesListener(long handle, @Nullable SyncChangeListener advancedListener);
 
     /** @param subscribeForPushes Pass true to automatically receive updates for future changes. */
     private native void nativeSetRequestUpdatesMode(long handle, boolean autoRequestUpdates, boolean subscribeForPushes);
@@ -253,44 +266,44 @@ private void checkNotNull(Object object, String message) {
     /** Hints to the native client that an active network connection is available. */
     private native void nativeTriggerReconnect(long handle);
 
-    private class InternalListener implements SyncClientListener {
+    /**
+     * Methods on this class must match those expected by JNI implementation.
+     */
+    @SuppressWarnings("unused") // Methods called from native code.
+    private class InternalSyncClientListener {
         private final CountDownLatch firstLoginLatch = new CountDownLatch(1);
 
-        @Override
         public void onLogin() {
             lastLoginCode = SyncLoginCodes.OK;
             firstLoginLatch.countDown();
 
-            SyncClientListener listenerToFire = listener;
+            SyncLoginListener listenerToFire = loginListener;
             if (listenerToFire != null) {
-                listenerToFire.onLogin();
+                listenerToFire.onLoggedIn();
             }
         }
 
-        @Override
         public void onLoginFailure(long errorCode) {
             lastLoginCode = errorCode;
             firstLoginLatch.countDown();
 
-            SyncClientListener listenerToFire = listener;
+            SyncLoginListener listenerToFire = loginListener;
             if (listenerToFire != null) {
-                listenerToFire.onLoginFailure(errorCode);
+                listenerToFire.onLoginFailed(errorCode);
             }
         }
 
-        @Override
         public void onSyncComplete() {
-            SyncClientListener listenerToFire = listener;
+            SyncCompletedListener listenerToFire = completedListener;
             if (listenerToFire != null) {
-                listenerToFire.onSyncComplete();
+                listenerToFire.onUpdatesCompleted();
             }
         }
 
-        @Override
         public void onDisconnect() {
-            SyncClientListener listenerToFire = listener;
+            SyncConnectionListener listenerToFire = connectionListener;
             if (listenerToFire != null) {
-                listenerToFire.onDisconnect();
+                listenerToFire.onDisconnected();
             }
         }