includes.reactivestreams.rsoperators.adoc Maven / Gradle / Ivy

Go to download
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2020, 2024 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

ifndef::rootdir[:rootdir: {docdir}/../..]
:feature-name: Reactive Streams

include::{rootdir}/includes/attributes.adoc[]

== Contents

- <>
- <>
- <>
- <>

== Overview

Helidon implements link:{microprofile-rs-operators-spec-url}[MicroProfile Reactive Streams Operators] specification which defines reactive operators and provides a standardized tool for manipulation with https://www.reactive-streams.org/[Reactive Streams]. You can use MicroProfile Reactive Streams Operators when you want to maintain source-level portability between different implementations.

include::{rootdir}/includes/dependencies.adoc[]

[source,xml]
----

   io.helidon.microprofile.reactive-streams
   helidon-microprofile-reactive-streams

----

== Usage

The MicroProfile Reactive Streams Operators specification provides a set of operators within stages,
as well as the builders used to prepare graphs of stages from which streams can be built.

[source,java]
.Example of simple closed graph usage:
----
include::{sourcedir}/includes/reactivestreams/RsoperatorsSnippets.java[tag=snippet_1, indent=0]
----

[[terms]]
.Operators(Stages)
|===
|fromIterable | Create new PublisherBuilder from supplied Iterable
|of | Create new PublisherBuilder emitting supplied elements
|ofNullable | Empty stream if supplied item is null
|iterate | Create infinite stream with every next item created by supplied operator from previous item
|generate| Create infinite stream with every item created by invocation of supplier
|empty| Create new PublisherBuilder emitting as a first thing complete signal
|failed| Create new PublisherBuilder emitting as a first thing error signal
|concat| Concat two streams
|coupled| Two parallel streams sharing cancel, onError and onComplete signals
|limit| Limit the size of the stream, when limit is reached completes
|peek| Invoke consumer for every item passing this operator
|filter| Drop item when expression result to false
|map| Transform items
|flatMap| Flatten supplied stream to current stream
|flatMapIterable| Flatten supplied iterable to current stream
|flatMapCompletionStage| Map elements to completion stage and wait for each to be completed, keeps the order
|flatMapRSPublisher| Map elements to Publishers and flatten this sub streams to original stream
|takeWhile| Let items pass until expression is true, first time its false completes
|dropWhile| Drop items until expression is true, first time its false let everything pass
|skip| Drop first n items
|distinct| Let pass only distinct items
|via| Connect supplied processor to current stream return supplied processor
|onError| Invoke supplied consumer when onError signal received
|onErrorResume| Emit one last supplied item when onError signal received
|onErrorResumeWith| When onError signal received continue emitting from supplied publisher builder
|onErrorResumeWithRsPublisher| When onError signal received continue emitting from supplied publisher
|onComplete| Invoke supplied runnable when onComplete signal received
|onTerminate| Invoke supplied runnable when onComplete or onError signal received
|ifEmpty| Executes given `java.lang.Runnable` when stream is finished without value(empty stream).
|to| Connect this stream to supplied subscriber
|toList| Collect all intercepted items to List
|collect| Collect all intercepted items with provided collector
|forEach| Invoke supplied Consumer for each intercepted item
|ignore| Ignore all onNext signals, wait for onComplete
|reduce| Reduction with provided expression
|cancel| Cancel stream immediately
|findFirst| Return first intercepted element
|===

=== Graphs

link:{microprofile-rs-operators-spec-url}#_graphs[Graphs] are pre-prepared stream builders with
 link:{microprofile-rs-operators-spec-url}#_stages[stages], which can be combined to closed graph with methods
 `via` and `to`.

[source,java]
.Combining the graphs and running the stream:
----
include::{sourcedir}/includes/reactivestreams/RsoperatorsSnippets.java[tag=snippet_2, indent=0]
----

== Reference

* link:{microprofile-rs-operators-spec-url}[MicroProfile Reactive Streams Operators Specification]
* link:{microprofile-rs-operators-javadoc-url}[MicroProfile Reactive Streams Operators JavaDoc]
* link:https://github.com/eclipse/microprofile-reactive-streams-operators[MicroProfile Reactive Streams Operators on GitHub]