Update subscriber and transformer documentation.

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/reactive/DataTransformer.java

@@ -16,17 +16,16 @@
 
 package io.objectbox.reactive;
 
-import javax.annotation.Nullable;
-
 /**
  * Transforms or processes data before it is given to subscribed {@link DataObserver}s. A transformer is set via
  * {@link SubscriptionBuilder#transform(DataTransformer)}.
- *
+ * <p>
  * Note that a transformer is not required to actually "transform" any data.
  * Technically, it's fine to return the same data it received and just do some processing with it.
- *
- * Threading notes: Note that the transformer is always executed asynchronously.
- * It is OK to perform long lasting operations.
+ * <p>
+ * Threading notes: transformations are executed sequentially on a background thread
+ * owned by the subscription publisher. It is OK to perform long lasting operations,
+ * however this will block notifications to all other observers until finished.
  *
  * @param <FROM> Data type this transformer receives
  * @param <TO> Type of transformed data

objectbox-java/src/main/java/io/objectbox/reactive/SubscriptionBuilder.java

@@ -19,13 +19,14 @@
 import javax.annotation.Nullable;
 
 import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.query.Query;
 
 /**
  * Builds a {@link DataSubscription} for a {@link DataObserver} passed via {@link #observer(DataObserver)}.
  * Note that the call to {@link #observer(DataObserver)} is mandatory to create the subscription -
  * if you forget it, nothing will happen.
  * <p>
- * When subscribing to a data source such as {@link io.objectbox.query.Query}, this builder allows to configure:
+ * When subscribing to a data source such as {@link Query}, this builder allows to configure:
  * <ul>
  * <li>weakly referenced observer via {@link #weak()}</li>
  * <li>a data transform operation via {@link #transform(DataTransformer)}</li>
@@ -78,11 +79,21 @@ public SubscriptionBuilder<T> weak() {
         return this;
     }
 
+    /**
+     * Only deliver the latest data once, do not subscribe for data changes.
+     *
+     * @see #onlyChanges()
+     */
     public SubscriptionBuilder<T> single() {
         single = true;
         return this;
     }
 
+    /**
+     * Upon subscribing do not deliver the latest data, only once there are changes.
+     *
+     * @see #single()
+     */
     public SubscriptionBuilder<T> onlyChanges() {
         onlyChanges = true;
         return this;
@@ -94,14 +105,12 @@ public SubscriptionBuilder<T> onlyChanges() {
     //    }
 
     /**
-     * Transforms the original data from the publisher to something that is more helpful to your application.
-     * The transformation is done in an asynchronous thread.
-     * The observer will be called in the same asynchronous thread unless a Scheduler is defined using
-     * {@link #on(Scheduler)}.
+     * Transforms the original data from the publisher to some other type.
+     * All transformations run sequentially in an asynchronous thread owned by the publisher.
      * <p>
-     * This is roughly equivalent to the map operator as known in Rx and Kotlin.
+     * This is similar to the map operator of Rx and Kotlin.
      *
-     * @param <TO> The class the data is transformed to
+     * @param <TO> The type data is transformed to.
      */
     public <TO> SubscriptionBuilder<TO> transform(final DataTransformer<T, TO> transformer) {
         if (this.transformer != null) {
@@ -139,11 +148,16 @@ public SubscriptionBuilder<T> on(Scheduler scheduler) {
     }
 
     /**
-     * The given observer is subscribed to the publisher. This method MUST be called to complete a subscription.
+     * Sets the observer for this subscription and requests the latest data to be delivered immediately
+     * and subscribes to the publisher for data updates, unless configured differently
+     * using {@link #single()} or {@link #onlyChanges()}.
+     * <p>
+     * Results are delivered on a background thread owned by the publisher,
+     * unless a scheduler was set using {@link #on(Scheduler)}.
      * <p>
-     * Note: you must keep the returned {@link DataSubscription} to cancel it.
+     * The returned {@link DataSubscription} must be canceled once the observer should no longer receive notifications.
      *
-     * @return an subscription object used for canceling further notifications to the observer
+     * @return A {@link DataSubscription} to cancel further notifications to the observer.
      */
     public DataSubscription observer(DataObserver<T> observer) {
         WeakDataObserver<T> weakObserver = null;