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 provides an implementation of a publisher in the Flow API. It can be used on all platforms supported by this library, including TeaVM.

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

Constructor Summary

Constructors

Constructor	Description
Subject()

Method Summary

Modifier and Type	Method	Description
void	complete()	Marks this Subject as completed, meaning that no new events or errors will be published to subscribers.
static <T> Subject<T>	empty()	Returns a Subject that is incapable of ever publishing any events or errors, and therefore acts as a no-op implementation.
Subject<T>	filter(Predicate<T> predicate)	Returns a Subject that forwards events to its own subscribers, though only events that match the specified predicate.
<S> Subject<S>	flatMap(Function<T, Stream<S>> mapper)	Returns a Subject that forwards events to its own subscribers, first applying the specified mapper function to each event.
<S> Subject<S>	map(Function<T,S> mapper)	Returns a Subject that forwards events to its own subscribers, first applying the specified mapper function to each event.
void	next(Callable<T> operation)	Performs the specified operation and publishes the resulting event to subscribers.
void	next(T event)	Publishes the next event to all event subscribers.
void	nextError(Throwable error)	Publishes the next error to all error subscribers.
static <T> Subject<T>	of(Iterable<T> values)	Creates a Subject that will immediately publish the specified values to its subscribers.
static <T> Subject<T>	of(T... values)	Creates a Subject that will immediately publish the specified values to its subscribers.
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.
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.
static <T> Subject<T>	run(Callable<T> operation)	Performs the specified operation in the current thread, returns a Subject that can be used to subscribe to its results.
static <T> Subject<T>	runAsync(Callable<T> operation)	Performs the specified operation in a new thread, returns a Subject that can be used to subscribe to its results.
void	subscribe(Flow.Subscriber<? super T> subscriber)	Registers the specified subscriber to receive published events and errors.
Flow.Subscription	subscribe(Consumer<T> onEvent)	Registers the specified callback function as a subscriber for events.
Flow.Subscription	subscribe(Consumer<T> onEvent, Consumer<Throwable> onError)	Registers the specified callback functions as event and error subscribers.
Flow.Subscription	subscribe(Subject<T> subscriber)	Subscribes the specified other Subject to listen for both events and errors generated by this Subject.
Flow.Subscription	subscribeErrors(Consumer<Throwable> onError)	Registers the specified callback function as an error subscriber.

Methods inherited from class Object

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

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> onEvent)

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> onEvent,
 Consumer<Throwable> onError)

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.

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 Subject that forwards events to its own subscribers, first applying the specified mapper function to each event. Intended as the equivalent of Stream.map(Function) for asynchronous events.

flatMap

public <S> Subject<S> flatMap(Function<T, Stream<S>> mapper)

Returns a Subject that forwards events to its own subscribers, first applying the specified mapper function to each event. Intended as the equivalent of Stream.flatMap(Function) for asynchronous events.

filter

public Subject<T> filter(Predicate<T> predicate)

Returns a Subject that forwards events to its own subscribers, though only events that match the specified predicate. Intended as the equivalent of Stream.filter(Predicate) for asynchronous events.

of

@SafeVarargs
public static <T> Subject<T> of(T... values)

Creates a Subject that will immediately publish the specified values to its subscribers.

of

public static <T> Subject<T> of(Iterable<T> values)

Creates a Subject that will immediately publish the specified values to its subscribers.

run

public static <T> Subject<T> run(Callable<T> operation)

Performs the specified operation in the current thread, returns a Subject that can be used to subscribe to its results.

runAsync

public static <T> Subject<T> runAsync(Callable<T> operation)

Performs the specified operation in a new thread, returns a Subject that can be used to subscribe to its results.

empty

public static <T> Subject<T> empty()

Returns a Subject that is incapable of ever publishing any events or errors, and therefore acts as a no-op implementation.