Merge remote-tracking branch 'origin/458-align-sync-apis' into sync

# Conflicts:
#	objectbox-java/src/main/java/io/objectbox/sync/SyncBuilder.java
#	objectbox-java/src/main/java/io/objectbox/sync/SyncClientImpl.java

Author: greenrobot

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,13 +24,15 @@ 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;
     boolean uncommittedAcks;
-    boolean manualStart;
 
     RequestUpdatesMode requestUpdatesMode = RequestUpdatesMode.AUTO;
 
@@ -103,50 +110,82 @@ public SyncBuilder uncommittedAcks() {
         return this;
     }
 
-
     /**
-     * Prevents the client from starting (connecting, logging in, syncing) automatically.
-     * It will need to be started manually later.
-     *
-     * @see SyncClient#start()
+     * 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 manualStart() {
-        manualStart = true;
+    public SyncBuilder loginListener(SyncLoginListener loginListener) {
+        this.loginListener = loginListener;
         return this;
     }
 
     /**
-     * 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 completed events.
+     * <p>
+     * This listener can also be {@link SyncClient#setSyncCompletedListener(SyncCompletedListener) set or removed}
+     * on the Sync client directly.
      */
-    public SyncBuilder listener(SyncClientListener listener) {
-        this.listener = listener;
+    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;
+    }
+
+    /**
+     * Builds and returns a Sync client ready to {@link SyncClient#start()}.
+     */
     public SyncClient build() {
-        if (credentials == null) {
-            throw new IllegalStateException("Credentials are required.");
-        }
         if (boxStore.getSyncClient() != null) {
             throw new IllegalStateException("The given store is already associated with a Sync client, close it first.");
         }
         return new SyncClientImpl(this);
     }
 
+    /**
+     * Builds, {@link SyncClient#start() starts} and returns a Sync client.
+     */
+    public SyncClient buildAndStart() {
+        SyncClient syncClient = build();
+        syncClient.start();
+        return syncClient;
+    }
+
     private void checkNotNull(Object object, String message) {
         //noinspection ConstantConditions Non-null annotation does not enforce, so check for null.
         if (object == null) {

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.