3.x: [Java 8] Implement mapOptional, collector, first/last/single stage

[akarnokd]

This PR implements the following Flowable operators:

• mapOptional - essentially a map-filter via Optionals.
• collect(Collector) - use the Java 8 Collector API, see Collectors.
• firstStage - return the first item or a default value as a CompletionStage.
• firstOrErrorStage - return the first item or error as a CompletionStage.
• singleStage - return the only item or a default value as a CompletionStage.
• singleOrErrorStage - return the only item or error as a CompletionStage.
• lastStage - return the last item or a default value as a CompletionStage.
• lastOrErrorStage - return the last item or error as a CompletionStage.

Related: #6776

Diagrams:

[codecov]

Codecov Report

Merging #6775 into 3.x will increase coverage by 0.02%.
The diff coverage is 100%.

@@             Coverage Diff             @@
##               3.x    #6775      +/-   ##
===========================================
+ Coverage     98.2%   98.22%   +0.02%     
- Complexity    6187     6234      +47     
===========================================
  Files          681      688       +7     
  Lines        44776    45041     +265     
  Branches      6164     6193      +29     
===========================================
+ Hits         43971    44243     +272     
+ Misses         281      279       -2     
+ Partials       524      519       -5

Impacted Files	Coverage Δ	Complexity Δ
...3/internal/jdk8/FlowableSingleStageSubscriber.java	100% <100%> (ø)	8 <8> (?)
...ernal/jdk8/FlowableCollectWithCollectorSingle.java	100% <100%> (ø)	3 <3> (?)
...rxjava3/internal/jdk8/FlowableStageSubscriber.java	100% <100%> (ø)	10 <10> (?)
...va3/internal/jdk8/FlowableLastStageSubscriber.java	100% <100%> (ø)	7 <7> (?)
...a3/internal/jdk8/FlowableFirstStageSubscriber.java	100% <100%> (ø)	6 <6> (?)
.../main/java/io/reactivex/rxjava3/core/Flowable.java	100% <100%> (ø)	570 <8> (+8)	⬆️
...a3/internal/jdk8/FlowableCollectWithCollector.java	100% <100%> (ø)	2 <2> (?)
...vex/rxjava3/internal/jdk8/FlowableMapOptional.java	100% <100%> (ø)	3 <3> (?)
...l/operators/observable/ObservableFlatMapMaybe.java	90.14% <0%> (-2.12%)	2% <0%> (ø)
...perators/single/SingleFlatMapIterableFlowable.java	95% <0%> (-1.67%)	2% <0%> (ø)
... and 26 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0fba7c5...5337a00. Read the comment docs.

[JakeWharton]

I wonder if these are actually useful compared to just using the regular Single-returning operators and then calling a toStage().

[JakeWharton]

Or, put another way, would you add blockingFirstOptional() and blockingLastOptional() and the like or would you expect people to using the Single-returning operators and then call blockingOptional()?

[akarnokd]

I'm not sure. We have first and blockingFirst so in case of a firstStage -> first().toCompletionStage() change, wouldn't the API consistency require us dropping blockingFirst for first().blockingGet()?

[JakeWharton]

I don't mind that. It keeps you inside the reactive APIs for transforming the data into the shape you want and then you can use a conversion or blocking operator to escape.

Up to you though. Just thinking of how to minimize the number of operators needed to support these new types.

[akarnokd]

I'd keep them for now and see if I can beef up blockingGet with macro-fusion (as their backing specific implementation is to be reused there). If it can be done reasonably well, I'm willing to drop blockingX, and xStage operators.