Package nl.colorize.util

Class Subscribable<T>

java.lang.Object
nl.colorize.util.Subscribable<T>
Type Parameters:
T - The type of event that can be subscribed to.
public final class Subscribable<T> extends Object
Proxy for accessing multiple events that are produced by a (possibly asynchronous) operation, allowing for publish/subscribe workflows. Subscribers can be notified for events, for errors, or for both.

This type of workflow can also be created in other ways, most commonly using java.util.concurrent and its Flow API. However, the Flow API is not yet available on all platforms that are supported by this library, making this class a more portable alternative.

On platforms that support concurrency, Subscribable instances are thread-safe and can be accessed from multiple threads.

  • Constructor Details

    • Subscribable

      public Subscribable()

  • Method Details

    • next

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

    • nextError

      public void nextError(Exception 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 Subscribable 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 Subscribable 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 Subscribable<T> subscribe(Subscriber<T> subscriber)
      Registers the specified subscriber to receive published events and errors. The subscriber will immediately be notified of previously published events.
      Returns:
      This Subscribable, for method chaining.

    • subscribe

      public Subscribable<T> subscribe(Consumer<T> eventFn, Consumer<Exception> errorFn)
      Registers the specified callback functions as event and error subscribers. The subscribers will immediately be notified of previously published events and/or errors.
      Returns:
      This Subscribable, for method chaining.

    • subscribeErrors

      public Subscribable<T> subscribeErrors(Consumer<Exception> onError)
      Registers the specified callback function as an error subscriber. The subscriber will immediately be notified of previously published errors.
      Returns:
      This Subscribable, for method chaining.

    • subscribe

      public Subscribable<T> subscribe(Subscribable<T> subscriber)
      Subscribes the specified other Subscribable to listen for both events and errors generated by this Subscribable. This effectively means that events published by this instance will be forwarded to subscriber's subscribers.
      Returns:
      This Subscribable, for method chaining.

    • unsubscribe

      public void unsubscribe(Subscriber<T> subscriber)
      Removes a previously registered subscriber. If the subscriber is not currently registered with this Subscribable, this method does nothing.

    • complete

      public void complete()
      Marks this Subscribable 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> Subscribable<S> map(Function<T,S> mapper)
      Returns a new Subscribable 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 Subscribable<T> filter(Predicate<T> predicate)
      Returns a new Subscribable 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> Subscribable<T> of(T... values)
      Creates a Subscribable that will publish the specified values to its subscribers.

    • of

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

    • run

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

    • runBackground

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