feat: support the flattening syntax for supervising

[Roiocam]

MOTIVATION

Continue #680

The original api wasn't flatening.

Behaviors.supervise(
        Behaviors.supervise(behavior)
            .onFailure(IllegalStateException.class, SupervisorStrategy.restart()))
    .onFailure(IllegalArgumentException.class, SupervisorStrategy.stop());

RELATED WORK

• scaladsl
• javadsl
• documentation
• made unit test passed
• binary compatibility

[Roiocam]

The scala test migration is more than this, I will open a sperate PR for this.

[raboof]

I really think we should not just add things to mima backwards excludes, but also add comments why the exclusions are justified.

In this case it looks, to me, like the mima errors were actually legitimate and this PR breaks our binary compatibility promises documented at https://pekko.apache.org/docs/pekko/current/common/binary-compatibility-rules.html and https://github.com/apache/pekko/blob/main/CONTRIBUTING.md#binary-compatibility

To make things explicit: suppose we have an application 'A' which uses a library 'L' which depends on Pekko 1.0.0 . The point of the binary compatibility rules is that it should be safe for 'A' to update to Pekko 1.1.0 without breaking.

In this case, if L contained:

val s: Behaviors.Supervise = Behaviors.supervise(SupervisedActor.create())

... AFAICS this code would throw a runtime exception when executed with any Pekko version that has the change in this PR, because Behaviors.Supervise no longer exists.

[Roiocam]

I really think we should not just add things to mima backwards excludes, but also add comments why the exclusions are justified.

I totally agree with that.

In this case it looks, to me, like the mima errors were actually legitimate

Yes.

What should we do when we face such API changes?

[raboof]

What should we do when we face such API changes?

It depends on the situation. I haven't looked closely, but in this case, it looks like the SuperviseBehaviour was introduced to reduce code duplication between the two Behavior.Supervise classes, is that correct? I wonder if we could restore binary compatibility while still avoiding code duplication by restoring the Behavior.Supervise classes, but having them extends SuperviseBehaviour. If that does not work, possibly we should just choose to accept some duplication to achieve compatibility.

[Roiocam]

I has been fix these binary compatibility via some duplicate code. would you take a look?

[raboof]

seems like a nice syntax

[raboof]

So these are OK because the old signatures returned Behavior, and the new ones return SuperviseBehavior, and since SuperviseBehavior extends Behavior every SuperviseBehavior is a Behavior? Sounds reasonable.

[raboof]

This one as well (checked with javap)

[Roiocam]

Thanks @raboof, let we merged it.