Wether to use @SingleResult Publisher or return Flux, Mono or Flowable, Single in Guides

[sdelamo]

While reviewing #382, I have suggested rewriting a controller return a RxJava 2 type such as:

@Controller
public class HomeController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get
    public Single<String> index() {
        return Single.just("Boom");

As:

@Controller
public class HomeController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get
    @SingleResult
    public Publisher<String> index() {
        return Single.just("Boom");

@graeme commented out:

Why this is not a module?

RxJava2 code in guides needs migrated for Micronaut 3. The previous snippet with Single will not work in a Micronaut 3 application out of the Box.

If the user does not want to change the code, they need to add: io.micronaut.rxjava2:micronaut-rxjava2.

However, we suggest the users to move to Project Reactor

We recommend switching to Project Reactor as that is the implementation used internally by Micronaut. Adding a dependency to RxJava2 will result in both implementations in the runtime classpath of your application.

Thus, at least we should rewrite the code as: \

@Controller
public class HomeController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get
    public Mono<String> index() {
        return Mono.just("Boom");

For the above code, we will need to tell the user to add:

io.micronaut.reactor:micronaut-reactor

or

io.projectreactor:reactor-core

What I suggest is to use:

@Controller
public class HomeController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get
    @SingleResult
    public Publisher<String> index() {
        return Mono.just("Boom");

Moreover, for simple reactive code (e.g. usage of just) we could use Micronaut's Publishers` own class. With the benefit that the user does not need to even add a reactive library dependency.

@Controller
public class HomeController {

    @Get
    @SingleResult
    public Publisher<String> index() {
        return Publishers.just("Boom");

I think in public methods, we should do encourage users to use Publisher or @SingleResult Publisher or reactive streams with a single emitted item.

• Users reading guides may become library authors in the future, public library authors or company internal library authors. Libraries ensure a better interoperability if they don't couple themselves to any reactive implementation.
• We show users the same paradigm used in the Micronuat modules. If they want to contribute they will understand what @SingleResult does and the pattern of not exposing a reactive implementation in our code base.
• We keep a reactive implementation agnostic position. For guides, which need to transform streams (e.g. map operators), we will include Project Reactor but the contract remains reactive implementation agnostic.
• Guides code is easier to maintain. If in the future, we change the recommended reactive library the less Reactor code we have, the less work to updates the guides.

[sdelamo]

@micronaut-projects/core-developers thoughts?

[sdelamo]

Suggesting ‘Publisher’ means you need to explain ‘SingleResult’ and if you forget it we are doing streaming by default which will affect performance if you don’t actually need it. IMHO we should switch to the opposite and have the single result by default and introduce ‘@streaming’

@dstepanov I think this is a discussion worth having in core.

[sdelamo]

This is to decide. For the public methods in the guides sample apps, we use:

A) Mono and Flux.
B) @SingleResult Publisher and Publisher.

So far @graemerocher @dstepanov and @ilopmar lean towards A.

I will leave this open a couple of days. I consensus is to use A, I will do the changes in the 3.0.x branch.

[jameskleeh]

To me the benefit of using @SingleResult Publisher is that users can easily translate that code to whatever reactive streams implementation they are comfortable with. Using Mono and Flux may confuse those who are only familiar with RxJava and the opposite is also true.

The recommended approach is to use Reactor because that will already be a dependency on users runtime classpath and thus using another implementation will be another dependency on their classpath that could be avoided.

I think because we want to encourage users to use Reactor, we should use it in the guides. @sdelamo Do note that adding a dependency on io.projectreactor:reactor-core is not enough because that doesn't contain the converters.

[sdelamo]

@jameskleeh since both Mono and Flowable are Publishers and we have a Publisher converter. A user can have a controller returning Mono and have only a dependency to reactor-core and it works.

For RxJava2, they will need micronaut-rxjava2 because Single is needs a converter.

[jameskleeh]

We don't have a Publisher to Flux converter in core, or any converters related to reactor. If it happens to work its because the thing being converted from is what you're trying to convert it to, thus no conversion is required. That of course is working just by circumstance and is dependent on the internal behavior of Micronaut which is not part of the API. The dependency on micronaut-reactor is necessary