io.objectbox.reactive

Class SubscriptionBuilder<T>

java.lang.Object

io.objectbox.reactive.SubscriptionBuilder<T>

Type Parameters:

T - The data type the DataObserver subscribes to.

public class SubscriptionBuilder<T>
extends java.lang.Object

Builds a DataSubscription for a DataObserver passed via observer(DataObserver). Note that the call to observer(DataObserver) is mandatory to create the subscription - if you forget it, nothing will happen.

When subscribing to a data source such as Query, this builder allows to configure:

• weakly referenced observer via weak()
• a data transform operation via transform(DataTransformer)
• error handlers via onError(ErrorObserver)
• calling the observer using a custom Scheduler (e.g. Android main thread) via on(Scheduler)

Note: the order of methods called in this do not matter. Unlike Rx's Observeable, this builder just collects all info. For example, on(scheduler).transform(transformer) is the same as transform(transformer).on(scheduler).

Constructor Summary

Constructors

Constructor and Description
SubscriptionBuilder(DataPublisher<T> publisher, java.lang.Object param, java.util.concurrent.ExecutorService threadPool)

Method Summary

Modifier and Type	Method and Description
SubscriptionBuilder<T>	dataSubscriptionList(DataSubscriptionList dataSubscriptionList)
DataSubscription	observer(DataObserver<T> observer) The given observer is subscribed to the publisher.
SubscriptionBuilder<T>	on(Scheduler scheduler) Changes the thread in which the DataObserver (and potentially @ErrorObserver) is called.
SubscriptionBuilder<T>	onError(ErrorObserver errorObserver) The given ErrorObserver is notified when the DataTransformer (transform(DataTransformer)) or DataObserver (observer(DataObserver)) threw an exception.
SubscriptionBuilder<T>	onlyChanges()
SubscriptionBuilder<T>	single()
<TO> SubscriptionBuilder<TO>	transform(DataTransformer<T,TO> transformer) Transforms the original data from the publisher to something that is more helpful to your application.
SubscriptionBuilder<T>	weak() Uses a weak reference for the observer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SubscriptionBuilder

@Internal
public SubscriptionBuilder(DataPublisher<T> publisher,
                                     @Nullable
                                     java.lang.Object param,
                                     java.util.concurrent.ExecutorService threadPool)

Method Detail

weak

public SubscriptionBuilder<T> weak()

Uses a weak reference for the observer. It is still advised to remove observers explicitly if possible: relying on the garbage collection may cause non-deterministic timing. Until the weak reference is actually cleared by GC, it may still receive notifications.

single

public SubscriptionBuilder<T> single()

onlyChanges

public SubscriptionBuilder<T> onlyChanges()

transform

public <TO> SubscriptionBuilder<TO> transform(DataTransformer<T,TO> transformer)

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 on(Scheduler).

This is roughly equivalent to the map operator as known in Rx and Kotlin.

Type Parameters:

TO - The class the data is transformed to

onError

public SubscriptionBuilder<T> onError(ErrorObserver errorObserver)

The given ErrorObserver is notified when the DataTransformer (transform(DataTransformer)) or DataObserver (observer(DataObserver)) threw an exception.

on

public SubscriptionBuilder<T> on(Scheduler scheduler)

Changes the thread in which the DataObserver (and potentially @ErrorObserver) is called.

In the Android package, there is a class AndroidScheduler with a MAIN_THREAD Scheduler implementation. Using MAIN_THREAD, observers will be called in Android's main thread, which is required for UI updates.

observer

public DataSubscription observer(DataObserver<T> observer)

The given observer is subscribed to the publisher. This method MUST be called to complete a subscription.

Note: you must keep the returned DataSubscription to cancel it.

Returns:

an subscription object used for canceling further notifications to the observer

dataSubscriptionList

public SubscriptionBuilder<T> dataSubscriptionList(DataSubscriptionList dataSubscriptionList)