⚠️ This stream of the feature pack only supports WildFly 23. For previous versions of WildFly, try the 1.0.x releases. This is because MicroProfile Reactive Messaging and the Kafka integration moved into WildFly 23. Prior to WildFly 23, those pieces of functionality were supplied by this feature pack.
If you are an end-user and not a project developer (or especially interested), use the latest tag for this README and other information.
This repository contains a Galleon feature pack to extend the MicroProfile reactive subsystems offered by WildFly. WildFly 23 itself contains:
- MicroProfile Reactive Messaging 1.0 ** The Kafka connector
- MicroProfile Reactive Streams Operators 1.0
This feature pack contains functionality to:
- Allow MicroProfile Reactive Messaging functionality beyond what is offered by 1.0, by passing in the
-Djboss.as.reactive.messaging.experimental=truesystem property on server start. This allows you to use@ChannelandEmitterwhich were introduced after 1.0. These allow you to have user-initiated code interact with the streams managed by Reactive Messaging. - Enable MicroProfile Context Propagation 1.0. This is useful in the context of user-initiated code interacting with the streams, for example to be able to propagate the main thread's transaction to reactive style callouts which might be happening in another thread.
- Enable other connectors for Reactive Messaging, currently we have ** MQTT ** AMQP
If you would like to see more Reactive Messaging connectors here and are willing to give integrating them a go, we use the SmallRye implementations. Get in touch if you are interested, and I can offer advice.
Galleon is the tool we use internally to build the WildFly server. See the Galleon documentation for more background about the concepts.
If you are an end-user and not a project developer (or especially interested), use the latest tag for this README and other information.
To install the feature pack you need to download Galleon (use the 5.x series)
and unzip it somewhere. The rest of this document assumes that you have added the resulting galleon-x.y.z.Final/bin/ folder
to your path.
The easiest way to install a WildFly Server with MicroProfile reactive specs is (Download provision.xml first):
galleon.sh provision /path/to/provision.xml --dir=wildfly
This installs a full WildFly installation and everything from this feature pack in the wildfly/ directory.
Later we will look at what the above command means, other ways to install the server and how to tweak what is
installed.
Take a look at our Quickstarts for examples of how to use the MicroProfile Reactive specifications in your applications.
The rest of this README will explain the structure of this feature pack in more detail. If you are itching to get going try the quickstarts first and come back to this.
To provision a server containing the microprofile reactive specs, you use Galleon to first install the base
WildFly server, and then add layers from this feature pack. We will see exactly how this is done later in this guide,
but it essentially allows you to create smaller servers containing exactly the parts of functionality that
you want for your application.
A layer is a unit of functionality. Each subsystem in WildFly has its own layer. For example there is
a cdi layer for the weld subsystem, a jaxrs layer for the jaxrs subsystem and
an undertow layer for the undertow subsystem.
Layers can have dependencies between them, and when asking to install a particular layer, all the layer's dependencies are also installed recursively.
There are some 'aggregate' layers, provided for convenience, such as cloud-server which pulls in a set of layers
that we deem important for a server running on OpenShift. It results in a server with JAX-RS, JPA, Transactions amd
Weld (CDI) amongst other things.
There is a list of all our layers defined by WildFly and WildFly Core in our documentation.
If you want to understand better what their dependencies are, you can look at the layer-spec.xml for the various layers in the following locations:
- WildFly Core's Core Feature Pack
- WildFly's Servlet Feature Pack
- WildFly's EE Feature Pack
- WildFly's MicroProfile Feature Pack
We will use 'WildFly Galleon Pack' to refer to these various feature packs.
Note that the above links take you to the versions used for WildFly 23.0.0.Final. If you are interested in another/newer WildFly version, adjust the tag name in the URL.
The layers from this feature pack are contained in the feature-pack/src/main/resources/layers/standalone folder. We'll explain what each of them contains, and their direct dependencies on other layers.
The microprofile-context-propagation layer installs the microprofile-context-propagation-smallrye subsystem, so you can use
the MicroProfile Context Propagation APIs
from your application. The traditional way of propagating state using ThreadLocals does not work well in the reactive
world. Async/reactive code often creates a 'pipeline' of code blocks that get executed 'later' - in practice after the
method defining them has returned. MicroProfile Context Propagation is there to help you deal with this, so that your
deferred code can still for example latch onto the transaction initiated by the calling method.
Note although the core context propagation mechanism works, we are still missing things in WildFly 20 for this to work totally. You currently get context propagation for the following:
Application- This propagates the Thread Context ClassLoaderCDI- propagates the CDI contextTransaction- not enabled by default, see themicroprofile-context-propagation-jtalayer below
What is missing is:
Web= propagation of parameter injected web contextRestEasy- propagation of parameter injected RestEasy contextSecurity- propagation of the security context
This might still be enough for your application, and we hope to be able to add these soon.
Layer Dependencies:
cdi- From the WildFly Galleon Pack. It contains theweldsubsystem which implements Jakarta EE CDI.microprofile-config- From the WildFly Galleon Pack. It contains themicroprofile-config-smallryesubsystem which implements MicroProfile Config.microprofile-reactive-streams-operators- From the WildFly Galleon Pack. It contains themicroprofile-reactive-streams-operators-smallryesubsystem so you can use the MicroProfile Reactive Streams Operators classes from your application.
The microprofile-context-propagation-jta layer installs the ThreadContextProvider propagating transactions.
Layer Dependencies:
microprofile-context-propagation- From this feature pack, as described in this document.transactions- From the WildFly Galleon Pack. It contains thetransactionssubsystem which contains theTransactionManager. This is needed for propagation of the current transaction.
The microprofile-reactive-messaging-amqp layer installs the AMQP connector so you can interact with AMQP enabled message
brokers.
Layer Dependencies:
microprofile-reactive-messaging- From this feature pack, as described above.
This is no longer part of this feature pack, as it has been moved to the WildFly Galleon Pack. But you can
still use it when provisioning a server with other parts of this feature pack.
The microprofile-reactive-messaging-kafka layer installs the Kafka connector so you can interact with Kafka streams.
Layer Dependencies:
microprofile-reactive-messaging- From the WildFly Galleon Pack. It contains themicroprofile-reactive-messaging-smallryesubsystem so you can use the MicroProfile Reactive Messaging classes from your application.
The microprofile-reactive-messaging-mqtt layer installs the MQTT connector so you can interact with a MQTT server.
Layer Dependencies:
microprofile-reactive-messaging- From the WildFly Galleon Pack. It contains themicroprofile-reactive-messaging-smallryesubsystem so you can use the MicroProfile Reactive Messaging classes from your application.
The microprofile-reactive-messaging-connectors layer is a convenience layer, which installs all the connector layers mentioned above.
Layer Dependencies:
microprofile-reactive-messaging-amqp- From this feature pack, as described above.microprofile-reactive-messaging-kafka- From the WildFly Galleon Pack. It installs the Kafka connector so you can interact with a Kafka server.microprofile-reactive-messaging-mqtt- From this feature pack, as described above.
The microprofile-reactive-all layer is a convenience layer, which installs all the layers mentioned above.
Download Galleon as mentioned in the introduction. There are two main ways of provisioning a server containing the MicroProfile Reactive specifications. The first is to provision from a file, as we saw in the introduction. The second is to execute all the Galleon commands individually.
In both cases we install the main WildFly server (possibly with some tweaks) and then we install layers we choose from this feature pack.
Galleon can not modify the server you download from the wildfly.org downloads page. Instead you have to install WildFly using Galleon before adding the layers from this feature pack. Both the ways shown do this.
The provision.xml file contains everything we need to install a server with the MicroProfile reactive spec subsystems.
It contains a reference to the WildFly feature pack. It's version is current which means it will download the
latest released version (which at the time of writing is 23.0.0.Final. If you want to choose a different version,
you can modify the file and append the version as current:23.0.1.Final for example.
Next it contains a reference to this feature pack.
Finally it lists the layers to install:
cloud-profileis from the WildFly Full Feature Pack, and is similar tocloud-serverbut smaller.microprofile-reactive-allinstalls everything from this feature pack
To adjust what exactly you want to install, you can modify this file. As we saw in the introduction we can run:
galleon.sh provision /path/to/provision.xml --dir=wildfly
This installs a full WildFly installation and everything from this feature pack in the wildfly/ child directory
indicated by the -dir flag.
We need to first install our base WildFly server, and then add the layers from this feature pack. This is great if you want to experiment with different combinations. Once you are happy you can create a provision.xml file like we saw above.
First we need to install base server. To do this, we run Galleon to install the full WildFly server (the result will be the same as the zip you download from the wildfly.org downloads page):
galleon.sh install wildfly:current --dir=wildfly
The wildfly:current above tells Galleon to provision the latest version of WildFly which
at the time of writing is 23.0.0.Final. If you want to install a particular version of
WildFly, you can append the version, e.g:
wildfly:current#23.0.0.Final- installs WildFly from locally build maven artifacts
Note that the minimal supported WildFly version for this feature pack is 23.0.0.Final.
--dir specifies the directory to install the server into. In this case I am using
a relative directory called wildfly.
The first time you do this, it will probably take some time while it downloads everything. After the first installation it should be a lot faster.
If you want to trim the base server that we install you can specify which layers to install by passing in
the --layers option. For example to install a smaller base server, you can run the following instead:
galleon.sh install wildfly:current --dir=wildfly --layers=cloud-profile
Note that we do not install our MicroProfile reactive layers yet, because they are unknown in the main WildFly feature pack. We will add those in the next step.
If you want to keep your server as small as possible, and you miss something that is ok. You
can rerun the above command, and pass in more layers in the --layers option if you missed something.
Now to install our feature pack, we can run:
galleon.sh install org.wildfly.extras.reactive:wildfly-microprofile-reactive-feature-pack:3.0.1.Final-SNAPSHOT --layers=microprofile-reactive-all --dir=wildfly
which will install all the layers from the MicroProfile reactive feature pack.
To just install the microprofile-reactive-streams-operators and microprofile-context-propagation layers, we run this instead:
galleon.sh install org.wildfly.extras.reactive:wildfly-microprofile-reactive-feature-pack:3.0.1.Final-SNAPSHOT --layers=microprofile-reactive-streams-operators,microprofile-context-propagation --dir=wildfly
- MicroProfile Reactive Messaging specification
- SmallRye Reactive Messaging documentation
- SmallRye Reactive Messaging Source
- MicroProfile Reactive Streams Operators specification
- SmallRye Reactive Streams Operators documentation
- SmallRye Reactive Streams Operators source code
- MicroProfile Context Propagation specification
- SmallRye Context Propagation source code