Package org.reactfx

Interface EventStream<T>

Type Parameters:
T - type of values emitted by this stream.
All Superinterfaces:
Observable<Consumer<? super T>>
All Known Subinterfaces:
AwaitingEventStream<T>, CompletionStageStream<T>, ConnectableEventStream<T>, ProperEventStream<T>, SuspendableEventStream<T>, SuspenderStream<T,S>, TaskStream<T>
All Known Implementing Classes:
AbstractReducibleEventStream, AccumulateBetweenStream, AccumulateUntilLaterStream, AccumulatingStream, AccumulativeEventStream, Await, AwaitLatest, ConnectableEventSource, DefaultEventStream, DistinctStream, EmitBothOnEachStream, EmitOnEachStream, EmitOnStream, EventSource, EventStreamBase, EventStreams.Never, FilterMapStream, FilterStream, FlatMapOptStream, FlatMapStream, ForgetfulEventStream, HookStream, LatestNStream, MappedStream, MappedToCompletionStageStream, MappedToTaskStream, PausableEventStream, RecursiveStream, ReducibleEventStream, RepeatOnStream, StatefulStream, StateStream, SuccessionReducingStream, SuppressibleEventStream, SuspendableEventStreamBase, SuspendedWhenStream, SuspenderStreamImpl, ThenAccumulateForStream, ThreadBridge

public interface EventStream<T> extends Observable<Consumer<? super T>>
Stream of values (events).
  • Method Details

    • subscribe

      default Subscription subscribe(Consumer<? super T> subscriber)
      Get notified every time this event stream emits a value.
      Parameters:
      subscriber - handles emitted events.
      Returns:
      subscription that can be used to stop observing this event stream.
    • subscribeFor

      default Subscription subscribeFor(int n, Consumer<? super T> subscriber)
      Subscribes to this event stream for at most n events. The subscriber is automatically removed after handling n events.
      Parameters:
      n - limit on how many events may be handled by subscriber. Must be positive.
      subscriber - handles emitted events.
      Returns:
      Subscription that may be used to unsubscribe before reaching n events handled by subscriber.
    • subscribeForOne

      default Subscription subscribeForOne(Consumer<? super T> subscriber)
      Shorthand for subscribeFor(1, subscriber).
    • feedTo

      default Subscription feedTo(EventSink<? super T> sink)
      Starts pushing all events emitted by this stream to the given event sink.

      stream.feedTo(sink) is equivalent to sink.feedFrom(stream)

      Parameters:
      sink - event sink to which this event stream's events will be pushed
      Returns:
      subscription that can be used to stop delivering this stream's events to sink.
      See Also:
    • feedTo

      default Subscription feedTo(javafx.beans.value.WritableValue<? super T> dest)
      Starts setting all events emitted by this stream as the value of the given writable value. This is a shortcut for subscribe(dest::setValue).
    • pin

      default Subscription pin()
      If this stream is a compound stream lazily subscribed to its inputs, that is, subscribed to inputs only when it itself has some subscribers, pinning this stream causes it to stay subscribed until the pinning is revoked by calling unsubscribe() on the returned subscription.

      Equivalent to subscribe(x -> {}).

      Returns:
      subscription used to cancel the pinning
    • withDefaultEvent

      default EventStream<T> withDefaultEvent(T defaultEvent)
      Returns an event stream that immediately emits its event when something subscribes to it. If the stream has no event to emit, it defaults to emitting the default event. Once this stream emits an event, the returned stream will emit this stream's most recent event. Useful when one doesn't know whether an EventStream will emit its event immediately but needs it to emit an event immediately. Such a case can arise as shown in the following example:
       
       EventStream<Boolean> controlPresses = EventStreams
           .eventsOf(scene, KeyEvent.KEY_PRESSED)
           .filter(key -> key.getCode().is(KeyCode.CONTROL))
           .map(key -> key.isControlDown());
      
       EventSource<?> other;
       EventStream<Tuple2<Boolean, ?>> combo = EventStreams.combine(controlPresses, other);
      
       // This will not run until user presses the control key at least once.
       combo.subscribe(tuple2 -> System.out.println("Combo emitted an event."));
      
       EventStream<Boolean> controlDown = controlPresses.withDefaultEvent(false);
       EventStream<Tuple2<Boolean, ?>> betterCombo = EventStreams.combine(controlDown, other);
       betterCombo.subscribe(tuple2 -> System.out.println("Better Combo emitted an event immediately upon program start."));
       
       
      Parameters:
      defaultEvent - the event this event stream will emit if something subscribes to this stream and this stream does not have an event.
    • hook

      default EventStream<T> hook(Consumer<? super T> sideEffect)
      Returns an event stream that emits the same(*) events as this stream, but before emitting each event performs the given side effect. This is useful for debugging. The side effect is not allowed to cause recursive event emission from this stream: if it does, IllegalStateException will be thrown.

      (*) The returned stream is lazily bound, so it only emits events and performs side effects when it has at least one subscriber.

    • filter

      default EventStream<T> filter(Predicate<? super T> predicate)
      Returns a new event stream that emits events emitted from this stream that satisfy the given predicate.
    • filter

      default <U extends T> EventStream<U> filter(Class<U> subtype)
      Filters this event stream by the runtime type of the values. filter(SomeClass.class) is equivalent to filter(x -> x instanceof SomeClass).map(x -> (SomeClass) x).
    • distinct

      default EventStream<T> distinct()
      Returns a new event stream that emits repetitive events only once. For example, given
           
           EventStream<Integer> A = ...;
           EventStream<Integer> B = A.distinct();
           
       

      Returns B. When A emits an event, B only emits that event if it's different from the previous event emitted by A.

              Time --->
              A :-3--3---3-4---4---4---5-4-5--5--5->
              B :-3--------4-----------5-4-5------->
       
    • supply

      default <U> EventStream<U> supply(U value)
      Returns an event stream that emits the given constant value every time this stream emits a value. For example, given
           
           EventStream<Integer> A = ...;
           EventStream<Integer> B = A.supply(5);
           
       

      Returns B. When A emits an event, B emits the supplied value.

              Time --->
              A :-3--0--6--4-1--1---5-4-5--8--2->
              B :-5--5--5--5-5--5---5-5-5--5--5->
       
    • supply

      default <U> EventStream<U> supply(Supplier<? extends U> f)
      Returns an event stream that emits a value obtained from the given supplier every time this event stream emits a value.
           
           EventStream<?> A = ...;
           SimpleIntegerProperty intProp = ...;
           EventStream<Double> B = A.supply(intProp::get);
           
       

      Returns B. When A emits an event, B emits the supplier's value.

              Time --->
              A :----a----b------c----d----e---->
        intProp :-3--------6---------9---------->
              B :----3----3------6----9----9---->
       
    • supplyCompletionStage

      default <U> CompletionStageStream<U> supplyCompletionStage(Supplier<CompletionStage<U>> f)
      Similar to supply(Supplier), but the returned stream is a CompletionStageStream, which can be used to await the results of asynchronous computation.
    • supplyTask

      default <U> TaskStream<U> supplyTask(Supplier<javafx.concurrent.Task<U>> f)
      Similar to supply(Supplier), but the returned stream is a CompletionStageStream, which can be used to await the results of asynchronous computation.
    • map

      default <U> EventStream<U> map(Function<? super T,? extends U> f)
      Returns a new event stream that applies the given function to every value emitted from this stream and emits the result. For example, given
           
           EventStream<Integer> A = ...;
           EventStream<Integer> B = A.map(intValue -> intValue * 2);
           
       

      Returns B. When A emits an event, the event is mapped by the function (in this case, it multiples A's emitted value by two) and B emits this mapped event.

              Time --->
              A :-3---1--4--5--2--0---3--7--->
              B :-6---2--8--10-4--0---6--14-->
       
    • cast

      default <U extends T> EventStream<U> cast(Class<U> subtype)
      Returns a new event stream that emits events emitted by this stream cast to the given type. cast(SomeClass.class) is equivalent to map(x -> (SomeClass) x).
    • splitBy

      default EventStream<Either<T,T>> splitBy(Predicate<? super T> test)
      Returns a new event stream that, for event e emitted from this stream, emits left(e) if e passes the given test, and emits right(e) if e does not pass the test.
    • fork

      default Tuple2<EventStream<T>,EventStream<T>> fork(Predicate<? super T> test)
      Returns two event streams, the first one emitting events of this stream that satisfy the given test and the second one emitting events of this stream that do not satisfy the test.
    • mapToCompletionStage

      default <U> CompletionStageStream<U> mapToCompletionStage(Function<? super T,CompletionStage<U>> f)
      Similar to map(Function), but the returned stream is a CompletionStageStream, which can be used to await the results of asynchronous computation.
    • mapToTask

      default <U> TaskStream<U> mapToTask(Function<? super T,javafx.concurrent.Task<U>> f)
      Similar to map(Function), but the returned stream is a TaskStream, which can be used to await the results of asynchronous computation.
    • filterMap

      default <U> EventStream<U> filterMap(Predicate<? super T> predicate, Function<? super T,? extends U> f)
      A more efficient equivalent to filter(predicate).map(f).
    • filterMap

      default <U> EventStream<U> filterMap(Function<? super T,Optional<U>> f)
      Equivalent to
       
       map(f)
           .filter(Optional::isPresent)
           .map(Optional::get)
       
       
      with more efficient implementation.
    • flatMap

      default <U> EventStream<U> flatMap(Function<? super T,? extends EventStream<U>> f)
      Returns a new event stream that, for each event x emitted from this stream, obtains the event stream f(x) and keeps emitting its events until the next event is emitted from this stream. For example, given
           
           EventStream<Integer> A = ...;
           EventStream<Integer> B = ...;
           EventStream<Integer> C = ...;
           EventStream<Integer> D = A.flatMap(intValue -> {
               intValue < 4
                   ? B
                   : C
           })
           
       

      Returns D. When A emits an event that is less than 4, D will emit B's events. Otherwise, D will emit C's events. When A emits a new event, the stream whose events D will emit is re-determined.

              Time --->
              A :-3---1--4--5--2--0---3--5--------->
              B :--4-7---8--7----4-----34---5--56-->
              C :----6---6----5---8----9---2---5--->
         Stream :-BBBBBBBCCCCCCBBBBBBBBBBCCCCCCCCC->
              D :--4-7---6----5--4-----34--2---5--->
       
    • conditionOn

      default EventStream<T> conditionOn(javafx.beans.value.ObservableValue<Boolean> condition)
      Returns a new EventStream that only observes this EventStream when condition is true. More precisely, the returned EventStream observes condition whenever it itself has at least one subscriber and observes this EventStream whenever it itself has at least one subscriber and the value of condition is true. When condition is true, the returned EventStream emits the same events as this EventStream. When condition is false, the returned EventStream emits no events.
    • conditionOnShowing

      default EventStream<T> conditionOnShowing(javafx.scene.Node node)
      Equivalent to conditionOn(ObservableValue) where the condition is that node is showing: it is part of a scene graph (Node.sceneProperty() is not null), its scene is part of a window (Scene.windowProperty() is not null) and the window is showing (Window.showingProperty() is true).
    • or

      default <U> EventStream<Either<T,U>> or(EventStream<? extends U> right)
      Returns an event stream that emits all the events emitted from either this stream or the right stream. An event t emitted from this stream is emitted as Either.left(t). An event u emitted from the right stream is emitted as Either.right(u).
      See Also:
    • latestN

      default EventStream<List<T>> latestN(int n)
      Returns an event stream that emits lists of n latest events emitted from this stream. For example, given
       
       EventStream<Integer> stream = ...;
       EventStream<List<Integer>> latest3 = stream.latestN(3);
       
      
           Time --->
           stream  :--1--2-----3--4--5-----6--->
           latest3 :--a--b-----c--d--e-----f--->
       
      then lastest3's values are
      • a = [1]
      • b = [1,2]
      • c = [1,2,3]
      • d = [2,3,4]
      • e = [3,4,5]
      • f = [4,5,6]
    • emitOn

      default EventStream<T> emitOn(EventStream<?> impulse)
      Returns a new event stream that, when an event arrives from the impulse stream, emits the most recent event emitted by this stream. Each event is emitted at most once. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = ...;
           EventStream<?> C = A.emitOn(B);
       

      Returns C. When B emits an event, C emits A's most recent event. No, does not emit the most recent event multiple times.

           Time --->
           A :-a-------b-----c----------d------->
           B :----i------------i--i--i-----i---->
           C :----a------------c-----------d---->
       

      Relationship to other EventStreams:

    • emitOnEach

      default EventStream<T> emitOnEach(EventStream<?> impulse)
      Returns a new event stream that, when an event arrives from the impulse stream, emits the most recent event emitted by this stream. The same event may be emitted more than once. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = ...;
           EventStream<?> C = A.emitOnEach(B);
       

      Returns C. When B emits an event, C emits A's most recent event. Yes, does emit the most recent event multiple times.

           Time --->
           A :-a-------b-----c----------d------->
           B :----i------------i--i--i-----i---->
           C :----a------------c--c--c-----d---->
       

      Relationship to other EventStreams:

    • emitBothOnEach

      default <I> EventStream<Tuple2<T,I>> emitBothOnEach(EventStream<I> impulse)
      Similar to emitOnEach(EventStream), but also includes the impulse in the emitted value. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = ...;
           EventStream<?> C = A.emitBothOnEach(B);
       

      Returns C. When B emits an event, C emits A and B's most recent events.. Only emits an event when both A and B have emitted at least one new event.

           Time --->
           A :-a-------b---c------------------d------->
           B :----1-----------2-----3-----4----------->
           C :---[a,1]------[c,2]-----------[d,4]----->
       

      Relationship to other EventStreams:

    • repeatOn

      default EventStream<T> repeatOn(EventStream<?> impulse)
      Returns a new event stream that emits all the events emitted from this stream and in addition to that re-emits the most recent event on every event emitted from impulse. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = ...;
           EventStream<?> C = A.repeatOn(B);
       

      Returns C. When A emits an event, C also emits that event. When B emits an event, C emits that most recent event that A emitted.

           Time --->
           A :-a-------b---c------------------d------->
           B :----i-----------i-----i-----i----------->
           C :-a--a----b---c--c-----c-----c---d------->
       

      Relationship to other EventStreams:

    • suppressible

      default SuspendableEventStream<T> suppressible()
      Returns a suspendable event stream that, when suspended, suppresses any events emitted by this event stream.
    • suppressWhen

      default EventStream<T> suppressWhen(javafx.beans.value.ObservableValue<Boolean> condition)
      Shortcut for suppressible().suspendedWhen(condition).
    • pausable

      default SuspendableEventStream<T> pausable()
      Returns a suspendable event stream that, when suspended, stores the events emitted by this event stream and emits them when the returned stream's emission is resumed. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = A.pausable();
           
       

      Returns B. When A emits an event and B is not suspended, B also emits that event. When B is suspended and A emits events, those events are stored in B. Once B is unsuspended, B emits those events.

           Time --->
           A :-a--b----c---d-----e------------f------->
           B :-a--b--|---Suspended----|cde----f------->
       
    • pauseWhen

      default EventStream<T> pauseWhen(javafx.beans.value.ObservableValue<Boolean> condition)
      Shortcut for pausable().suspendedWhen(condition).
    • forgetful

      default SuspendableEventStream<T> forgetful()
      Returns a suspendable event stream that, when suspended, forgets all but the latest event emitted by this event stream. The remembered event, if any, is emitted from the returned stream upon resume. For example,
           
           EventStream<?> A = ...;
           EventStream<?> B = A.forgetful();
           
       

      Returns B. When B is not suspended and A emits an event, B emits that event. When B is suspended and A emits an event, B does not emit that event, nor does it store that event for later emission. Those events are "forgotten."

           Time --->
           A :-a--b----c---d-----e------------f------->
           B :-a--b--|---Suspended----|-------f------->
       
    • retainLatestWhen

      default EventStream<T> retainLatestWhen(javafx.beans.value.ObservableValue<Boolean> condition)
      Shortcut for forgetful().suspendedWhen(condition).
    • reducible

      default SuspendableEventStream<T> reducible(BinaryOperator<T> reduction)
      Returns a suspendable event stream that, when suspended, reduces incoming events by the given reduction function into one. The reduced event is emitted from the returned stream upon resume. For example,
           
           EventStream<Integer> A = ...;
           EventStream<Integer> B = A.reducible(lastStored_A_Event, mostRecent_A_EventEmitted -> {
               lastStored_A_Event <= 4
                   ? mostRecent_A_EventEmitted
                   : lastStored_A_Event;
           });
           
       

      Returns B. When B is not suspended and A emits an event, B emits that event. When B is suspended and A emits events (En) where n is the number of the event, B applies reduction(En-1, En). When B is no longer suspended, it emits result

           Time --->
           A      :-1--2----4--1--5-----7------------6------->
           B      :-1--2--|---Suspended---|5---------6------->
           result :-------|-a--b--c-----d-|------------------>
       
      then result's values are:
      • a = 4 [reduction(2, 4) == 4]
      • b = 5 [reduction(4, 1) == 1]
      • c = 5 [reduction(1, 5) == 5]
      • d = 5 [reduction(5, 7) == 5]

      Note that forgetful() is equivalent to reducible((a, b) -> b).

    • reduceWhen

      default EventStream<T> reduceWhen(javafx.beans.value.ObservableValue<Boolean> condition, BinaryOperator<T> reduction)
      Shortcut for reducible(reduction).suspendedWhen(condition).
    • accumulative

      default <A> SuspendableEventStream<T> accumulative(Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
      Returns a suspendable event stream that, when suspended, accumulates incoming events to a cumulative value of type A. When the returned stream is resumed, the accumulated value is deconstructed into a sequence of events that are emitted from the returned stream.

      Note that suppressible() is equivalent to

       
       accumulative(
           t -> (Void) null,                        // use null as accumulator
           (a, t) -> a,                             // keep null as accumulator
           a -> AccumulatorSize.ZERO,               // no events to be emitted from accumulator
           a -> throw new NoSuchElementException(), // head is never called on empty accumulator
           a -> throw new NoSuchElementException()) // tail is never called on empty accumulator
       
       

      Note that reducible(reduction) is equivalent to

       
       accumulative(
           t -> t,                                // the event itself is the accumulator
           reduction,
           t -> AccumulatorSize.ONE,              // one event to be emitted
           t -> t,                                // head of a single value is the value itself
           t -> throw new NoSuchElementException) // tail is never called on accumulator of size one
       
       
      Type Parameters:
      A - type of the cumulative value
      Parameters:
      initialTransformation - Used to convert the first event after suspension to the cumulative value.
      accumulation - Used to accumulate further incoming events to the cumulative value.
      size - determines how many events can be emitted from the current cumulative value.
      head - produces the first event off the cumulative value.
      tail - returns a cumulative value that produces the same events as the given cumulative value, except the event returned by head. May be destructive for the given cumulative value.
    • accumulateWhen

      default <A> EventStream<T> accumulateWhen(javafx.beans.value.ObservableValue<Boolean> condition, Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
      Shortcut for
       
       accumulative(initialTransformation, accumulation, size, head, tail)
           .suspendedWhen(condition)
       
    • accumulative

      default <A> SuspendableEventStream<T> accumulative(Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
      A variation on accumulative(Function, BiFunction, Function, Function, Function) to use when it is more convenient to provide a unit element of the accumulation than to transform the initial event to a cumulative value. It is equivalent to accumulative(t -> accumulation.apply(unit.get(), t), accumulation, size, head, tail), i.e. the initial transformation is achieved by accumulating the initial event to the unit element.

      Note that pausable() is equivalent to

       
       accumulative(
           LinkedList<T>::new,                     // the unit element is an empty queue
           (q, t) -> { q.addLast(t); return q; },  // accumulation is addition to the queue
           q -> AccumulatorSize.fromInt(q.size()), // size is the size of the queue
           Deque::getFirst,                        // head is the first element of the queue
           q -> { q.removeFirst(); return q; })    // tail removes the first element from the queue
       
       
      Type Parameters:
      A - type of the cumulative value
      Parameters:
      unit - Function that supplies unit element of the accumulation.
      accumulation - Used to accumulate further incoming events to the cumulative value.
      size - determines how many events can be emitted from the current cumulative value.
      head - produces the first event off the cumulative value.
      tail - returns a cumulative value that produces the same events as the given cumulative value, except the event returned by head. May be destructive for the given cumulative value.
    • accumulateWhen

      default <A> EventStream<T> accumulateWhen(javafx.beans.value.ObservableValue<Boolean> condition, Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
      Shortcut for
       
       accumulative(unit, accumulation, size, head, tail)
           .suspendedWhen(condition)
       
    • accumulateBetween

      default <A> EventStream<T> accumulateBetween(EventStream<?> ticks, Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction)
      Returns an event stream that, when an event arrives from this stream, transforms it into a cumulative value using the initialTransformation function. Any further events that arrive from this stream are accumulated to the cumulative value using the accumulation function. When an event arrives from the ticks stream, the accumulated value is deconstructed into a sequence of events using the deconstruction function and the events are emitted from the returned stream.

      Note that reduceBetween(ticks, reduction) is equivalent to accumulateBetween(ticks, t -> t, reduction, Collections::singletonList).

    • accumulateBetween

      default <A> EventStream<T> accumulateBetween(EventStream<?> ticks, Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction)
      A variation on accumulateBetween(EventStream, Function, BiFunction, Function) to use when it is more convenient to provide a unit element of the accumulation than to transform the initial event to a cumulative value. It is equivalent to accumulateBetween(ticks, t -> accumulation.apply(unit.get(), t), accumulation, deconstruction), i.e. the initial transformation is achieved by accumulating the initial event to the unit element.

      Note that queueBetween(ticks) is equivalent to accumulateBetween(ticks, ArrayList<T>::new, (l, t) -> { l.add(t); return l; }, l -> l), i.e. the unit element is an empty list, accumulation is addition to the list and deconstruction of the accumulated value is a no-op, since the accumulated value is already a list of events.

    • reduceBetween

      default EventStream<T> reduceBetween(EventStream<?> ticks, BinaryOperator<T> reduction)
      Returns an event stream that, when an event arrives from this stream, stores it for emission. Any further events that arrive from this stream are reduced into the stored event using the reduction function. The stored event is emitted from the returned stream when a tick arrives from the ticks stream.

      Note that retainLatestBetween(ticks) is equivalent to reduceBetween(ticks, (a, b) -> b).

    • queueBetween

      default EventStream<T> queueBetween(EventStream<?> ticks)
      Returns an event stream that, when an event arrives from this stream, enqueues it for emission. Queued events are emitted from the returned stream when a tick arrives from the ticks stream.
    • retainLatestBetween

      default EventStream<T> retainLatestBetween(EventStream<?> ticks)
      Equivalent to emitOn(EventStream).
    • accumulateUntilLater

      default <A> EventStream<T> accumulateUntilLater(Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction, Executor eventThreadExecutor)
      Version of accumulateUntilLater(Function, BiFunction, Function) for event streams that don't live on the JavaFX application thread.
      Parameters:
      eventThreadExecutor - executor that executes actions on the thread from which this event stream is accessed.
    • accumulateUntilLater

      default <A> EventStream<T> accumulateUntilLater(Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction)
      Returns an event stream that, when an event is emitted from this stream, transforms the event to a cumulative value using the initialTransformation function and schedules emission using Platform.runLater(Runnable), if not already scheduled. Any new event that arrives from this stream before the scheduled emission is executed is accumulated to the stored cumulative value using the given accumulation function. When the scheduled emission is finally executed, the accumulated value is deconstructed into a sequence of events using the deconstruction function and the events are emitted from the returned stream.

      Note that reduceUntilLater(reduction) is equivalent to accumulateUntilLater(t -> t, reduction, t -> Collections::singletonList).

      Type Parameters:
      A - type of the cumulative value (accumulator)
    • accumulateUntilLater

      default <A> EventStream<T> accumulateUntilLater(Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction, Executor eventThreadExecutor)
      Version of accumulateUntilLater(Supplier, BiFunction, Function) for event streams that don't live on the JavaFX application thread.
      Parameters:
      eventThreadExecutor - executor that executes actions on the thread from which this event stream is accessed.
    • accumulateUntilLater

      default <A> EventStream<T> accumulateUntilLater(Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> accumulation, Function<? super A,List<T>> deconstruction)
      A variation on accumulateUntilLater(Function, BiFunction, Function) to use when it is more convenient to provide a unit element of the accumulation than to transform the initial event to a cumulative value. It is equivalent to accumulateUntilLater(t -> accumulation.apply(unit.get(), t), accumulation, deconstruction), i.e. the initial transformation is achieved by accumulating the initial event to the unit element.

      Note that queueUntilLater() is equivalent to accumulateUntilLater(ArrayList<T>::new, (l, t) -> { l.add(t); return l; }, l -> l), i.e. the unit element is an empty list, accumulation is addition to the list and deconstruction of the accumulated value is a no-op, since the accumulated value is already a list of events.

      Type Parameters:
      A - type of the cumulative value (accumulator)
    • reduceUntilLater

      default EventStream<T> reduceUntilLater(BinaryOperator<T> reduction, Executor eventThreadExecutor)
      Version of reduceUntilLater(BinaryOperator) for event streams that don't live on the JavaFX application thread.
      Parameters:
      eventThreadExecutor - executor that executes actions on the thread from which this event stream is accessed.
    • reduceUntilLater

      default EventStream<T> reduceUntilLater(BinaryOperator<T> reduction)
      Returns an event stream that, when an event is emitted from this stream, stores the event for emission and schedules emission using Platform.runLater(Runnable), if not already scheduled. Any new event that arrives from this stream before the scheduled emission is executed is accumulated into the stored event using the given reduction function. When the scheduled emission is finally executed, the stored event is emitted from the returned stream.

      Note that retainLatestUntilLater() is equivalent to reduceUntilLater((a, b) -> b).

    • retainLatestUntilLater

      default EventStream<T> retainLatestUntilLater(Executor eventThreadExecutor)
      Version of retainLatestUntilLater() for event streams that don't live on the JavaFX application thread.
      Parameters:
      eventThreadExecutor - executor that executes actions on the thread from which this event stream is accessed.
    • retainLatestUntilLater

      default EventStream<T> retainLatestUntilLater()
      Returns an event stream that, when an event is emitted from this stream, stores the event for emission and schedules emission using Platform.runLater(Runnable), if not already scheduled. If a new event arrives from this stream before the scheduled emission is executed, the stored event is overwritten by the new event and only the new event is emitted when the scheduled emission is finally executed.
    • queueUntilLater

      default EventStream<T> queueUntilLater(Executor eventThreadExecutor)
      Version of queueUntilLater() for event streams that don't live on the JavaFX application thread.
      Parameters:
      eventThreadExecutor - executor that executes actions on the thread from which this event stream is accessed.
    • queueUntilLater

      default EventStream<T> queueUntilLater()
      Returns an event stream that, when an event is emitted from this stream, enqueues the event for emission and schedules emission using Platform.runLater(Runnable), if not already scheduled. Any events that arrive from this stream before a scheduled emission is executed are enqueued as well and emitted (in order) when the scheduled emission is finally executed.
    • toBinding

      default javafx.beans.binding.Binding<T> toBinding(T initialValue)
      Returns a binding that holds the most recent event emitted from this stream. The returned binding stays subscribed to this stream until its dispose() method is called.
      Parameters:
      initialValue - used as the returned binding's value until this stream emits the first value.
      Returns:
      binding reflecting the most recently emitted value.
    • accumulate

      default EventStream<T> accumulate(BinaryOperator<T> reduction)
      Returns an event stream that accumulates events emitted from this event stream and emits the accumulated value every time this stream emits a value.
      Parameters:
      reduction - function to reduce two events into one.
    • accumulate

      default <U> EventStream<U> accumulate(U unit, BiFunction<? super U,? super T,? extends U> reduction)
      Returns an event stream that accumulates events emitted from this event stream and emits the accumulated value every time this stream emits a value. For example, given
           
           EventStream<String> A = ...;
           EventStream<String> B = A.accumulate(
                // Unit
                "Cheese",
                // reduction
                (lastStored_A_Event, mostRecent_A_EventEmitted) -> {
                   lastStored_A_Event.length() > mostRecent_A_EventEmitted
                      ? lastStored_A_Event.subString(0, mostRecent_A_EventEmitted.length())
                      : mostRecent_A_EventEmitted
                }
           );
           
       
      Returns B. When A emits an event, B emits the result of applying the reduction function on those events. When A emits its first event, B supplies Unit as the 'lastStored_A_Event'.
           Time --->
           A :-"Cake"--"Sugar"--"Oil"--"French Toast"---"Cookie"----->
           B :--1---------2--------3------4--------------5------------>
       
      where "#" is:
      • 1 = "Chee" ("Cheese" (6) > "Cake" (4) == true; "Cheese".subString(0, 4) == "Chee")
      • 2 = "Sugar" ("Chee" (4) > "Sugar" (5) == false; "Sugar")
      • 3 = "Sug" ("Sugar" (5) > "Oil" (3) == true); "Sugar".subString(0, 3) == "Sug")
      • 4 = "French Toast" ("Sug" (3) > "French Toast" (12) == false; "French Toast")
      • 5 = "French" ("French Toast" (12) > "Cookies" (6) == true; "French Toast".subString(0, 6) == "French")
      Parameters:
      unit - initial value of the accumulated value.
      reduction - function to add an event to the accumulated value.
    • accumulate

      default <U> EventStream<U> accumulate(BiFunction<? super U,? super T,? extends U> reduction, Function<? super T,? extends U> initialTransformation)
      Returns an event stream that accumulates events emitted from this event stream and emits the accumulated value every time this stream emits a value. For example, given
           
           // assumes that A only emits String events that are 1 char long.
           EventStream<String> A = ...;
           EventStream<String> B = A.accumulate(
                // reduction
                (lastStored_A_Event, mostRecent_A_EventEmitted) -> {
                   mostRecent_A_EventEmitted.isVowel()
                      ? lastStored_A_Event + mostRecent_A_EventEmitted
                      : mostRecent_A_EventEmitted
                },
                // initial transformation
                first_A_EvenEmitted ->
                   first_A_EventEmitted.isConsonant()
                      ? first_A_EventEmitted
                      : "M"
           );
           
       
      Returns B. The first time A emits an event, B emits the result of applying the initial transformation function to that event. For every event emitted after that, B emits the result of applying the reduction function on those events.
           Time --->
           A :-D--O---E---L---K---I--U---T----->
           B :-1--2---3---4---5---6--7---8----->
       
      where "#" is:
      • 1 = "D" ("D" is a consonant)
      • 2 = "DO" ("O" is a vowel)
      • 3 = "DOE" ("E" is a vowel)
      • 4 = "DOE" ("L" is a consonant)
      • 5 = "DOE" ("K" is a consonant)
      • 6 = "DOEI" ("I" is a vowel)
      • 7 = "DOEIU" ("U" is a vowle)
      • 8 = "DOEIU" ("T" is a consonant)
      Parameters:
      reduction - function to add an event to the accumulated value.
      initialTransformation - function to transform the first event from this stream to an event that can be emitted from the returned stream. Subsequent events emitted from this stream are accumulated to the value returned from this function.
    • reduceSuccessions

      default AwaitingEventStream<T> reduceSuccessions(BinaryOperator<T> reduction, Duration timeout)
      Returns an event stream that accumulates events emitted from this event stream in close temporal succession. After an event is emitted from this stream, the returned stream waits for up to timeout for the next event from this stream. If the next event arrives within timeout, it is accumulated to the current event by the reduction function and the timeout is reset. When the timeout expires, the accumulated event is emitted from the returned stream.

      Note: This function can be used only when this stream and the returned stream are used from the JavaFX application thread. If you are using the event streams on a different thread, use reduceSuccessions(BinaryOperator, Duration, ScheduledExecutorService, Executor) instead.

      Parameters:
      reduction - function to reduce two events into one.
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
    • reduceSuccessions

      default <U> AwaitingEventStream<U> reduceSuccessions(Function<? super T,? extends U> initialTransformation, BiFunction<? super U,? super T,? extends U> reduction, Duration timeout)
      A more general version of reduceSuccessions(BinaryOperator, Duration) that allows the accumulated event to be of different type.

      Note: This function can be used only when this stream and the returned stream are used from the JavaFX application thread. If you are using the event streams on a different thread, use reduceSuccessions(Function, BiFunction, Duration, ScheduledExecutorService, Executor) instead.

      Type Parameters:
      U - type of events emitted from the returned stream.
      Parameters:
      initialTransformation - function to transform a single event from this stream to an event that can be emitted from the returned stream.
      reduction - function to add an event to the accumulated value.
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
    • reduceSuccessions

      default <U> AwaitingEventStream<U> reduceSuccessions(Supplier<? extends U> unitSupplier, BiFunction<? super U,? super T,? extends U> reduction, Duration timeout)
      A convenient method that can be used when it is more convenient to supply an identity of the type U than to transform an event of type T to an event of type U. This method is equivalent to reduceSuccessions(t -> reduction.apply(identitySupplier.get(), t), reduction, timeout).

      Note: This function can be used only when this stream and the returned stream are used from the JavaFX application thread. If you are using the event streams on a different thread, use reduceSuccessions(Supplier, BiFunction, Duration, ScheduledExecutorService, Executor) instead.

      Parameters:
      unitSupplier - function that provides the unit element (i.e. initial value for accumulation) of type U
      reduction - function to add an event to the accumulated value.
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
      See Also:
    • reduceSuccessions

      default AwaitingEventStream<T> reduceSuccessions(BinaryOperator<T> reduction, Duration timeout, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
      An analog to reduceSuccessions(BinaryOperator, Duration) to use outside of JavaFX application thread.
      Parameters:
      reduction - function to reduce two events into one.
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
      scheduler - used to schedule timeout expiration
      eventThreadExecutor - executor that executes actions on the thread on which this stream's events are emitted. The returned stream will use this executor to emit events.
    • reduceSuccessions

      default <U> AwaitingEventStream<U> reduceSuccessions(Function<? super T,? extends U> initialTransformation, BiFunction<? super U,? super T,? extends U> reduction, Duration timeout, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
      An analog to reduceSuccessions(Function, BiFunction, Duration) to use outside of JavaFX application thread.
      Parameters:
      initialTransformation - function to transform a single event from this stream to an event that can be emitted from the returned stream.
      reduction - function to accumulate an event to the stored value
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
      scheduler - used to schedule timeout expiration
      eventThreadExecutor - executor that executes actions on the thread on which this stream's events are emitted. The returned stream will use this executor to emit events.
    • reduceSuccessions

      default <U> AwaitingEventStream<U> reduceSuccessions(Supplier<? extends U> unitSupplier, BiFunction<? super U,? super T,? extends U> reduction, Duration timeout, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
      An analog to reduceSuccessions(Supplier, BiFunction, Duration) to use outside of JavaFX application thread.
      Parameters:
      unitSupplier - function that provides the unit element
      reduction - function to accumulate an event to the stored value
      timeout - the maximum time difference between two subsequent events that can still be accumulated.
      scheduler - used to schedule timeout expiration
      eventThreadExecutor - executor that executes actions on the thread on which this stream's events are emitted. The returned stream will use this executor to emit events.
    • successionEnds

      default AwaitingEventStream<T> successionEnds(Duration timeout)
      Returns an event stream that, when events are emitted from this stream in close temporal succession, emits only the last event of the succession. What is considered a close temporal succession is defined by timeout: time gap between two successive events must be at most timeout.

      This method is a shortcut for reduceSuccessions((a, b) -> b, timeout).

      Note: This function can be used only when this stream and the returned stream are used from the JavaFX application thread. If you are using the event streams on a different thread, use successionEnds(Duration, ScheduledExecutorService, Executor) instead.

      Parameters:
      timeout - the maximum time difference between two subsequent events in a close succession.
    • successionEnds

      default AwaitingEventStream<T> successionEnds(Duration timeout, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
      An analog to successionEnds(Duration) to use outside of JavaFX application thread.
      Parameters:
      timeout - the maximum time difference between two subsequent events in a close succession.
      scheduler - used to schedule timeout expiration
      eventThreadExecutor - executor that executes actions on the thread on which this stream's events are emitted. The returned stream will use this executor to emit events.
    • thenAccumulateFor

      default <A> AwaitingEventStream<T> thenAccumulateFor(Duration duration, Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,List<T>> deconstruction)
      Returns an event stream that emits the first event emitted from this stream and then, if the next event arrives within the given duration since the last emitted event, it is converted to an accumulator value using initialTransformation. Any further events that still arrive within duration are accumulated to the accumulator value using the given reduction function. After duration has passed since the last emitted event, the accumulator value is deconstructed into a series of events using the given deconstruction function and these events are emitted, the accumulator value is cleared and any events that arrive within duration are accumulated, and so on.
    • thenAccumulateFor

      default <A> AwaitingEventStream<T> thenAccumulateFor(Duration duration, Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,List<T>> deconstruction, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
    • thenAccumulateFor

      default <A> AwaitingEventStream<T> thenAccumulateFor(Duration duration, Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,List<T>> deconstruction)
      A variant of thenAccumulateFor(Duration, Function, BiFunction, Function) for cases when it is more convenient to provide a unit element for accumulation than the initial transformation.
    • thenAccumulateFor

      default <A> AwaitingEventStream<T> thenAccumulateFor(Duration duration, Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,List<T>> deconstruction, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
    • thenReduceFor

      default AwaitingEventStream<T> thenReduceFor(Duration duration, BinaryOperator<T> reduction)
      Returns an event stream that emits the first event emitted from this stream and then reduces all following events that arrive within the given duration into a single event using the given reduction function. The resulting event, if any, is emitted after duration has passed. Then again, any events that arrive within duration are reduced into a single event, that is emitted after duration has passed, and so on.
    • thenReduceFor

      default AwaitingEventStream<T> thenReduceFor(Duration duration, BinaryOperator<T> reduction, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
    • thenRetainLatestFor

      default AwaitingEventStream<T> thenRetainLatestFor(Duration duration)
      Returns an event stream that emits the first event emitted from this stream and then remembers, but does not emit, the latest event emitted from this stream. The remembered event is emitted after the given duration from the last emitted event. This repeats after each emitted event.
    • thenRetainLatestFor

      default AwaitingEventStream<T> thenRetainLatestFor(Duration duration, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
    • thenIgnoreFor

      default AwaitingEventStream<T> thenIgnoreFor(Duration duration)
      Returns an event stream that emits the first event emitted from this stream and then ignores the following events for the given duration. The first event that arrives after the given duration is emitted and following events are ignored for the given duration again, and so on.
    • thenIgnoreFor

      default AwaitingEventStream<T> thenIgnoreFor(Duration duration, ScheduledExecutorService scheduler, Executor eventThreadExecutor)
    • onRecurseAccumulate

      default <A> EventStream<T> onRecurseAccumulate(Function<? super T,? extends A> initialTransformation, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
    • onRecurseAccumulate

      default <A> EventStream<T> onRecurseAccumulate(Supplier<? extends A> unit, BiFunction<? super A,? super T,? extends A> reduction, Function<? super A,AccumulatorSize> size, Function<? super A,? extends T> head, Function<? super A,? extends A> tail)
    • onRecurseReduce

      default EventStream<T> onRecurseReduce(BinaryOperator<T> reduction)
    • onRecurseQueue

      default EventStream<T> onRecurseQueue()
    • onRecurseRetainLatest

      default EventStream<T> onRecurseRetainLatest()
    • threadBridge

      default EventStream<T> threadBridge(Executor sourceThreadExecutor, Executor targetThreadExecutor)
      Transfers events from one thread to another. Any event stream can only be accessed from a single thread. This method allows to transfer events from one thread to another. Any event emitted by this EventStream will be emitted by the returned stream on a different thread.
      Parameters:
      sourceThreadExecutor - executor that executes tasks on the thread from which this EventStream is accessed.
      targetThreadExecutor - executor that executes tasks on the thread from which the returned EventStream will be accessed.
      Returns:
      Event stream that emits the same events as this EventStream, but uses targetThreadExecutor to emit the events.
    • threadBridgeFromFx

      default EventStream<T> threadBridgeFromFx(Executor targetThreadExecutor)
      Transfers events from the JavaFX application thread to another thread. Equivalent to threadBridge(Platform::runLater, targetThreadExecutor).
      Parameters:
      targetThreadExecutor - executor that executes tasks on the thread from which the returned EventStream will be accessed.
      Returns:
      Event stream that emits the same events as this EventStream, but uses targetThreadExecutor to emit the events.
      See Also:
    • threadBridgeToFx

      default EventStream<T> threadBridgeToFx(Executor sourceThreadExecutor)
      Transfers events to the JavaFX application thread. Equivalent to threadBridge(sourceThreadExecutor, Platform::runLater).
      Parameters:
      sourceThreadExecutor - executor that executes tasks on the thread from which this EventStream is accessed.
      Returns:
      Event stream that emits the same events as this EventStream, but emits them on the JavaFX application thread.
      See Also:
    • guardedBy

      @Deprecated default EventStream<T> guardedBy(Guardian... guardians)
      Deprecated.
      Returns a clone of this event stream guarded by the given guardians. The returned event stream emits the same events as this event stream. In addition to that, the emission of each event is guarded by the given guardians: before the emission, guards are acquired in the given order; after the emission, previously acquired guards are released in reverse order.
    • suspenderOf

      @Experimental default <S extends Suspendable> SuspenderStream<T,S> suspenderOf(S suspendable)
      Returns an event stream that emits the same events as this event stream, but before each emission, suspends the given Suspendable and unsuspends it after the emission has completed.

      Experimental. The method itself is not experimental, but the return type SuspenderStream is. You may want to assign the result to a variable of type EventStream<T> to remain source compatible if the experimenal SuspenderStream is removed in the future.