Package nl.colorize.util

Class Subject<T>

java.lang.Object
nl.colorize.util.Subject<T>
Type Parameters:
T - The type of event that can be subscribed to.
All Implemented Interfaces:
Flow.Publisher<T>
public final class Subject<T> extends Object implements Flow.Publisher<T>
Publishes (possibly asynchronous) events to registered subscribers. This class implements the Flow API. It can be used on all platforms supported by this library, including TeaVM. The term "subject" originates from the original Gang of Four's description of the observer pattern.

Subject instances are thread-safe and can be accessed from different threads. This facilitates workflows where publishers and subscribers operate on different threads.

  • Constructor Details

    • Subject

      public Subject()

  • Method Details

    • next

      public void next(T event)
      Publishes the next event to all event subscribers. This method does nothing if this Subject has already been marked as completed.

    • nextError

      public void nextError(Throwable error)
      Publishes the next error to all error subscribers. If no error subscribers have been registered, this will invoke the default error handler that will print a log messsage describing the unhandled error. This method does nothing if this Subject has already been marked as completed.

    • next

      public void next(Callable<T> operation)
      Performs the specified operation and publishes the resulting event to subscribers. If the operation completes normally, the return value is published to subscribers as an event. If an exception occurs during the operation, this exception is published to error subscribers. Does nothing if this Subject has already been marked as completed.

    • retry

      public void retry(Callable<T> operation, int attempts)
      Attempts to perform an operation for the specified number of attempts, automatically retrying the operation if the initial attempt(s) failed. Note attempts includes the original attempt, so the number of retries is basically attempts - 1.

      If the operation is not successful, an error is sent to subscribers based on the last failed attempt.

    • retry

      public void retry(Callable<T> operation, int attempts, long delay)
      Attempts to perform an operation for the specified number of attempts, automatically retrying the operation if the initial attempt(s) failed. The specified time delay (in milliseconds) is applied in between attempts. Note attempts includes the original attempt, so the number of retries is basically attempts - 1.

      If the operation is not successful, an error is sent to subscribers based on the last failed attempt.

    • subscribe

      public void subscribe(Flow.Subscriber<? super T> subscriber)
      Registers the specified subscriber to receive published events and errors. The subscriber will immediately be notified of previously published events.
      Specified by:
      subscribe in interface Flow.Publisher<T>

    • subscribe

      public Flow.Subscription subscribe(Consumer<T> eventCallback)
      Registers the specified callback function as a subscriber for events. The subscriber will log errors, but not explicitly handle them. Returns a Flow.Subscription for the registered subscriber.

    • subscribe

      public Flow.Subscription subscribe(Consumer<T> eventCallback, Consumer<Throwable> errorCallback)
      Registers the specified callback functions as event and error subscribers. The subscribers will immediately be notified of previously published events and/or errors. Returns a Flow.Subscription for the registered subscriber.

    • subscribeErrors

      public Flow.Subscription subscribeErrors(Consumer<Throwable> onError)
      Registers the specified callback function as an error subscriber. The subscriber will immediately be notified of previously published errors. Returns a Flow.Subscription for the registered subscriber.

    • subscribe

      public Flow.Subscription subscribe(Subject<T> subscriber)
      Subscribes the specified other Subject to listen for both events and errors generated by this Subject. This effectively means that events published by this instance will be forwarded to subscriber's subscribers. Returns a Flow.Subscription for the registered subscriber.

    • collect

      public void collect(Queue<T> messageQueue)
      Creates and registers a Flow.Subscriber that collects received events into the specified queue. Consumers can then poll this queue to periodically process events.

    • unsubscribe

      @Deprecated public void unsubscribe(Flow.Subscription subscription)
      Deprecated.
      Prefer using Flow.Subscription.cancel() instead.
      Unsubscribes the specified subscription. If the subscriber is not currently registered with this Subject, this method does nothing.

    • unsubscribe

      @Deprecated public void unsubscribe(Flow.Subscriber<? super T> subscriber)
      Deprecated.
      Prefer using Flow.Subscription.cancel() instead.
      Removes a previously registered subscriber. If the subscriber is not currently registered with this Subject, this method does nothing.

    • complete

      public void complete()
      Marks this Subject as completed, meaning that no new events or errors will be published to subscribers. However, old events might still be published when additional subscribers are registered.

    • map

      public <S> Subject<S> map(Function<T,S> mapper)
      Returns a new Subject that will forward events to its own subscribers, but first uses the specified mapping function on each event. Errors will be forwarded as-is.

    • filter

      public Subject<T> filter(Predicate<T> predicate)
      Returns a new Subject that will forward events to its own subscribers, but only if the event matches the specified predicate. Errors will be forwarded as-is.

    • of

      @SafeVarargs public static <T> Subject<T> of(T... values)
      Creates a Subject that will publish the specified values to its subscribers.

    • of

      public static <T> Subject<T> of(Iterable<T> values)
      Creates a Subject that will publish the specified values to its subscribers.

    • run

      public static <T> Subject<T> run(Callable<T> operation)
      Performs the specified operation and returns a Subject that can be used to subscribe to the results.

    • runBackground

      public static <T> Subject<T> runBackground(Callable<T> operation)
      Performs the specified operation in a new background thread, and returns a Subject that can be used to subscribe to the background operation.

    • createSubscriber

      public static <T> Flow.Subscriber<T> createSubscriber(Consumer<T> eventCallback)
      Returns an implementation of the Flow.Subscriber interface that implements Flow.Subscriber.onNext(Object) using a callback method. Errors will be logged, all other methods use no-op implementations.

    • createSubscriber

      public static <T> Flow.Subscriber<T> createSubscriber(Consumer<T> eventFn, Consumer<Throwable> errorFn)
      Returns an implementation of the Flow.Subscriber interface that implements Flow.Subscriber.onNext(Object) and Flow.Subscriber.onError(Throwable) using callback methods. The other methods use no-op implementations.