Class RxJavaPlugins


  • public final class RxJavaPlugins
    extends java.lang.Object
    Utility class to inject handlers to certain standard RxJava operations.
    • Constructor Detail

      • RxJavaPlugins

        private RxJavaPlugins()
        Helper class, no instances.
    • Method Detail

      • lockdown

        public static void lockdown()
        Prevents changing the plugins from then on.

        This allows container-like environments to prevent clients messing with plugins.

      • isLockdown

        public static boolean isLockdown()
        Returns true if the plugins were locked down.
        Returns:
        true if the plugins were locked down
      • setFailOnNonBlockingScheduler

        public static void setFailOnNonBlockingScheduler​(boolean enable)
        Enables or disables the blockingX operators to fail with an IllegalStateException on a non-blocking scheduler such as computation or single.

        History: 2.0.5 - experimental

        Parameters:
        enable - enable or disable the feature
        Since:
        2.1
      • isFailOnNonBlockingScheduler

        public static boolean isFailOnNonBlockingScheduler()
        Returns true if the blockingX operators fail with an IllegalStateException on a non-blocking scheduler such as computation or single.

        History: 2.0.5 - experimental

        Returns:
        true if the blockingX operators fail on a non-blocking scheduler
        Since:
        2.1
      • getComputationSchedulerHandler

        @Nullable
        public static @Nullable Function<? super Scheduler,​? extends Scheduler> getComputationSchedulerHandler()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • getErrorHandler

        @Nullable
        public static @Nullable Consumer<? super java.lang.Throwable> getErrorHandler()
        Returns the a hook consumer.
        Returns:
        the hook consumer, may be null
      • getNewThreadSchedulerHandler

        @Nullable
        public static @Nullable Function<? super Scheduler,​? extends Scheduler> getNewThreadSchedulerHandler()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • getScheduleHandler

        @Nullable
        public static @Nullable Function<? super java.lang.Runnable,​? extends java.lang.Runnable> getScheduleHandler()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • initComputationScheduler

        @NonNull
        public static @NonNull Scheduler initComputationScheduler​(@NonNull
                                                                  @NonNull Supplier<Scheduler> defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - a Supplier which returns the hook's input value
        Returns:
        the value returned by the hook, not null
        Throws:
        java.lang.NullPointerException - if the supplier parameter or its result are null
      • initIoScheduler

        @NonNull
        public static @NonNull Scheduler initIoScheduler​(@NonNull
                                                         @NonNull Supplier<Scheduler> defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - a Supplier which returns the hook's input value
        Returns:
        the value returned by the hook, not null
        Throws:
        java.lang.NullPointerException - if the supplier parameter or its result are null
      • initNewThreadScheduler

        @NonNull
        public static @NonNull Scheduler initNewThreadScheduler​(@NonNull
                                                                @NonNull Supplier<Scheduler> defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - a Supplier which returns the hook's input value
        Returns:
        the value returned by the hook, not null
        Throws:
        java.lang.NullPointerException - if the supplier parameter or its result are null
      • initSingleScheduler

        @NonNull
        public static @NonNull Scheduler initSingleScheduler​(@NonNull
                                                             @NonNull Supplier<Scheduler> defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - a Supplier which returns the hook's input value
        Returns:
        the value returned by the hook, not null
        Throws:
        java.lang.NullPointerException - if the supplier parameter or its result are null
      • onComputationScheduler

        @NonNull
        public static @NonNull Scheduler onComputationScheduler​(@NonNull
                                                                @NonNull Scheduler defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - the hook's input value
        Returns:
        the value returned by the hook
      • onError

        public static void onError​(@NonNull
                                   @NonNull java.lang.Throwable error)
        Called when an undeliverable error occurs.

        Undeliverable errors are those Observer.onError() invocations that are not allowed to happen on the given consumer type (Observer, Subscriber, etc.) due to protocol restrictions because the consumer has either disposed/cancelled its Disposable/Subscription or has already terminated with an onError() or onComplete() signal.

        By default, this global error handler prints the stacktrace via Throwable.printStackTrace() and calls Thread.UncaughtExceptionHandler.uncaughtException(Thread, Throwable) on the current thread.

        Note that on some platforms, the platform runtime terminates the current application with an error if such uncaught exceptions happen. In this case, it is recommended the application installs a global error handler via the setErrorHandler(Consumer) plugin method.

        Parameters:
        error - the error to report
        See Also:
        getErrorHandler(), setErrorHandler(Consumer), Error handling Wiki
      • isBug

        static boolean isBug​(java.lang.Throwable error)
        Checks if the given error is one of the already named bug cases that should pass through onError(Throwable) as is.
        Parameters:
        error - the error to check
        Returns:
        true if the error should pass through, false if it may be wrapped into an UndeliverableException
      • uncaught

        static void uncaught​(@NonNull
                             @NonNull java.lang.Throwable error)
      • onIoScheduler

        @NonNull
        public static @NonNull Scheduler onIoScheduler​(@NonNull
                                                       @NonNull Scheduler defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - the hook's input value
        Returns:
        the value returned by the hook
      • onNewThreadScheduler

        @NonNull
        public static @NonNull Scheduler onNewThreadScheduler​(@NonNull
                                                              @NonNull Scheduler defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - the hook's input value
        Returns:
        the value returned by the hook
      • onSchedule

        @NonNull
        public static @NonNull java.lang.Runnable onSchedule​(@NonNull
                                                             @NonNull java.lang.Runnable run)
        Called when a task is scheduled.
        Parameters:
        run - the runnable instance
        Returns:
        the replacement runnable
      • onSingleScheduler

        @NonNull
        public static @NonNull Scheduler onSingleScheduler​(@NonNull
                                                           @NonNull Scheduler defaultScheduler)
        Calls the associated hook function.
        Parameters:
        defaultScheduler - the hook's input value
        Returns:
        the value returned by the hook
      • reset

        public static void reset()
        Removes all handlers and resets to default behavior.
      • setComputationSchedulerHandler

        public static void setComputationSchedulerHandler​(@Nullable
                                                          @Nullable Function<? super Scheduler,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • setErrorHandler

        public static void setErrorHandler​(@Nullable
                                           @Nullable Consumer<? super java.lang.Throwable> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • setInitComputationSchedulerHandler

        public static void setInitComputationSchedulerHandler​(@Nullable
                                                              @Nullable Function<? super Supplier<Scheduler>,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed, but the function may not return null
      • setInitIoSchedulerHandler

        public static void setInitIoSchedulerHandler​(@Nullable
                                                     @Nullable Function<? super Supplier<Scheduler>,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed, but the function may not return null
      • setInitNewThreadSchedulerHandler

        public static void setInitNewThreadSchedulerHandler​(@Nullable
                                                            @Nullable Function<? super Supplier<Scheduler>,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed, but the function may not return null
      • setInitSingleSchedulerHandler

        public static void setInitSingleSchedulerHandler​(@Nullable
                                                         @Nullable Function<? super Supplier<Scheduler>,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed, but the function may not return null
      • setIoSchedulerHandler

        public static void setIoSchedulerHandler​(@Nullable
                                                 @Nullable Function<? super Scheduler,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • setNewThreadSchedulerHandler

        public static void setNewThreadSchedulerHandler​(@Nullable
                                                        @Nullable Function<? super Scheduler,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • setScheduleHandler

        public static void setScheduleHandler​(@Nullable
                                              @Nullable Function<? super java.lang.Runnable,​? extends java.lang.Runnable> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • setSingleSchedulerHandler

        public static void setSingleSchedulerHandler​(@Nullable
                                                     @Nullable Function<? super Scheduler,​? extends Scheduler> handler)
        Sets the specific hook function.
        Parameters:
        handler - the hook function to set, null allowed
      • unlock

        static void unlock()
        Revokes the lockdown, only for testing purposes.
      • getOnFlowableSubscribe

        @Nullable
        public static @Nullable BiFunction<? super Flowable,​? super org.reactivestreams.Subscriber,​? extends org.reactivestreams.Subscriber> getOnFlowableSubscribe()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • getOnMaybeAssembly

        @Nullable
        public static @Nullable Function<? super Maybe,​? extends Maybe> getOnMaybeAssembly()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • getOnSingleAssembly

        @Nullable
        public static @Nullable Function<? super Single,​? extends Single> getOnSingleAssembly()
        Returns the current hook function.
        Returns:
        the hook function, may be null
      • setOnCompletableAssembly

        public static void setOnCompletableAssembly​(@Nullable
                                                    @Nullable Function<? super Completable,​? extends Completable> onCompletableAssembly)
        Sets the specific hook function.
        Parameters:
        onCompletableAssembly - the hook function to set, null allowed
      • setOnFlowableAssembly

        public static void setOnFlowableAssembly​(@Nullable
                                                 @Nullable Function<? super Flowable,​? extends Flowable> onFlowableAssembly)
        Sets the specific hook function.
        Parameters:
        onFlowableAssembly - the hook function to set, null allowed
      • setOnMaybeAssembly

        public static void setOnMaybeAssembly​(@Nullable
                                              @Nullable Function<? super Maybe,​? extends Maybe> onMaybeAssembly)
        Sets the specific hook function.
        Parameters:
        onMaybeAssembly - the hook function to set, null allowed
      • setOnConnectableFlowableAssembly

        public static void setOnConnectableFlowableAssembly​(@Nullable
                                                            @Nullable Function<? super ConnectableFlowable,​? extends ConnectableFlowable> onConnectableFlowableAssembly)
        Sets the specific hook function.
        Parameters:
        onConnectableFlowableAssembly - the hook function to set, null allowed
      • setOnFlowableSubscribe

        public static void setOnFlowableSubscribe​(@Nullable
                                                  @Nullable BiFunction<? super Flowable,​? super org.reactivestreams.Subscriber,​? extends org.reactivestreams.Subscriber> onFlowableSubscribe)
        Sets the specific hook function.
        Parameters:
        onFlowableSubscribe - the hook function to set, null allowed
      • setOnObservableAssembly

        public static void setOnObservableAssembly​(@Nullable
                                                   @Nullable Function<? super Observable,​? extends Observable> onObservableAssembly)
        Sets the specific hook function.
        Parameters:
        onObservableAssembly - the hook function to set, null allowed
      • setOnConnectableObservableAssembly

        public static void setOnConnectableObservableAssembly​(@Nullable
                                                              @Nullable Function<? super ConnectableObservable,​? extends ConnectableObservable> onConnectableObservableAssembly)
        Sets the specific hook function.
        Parameters:
        onConnectableObservableAssembly - the hook function to set, null allowed
      • setOnObservableSubscribe

        public static void setOnObservableSubscribe​(@Nullable
                                                    @Nullable BiFunction<? super Observable,​? super Observer,​? extends Observer> onObservableSubscribe)
        Sets the specific hook function.
        Parameters:
        onObservableSubscribe - the hook function to set, null allowed
      • setOnSingleAssembly

        public static void setOnSingleAssembly​(@Nullable
                                               @Nullable Function<? super Single,​? extends Single> onSingleAssembly)
        Sets the specific hook function.
        Parameters:
        onSingleAssembly - the hook function to set, null allowed
      • onSubscribe

        @NonNull
        public static <@NonNull T> @NonNull org.reactivestreams.Subscriber<? super T> onSubscribe​(@NonNull
                                                                                                  @NonNull Flowable<@NonNull T> source,
                                                                                                  @NonNull
                                                                                                  @NonNull org.reactivestreams.Subscriber<? super @NonNull T> subscriber)
        Calls the associated hook function.
        Type Parameters:
        T - the value type
        Parameters:
        source - the hook's input value
        subscriber - the subscriber
        Returns:
        the value returned by the hook
      • onSubscribe

        @NonNull
        public static <@NonNull T> @NonNull org.reactivestreams.Subscriber<? super T>[] onSubscribe​(@NonNull
                                                                                                    @NonNull ParallelFlowable<@NonNull T> source,
                                                                                                    @NonNull
                                                                                                    @NonNull org.reactivestreams.Subscriber<? super @NonNull T>[] subscribers)
        Calls the associated hook function.
        Type Parameters:
        T - the value type
        Parameters:
        source - the hook's input value
        subscribers - the array of subscribers
        Returns:
        the value returned by the hook
      • setOnParallelAssembly

        public static void setOnParallelAssembly​(@Nullable
                                                 @Nullable Function<? super ParallelFlowable,​? extends ParallelFlowable> handler)
        Sets the specific hook function.

        History: 2.0.6 - experimental; 2.1 - beta

        Parameters:
        handler - the hook function to set, null allowed
        Since:
        2.2
      • setOnParallelSubscribe

        public static void setOnParallelSubscribe​(@Nullable
                                                  @Nullable BiFunction<? super ParallelFlowable,​? super org.reactivestreams.Subscriber[],​? extends org.reactivestreams.Subscriber[]> handler)
        Sets the specific hook function.

        History: 3.0.11 - experimental

        Parameters:
        handler - the hook function to set, null allowed
        Since:
        3.1.0
      • getOnParallelSubscribe

        @Nullable
        public static @Nullable BiFunction<? super ParallelFlowable,​? super org.reactivestreams.Subscriber[],​? extends org.reactivestreams.Subscriber[]> getOnParallelSubscribe()
        Returns the current hook function.

        History: 3.0.11 - experimental

        Returns:
        the hook function, may be null
        Since:
        3.1.0
      • onBeforeBlocking

        public static boolean onBeforeBlocking()
        Called before an operator attempts a blocking operation such as awaiting a condition or signal and should return true to indicate the operator should not block but throw an IllegalArgumentException.

        History: 2.0.5 - experimental

        Returns:
        true if the blocking should be prevented
        Since:
        2.1
        See Also:
        setFailOnNonBlockingScheduler(boolean)
      • setOnBeforeBlocking

        public static void setOnBeforeBlocking​(@Nullable
                                               @Nullable BooleanSupplier handler)
        Set the handler that is called when an operator attempts a blocking await; the handler should return true to prevent the blocking and to signal an IllegalStateException instead.

        History: 2.0.5 - experimental

        Parameters:
        handler - the handler to set, null resets to the default handler that always returns false
        Since:
        2.1
        See Also:
        onBeforeBlocking()
      • getOnBeforeBlocking

        @Nullable
        public static @Nullable BooleanSupplier getOnBeforeBlocking()
        Returns the current blocking handler or null if no custom handler is set.

        History: 2.0.5 - experimental

        Returns:
        the current blocking handler or null if not specified
        Since:
        2.1
      • createComputationScheduler

        @NonNull
        public static @NonNull Scheduler createComputationScheduler​(@NonNull
                                                                    @NonNull java.util.concurrent.ThreadFactory threadFactory)
        Create an instance of the default Scheduler used for Schedulers.computation() except using threadFactory for thread creation.

        History: 2.0.5 - experimental

        Parameters:
        threadFactory - thread factory to use for creating worker threads. Note that this takes precedence over any system properties for configuring new thread creation. Cannot be null.
        Returns:
        the created Scheduler instance
        Since:
        2.1
      • createIoScheduler

        @NonNull
        public static @NonNull Scheduler createIoScheduler​(@NonNull
                                                           @NonNull java.util.concurrent.ThreadFactory threadFactory)
        Create an instance of the default Scheduler used for Schedulers.io() except using threadFactory for thread creation.

        History: 2.0.5 - experimental

        Parameters:
        threadFactory - thread factory to use for creating worker threads. Note that this takes precedence over any system properties for configuring new thread creation. Cannot be null.
        Returns:
        the created Scheduler instance
        Since:
        2.1
      • createNewThreadScheduler

        @NonNull
        public static @NonNull Scheduler createNewThreadScheduler​(@NonNull
                                                                  @NonNull java.util.concurrent.ThreadFactory threadFactory)
        Create an instance of the default Scheduler used for Schedulers.newThread() except using threadFactory for thread creation.

        History: 2.0.5 - experimental

        Parameters:
        threadFactory - thread factory to use for creating worker threads. Note that this takes precedence over any system properties for configuring new thread creation. Cannot be null.
        Returns:
        the created Scheduler instance
        Since:
        2.1
      • createSingleScheduler

        @NonNull
        public static @NonNull Scheduler createSingleScheduler​(@NonNull
                                                               @NonNull java.util.concurrent.ThreadFactory threadFactory)
        Create an instance of the default Scheduler used for Schedulers.single() except using threadFactory for thread creation.

        History: 2.0.5 - experimental

        Parameters:
        threadFactory - thread factory to use for creating worker threads. Note that this takes precedence over any system properties for configuring new thread creation. Cannot be null.
        Returns:
        the created Scheduler instance
        Since:
        2.1
      • createExecutorScheduler

        @NonNull
        public static @NonNull Scheduler createExecutorScheduler​(@NonNull
                                                                 @NonNull java.util.concurrent.Executor executor,
                                                                 boolean interruptibleWorker,
                                                                 boolean fair)
        Create an instance of a Scheduler by wrapping an existing Executor.

        This method allows creating an Executor-backed Scheduler before the Schedulers class would initialize the standard Schedulers.

        Parameters:
        executor - the Executor to wrap and turn into a Scheduler.
        interruptibleWorker - if true, the tasks submitted to the Scheduler.Worker will be interrupted when the task is disposed.
        fair - if true, tasks submitted to the Scheduler or Worker will be executed by the underlying Executor one after the other, still in a FIFO and non-overlapping manner, but allows interleaving with other tasks submitted to the underlying Executor. If false, the underlying FIFO scheme will execute as many tasks as it can before giving up the underlying Executor thread.
        Returns:
        the new Scheduler wrapping the Executor
        Since:
        3.1.0
      • apply

        @NonNull
        static <@NonNull T,​@NonNull R> R apply​(@NonNull
                                                     @NonNull Function<@NonNull T,​@NonNull R> f,
                                                     @NonNull
                                                     @NonNull T t)
        Wraps the call to the function in try-catch and propagates thrown checked exceptions as RuntimeException.
        Type Parameters:
        T - the input type
        R - the output type
        Parameters:
        f - the function to call, not null (not verified)
        t - the parameter value to the function
        Returns:
        the result of the function call
      • apply

        @NonNull
        static <@NonNull T,​@NonNull U,​@NonNull R> R apply​(@NonNull
                                                                      @NonNull BiFunction<@NonNull T,​@NonNull U,​@NonNull R> f,
                                                                      @NonNull
                                                                      @NonNull T t,
                                                                      @NonNull
                                                                      @NonNull U u)
        Wraps the call to the function in try-catch and propagates thrown checked exceptions as RuntimeException.
        Type Parameters:
        T - the first input type
        U - the second input type
        R - the output type
        Parameters:
        f - the function to call, not null (not verified)
        t - the first parameter value to the function
        u - the second parameter value to the function
        Returns:
        the result of the function call
      • callRequireNonNull

        @NonNull
        static @NonNull Scheduler callRequireNonNull​(@NonNull
                                                     @NonNull Supplier<Scheduler> s)
        Wraps the call to the Scheduler creation supplier in try-catch and propagates thrown checked exceptions as RuntimeException and enforces that result is not null.
        Parameters:
        s - the Supplier which returns a Scheduler, not null (not verified). Cannot return null
        Returns:
        the result of the supplier call, not null
        Throws:
        java.lang.NullPointerException - if the supplier parameter returns null
      • applyRequireNonNull

        @NonNull
        static @NonNull Scheduler applyRequireNonNull​(@NonNull
                                                      @NonNull Function<? super Supplier<Scheduler>,​? extends Scheduler> f,
                                                      Supplier<Scheduler> s)
        Wraps the call to the Scheduler creation function in try-catch and propagates thrown checked exceptions as RuntimeException and enforces that result is not null.
        Parameters:
        f - the function to call, not null (not verified). Cannot return null
        s - the parameter value to the function
        Returns:
        the result of the function call, not null
        Throws:
        java.lang.NullPointerException - if the function parameter returns null