Getting Started
This section contains information that should help you get going with Reactor. It includes the following sections:
1. Introducing Reactor
Reactor is a fully non-blocking reactive programming foundation for the JVM, with
efficient demand management (in the form of managing “backpressure”). It integrates
directly with the Java 8 functional APIs, notably CompletableFuture
, Stream
, and
Duration
. It offers composable asynchronous sequence APIs — Flux
(for [N] elements) and
Mono
(for [0|1] elements) — and extensively implements the
Reactive Streams specification.
Reactor also supports non-blocking inter-process communication with the
reactor-netty
project. Suited for Microservices Architecture, Reactor Netty offers
backpressure-ready network engines for HTTP (including Websockets), TCP, and UDP.
Reactive encoding and decoding are fully supported.
2. Prerequisites
Reactor Core runs on Java 8
and above.
It has a transitive dependency on org.reactivestreams:reactive-streams:1.0.3
.
Android Support
|
3. Understanding the BOM and versioning scheme
Reactor 3 uses a BOM (Bill of Materials) model (since reactor-core 3.0.4
, with the Aluminium
release train).
This curated list groups artifacts that are meant to work well together, providing
the relevant versions despite potentially divergent versioning schemes in these artifacts.
Note the versioning scheme has changed between 3.3.x and 3.4.x (Dysprosium and Europium).
Artifacts follow a versioning scheme of MAJOR.MINOR.PATCH-QUALIFIER
while the BOM is versioned using a CalVer inspired scheme of YYYY.MINOR.PATCH-QUALIFIER
, where:
-
MAJOR
is the current generation of Reactor, where each new generation can bring fundamental changes to the structure of the project (which might imply a more significant migration effort) -
YYYY
is the year of the first GA release in a given release cycle (like 3.4.0 for 3.4.x) -
.MINOR
is a 0-based number incrementing with each new release cycle-
in the case of projects, it generally reflects wider changes and can indicate a moderate migration effort
-
in the case of the BOM it allows discerning between release cycles in case two get first released the same year
-
-
.PATCH
is a 0-based number incrementing with each service release -
-QUALIFIER
is a textual qualifier, which is omitted in the case of GA releases (see below)
The first release cycle to follow that convention is thus 2020.0.x
, codename Europium
.
The scheme uses the following qualifiers (note the use of dash separator), in order:
-
-M1
..-M9
: milestones (we don’t expect more than 9 per service release) -
-RC1
..-RC9
: release candidates (we don’t expect more than 9 per service release) -
-SNAPSHOT
: snapshots -
no qualifier for GA releases
snapshots appear higher in the order above because, conceptually, they’re always "the freshest pre-release" of any given PATCH. Even though the first deployed artifact of a PATCH cycle will always be a -SNAPSHOT, a similarly named but more up-to-date snapshot would also get released after eg. a milestone or between release candidates. |
Each release cycle is also given a codename, in continuity with the previous codename-based scheme, which can be used to reference it more informally (like in discussions, blog posts, etc…). The codenames represent what would traditionally be the MAJOR.MINOR number. They (mostly) come from the Periodic Table of Elements, in increasing alphabetical order.
Up until Dysprosium, the BOM was versioned using a release train scheme with a codename followed by a qualifier, and the qualifiers were slightly different. For example: Aluminium-RELEASE (first GA release, would now be something like YYYY.0.0), Bismuth-M1, Californium-SR1 (service release would now be something like YYYY.0.1), Dysprosium-RC1, Dysprosium-BUILD-SNAPSHOT (after each patch, we’d go back to the same snapshot version. would now be something like YYYY.0.X-SNAPSHOT so we get 1 snapshot per PATCH) |
4. Getting Reactor
As mentioned earlier, the easiest way to use Reactor in your core is to use the BOM and add the relevant dependencies to your project. Note that, when you add such a dependency, you must omit the version so that the version gets picked up from the BOM.
However, if you want to force the use of a specific artifact’s version, you can specify it when adding your dependency, as you usually would. You can also forgo the BOM entirely and specify dependencies by their artifact versions.
As of this version (reactor-core 3.7.1), the latest stable BOM in the associated
release train line is 2024.0.1 , which is what is used in snippets below.
There might be newer versions since then (including snapshots, milestones and new release train lines),
see projectreactor.io/docs for the latest artifacts and BOMs.
|
4.1. Maven Installation
Maven natively supports the BOM concept. First, you need to import the BOM by
adding the following snippet to your pom.xml
:
<dependencyManagement> (1)
<dependencies>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-bom</artifactId>
<version>2024.0.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
1 | Notice the dependencyManagement tag. This is in addition to the regular
dependencies section. |
If the top section (dependencyManagement
) already exists in your pom, add only the contents.
Next, add your dependencies to the relevant reactor projects, as usual, except without a
<version>
, as follows:
<dependencies>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId> (1)
(2)
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-test</artifactId> (3)
<scope>test</scope>
</dependency>
</dependencies>
1 | Dependency on the core library. |
2 | No version tag here. |
3 | reactor-test provides facilities to unit test reactive streams. |
4.2. Gradle Installation
Prior to version 5.0, Gradle has no core support for Maven BOMs, but you can use Spring’s gradle-dependency-management plugin.
First, apply the plugin from the Gradle Plugin Portal, as follows:
plugins {
id "io.spring.dependency-management" version "1.0.7.RELEASE" (1)
}
1 | as of this writing, 1.0.7.RELEASE is the latest version of the plugin. Check for updates. |
Then use it to import the BOM, as follows:
dependencyManagement {
imports {
mavenBom "io.projectreactor:reactor-bom:2024.0.1"
}
}
Finally add a dependency to your project, without a version number, as follows:
dependencies {
implementation 'io.projectreactor:reactor-core' (1)
}
1 | There is no third : separated section for the version. It is taken from
the BOM. |
Since Gradle 5.0, you can use the native Gradle support for BOMs:
dependencies {
implementation platform('io.projectreactor:reactor-bom:2024.0.1')
implementation 'io.projectreactor:reactor-core' (1)
}
1 | There is no third : separated section for the version. It is taken from
the BOM. |
4.3. Milestones and Snapshots
Milestones and developer previews are distributed through the Spring Milestones repository rather than Maven Central. To add it to your build configuration file, use the following snippet:
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones Repository</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
For Gradle, use the following snippet:
repositories {
maven { url 'https://repo.spring.io/milestone' }
mavenCentral()
}
Similarly, snapshots are also available in a separate dedicated repository, as the following example show:
<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshot Repository</name>
<url>https://repo.spring.io/snapshot</url>
</repository>
</repositories>
repositories {
maven { url 'https://repo.spring.io/snapshot' }
mavenCentral()
}
5. Support and policies
The entries below are mirroring github.com/reactor/.github/blob/main/SUPPORT.adoc
5.1. Do you have a question?
Search Stack Overflow first; discuss if necessary |
If you’re unsure why something isn’t working or wondering if there is a better way of doing it please check on Stack Overflow first and if necessary start a discussion. Use relevant tags among the ones we monitor for that purpose:
-
reactor-netty
for specific reactor-netty questions -
project-reactor
for generic reactor questions
If you prefer real-time discussion, we also have a few Gitter channels:
-
reactor
is the historic most active one, where most of the community can help -
reactor-core
is intended for more advanced pinpointed discussions around the inner workings of the library -
reactor-netty
is intended for netty-specific questions
Refer to each project’s README for potential other sources of information.
We generally discourage opening GitHub issues for questions, in favor of the two channels above.
5.2. Our policy on deprecations
When dealing with deprecations, given a version A.B.C
, we’ll ensure that:
-
deprecations introduced in version
A
.B
.0
will be removed no sooner than versionA
.B+1
.0
-
deprecations introduced in version
A
.B
.1+
will be removed no sooner than versionA
.B+2
.0
-
we’ll strive to mention the following in the deprecation javadoc:
-
target minimum version for removal
-
pointers to replacements for the deprecated method
-
version in which method was deprecated
-
This policy is officially in effect as of January 2021, for all modules in 2020.0 BOMs and newer release trains, as well as Dysprosium releases after Dysprosium-SR15 .
|
Deprecation removal targets are not a hard commitment, and the deprecated methods could live on further than these minimum target GA versions (ie. only the most problematic deprecated methods will be removed aggressively). |
That said, deprecated code that has outlived its minimum removal target version may be removed in any subsequent release (including patch releases, aka service releases) without further notice. So users should still strive to update their code as early as possible. |
5.3. Support Timeline
Our GA release cadence is annual. The next release train is 2025
. The timeline is
subject to change.
The following table summarises the support dates for each individual project followed by the BOM support.
Version | Initial OSS Release | OSS Support End | Commercial Support (*) End | Published in BOM |
---|---|---|---|---|
reactor-core |
||||
3.7 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
3.6 |
2023-11-14 |
2025-08-31 |
2026-12-31 |
2023 |
3.5 |
2022-11-08 |
2024-08-31 |
2025-12-31 |
2022 |
3.4 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-netty |
||||
1.2 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
1.1 |
2022-11-08 |
2025-08-31 |
2026-12-31 |
2022, 2023 |
1.0 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-kafka |
||||
1.3 |
2020-10-26 |
2026-08-31 |
2027-12-31 |
2020, 2022, 2023, 2024 |
reactor-pool |
||||
1.1 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
1.0 |
2022-11-08 |
2025-08-31 |
2026-12-31 |
2022, 2023 |
0.2 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-addons |
||||
3.5 |
2022-11-08 |
2026-08-31 |
2027-12-31 |
2022, 2023, 2024 |
3.4 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-kotlin-extensions |
||||
1.2 |
2022-11-08 |
2026-08-31 |
2027-12-31 |
2022, 2023, 2024 |
1.1 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-rabbitmq |
||||
1.5 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-bom |
||||
2024 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
- |
2023 |
2023-11-14 |
2025-08-31 |
2026-12-31 |
- |
2022 |
2022-11-08 |
2024-08-31 |
2025-12-31 |
- |
2020 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
- |
(*) Commercial Support For more information visit Spring Support page. |