feat: add interaction results

Author: Citymonstret

state-core/src/main/java/org/incendo/state/StateInteraction.java

@@ -25,8 +25,6 @@
 
 import java.util.Objects;
 import java.util.function.Consumer;
-import java.util.function.Function;
-import java.util.function.UnaryOperator;
 import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.common.returnsreceiver.qual.This;
@@ -49,9 +47,11 @@ public interface StateInteraction<U extends State<U>, V extends Stateful<U, V>>
     /**
      * Executes the interaction.
      *
+     * <p>Any checked exceptions will be wrapped in {@link RuntimeException}.</p>
+     *
      * @return the result of the interaction
      */
-    @NonNull V execute();
+    @NonNull InteractionResult<U, V> execute();
 
     final class Builder<U extends State<U>, V extends Stateful<U, V>> implements StateInteraction<U, V> {
 
@@ -60,14 +60,14 @@ final class Builder<U extends State<U>, V extends Stateful<U, V>> implements Sta
         private States<U> incomingStates;
         private States<U> outgoingStates;
         private States<U> shortCircuitStates;
-        private Function<V, V> interaction;
+        private Interaction<U, V> interaction;
 
         private Builder(final @NonNull V instance) {
             this.instance = Objects.requireNonNull(instance, "instance");
             this.incomingStates = States.of(instance.state());
             this.outgoingStates = instance.allowedTransitions();
             this.shortCircuitStates = States.of();
-            this.interaction = UnaryOperator.identity();
+            this.interaction = Interaction.identity();
         }
 
         /**
@@ -112,7 +112,7 @@ private Builder(final @NonNull V instance) {
          * @param interaction interaction
          * @return {@code this}
          */
-        public @This @NonNull Builder<U, V> interaction(final @NonNull Function<V, V> interaction) {
+        public @This @NonNull Builder<U, V> interaction(final @NonNull Interaction<U, V> interaction) {
             this.interaction = Objects.requireNonNull(interaction, "interaction");
             return this;
         }
@@ -151,8 +151,98 @@ private Builder(final @NonNull V instance) {
          * @return the result of the interaction
          */
         @Override
-        public @NonNull V execute() {
+        public @NonNull InteractionResult<U, V> execute() {
             return this.build().execute();
         }
     }
+
+    @FunctionalInterface
+    interface Interaction<U extends State<U>, V extends Stateful<U, V>> {
+
+        /**
+         * Returns an interaction that immediately returns the incoming stateful.
+         *
+         * @param <U> state type
+         * @param <V> stateful type
+         * @return identity interaction
+         */
+        static <U extends State<U>, V extends Stateful<U, V>> @NonNull Interaction<U, V> identity() {
+            return interaction -> interaction;
+        }
+
+        /**
+         * Performs the interaction.
+         *
+         * @param stateful stateful instance to perform interaction on
+         * @return result of the interaction
+         */
+        @NonNull V interact(@NonNull V stateful) throws Throwable;
+    }
+
+    sealed interface InteractionResult<U extends State<U>, V extends Stateful<U, V>> {
+
+        /**
+         * Returns the stateful instance involved in the interaction.
+         *
+         * @return stateful instance
+         */
+        @NonNull V instance();
+
+        /**
+         * Unwraps the result.
+         *
+         * @return the result of the interaction
+         */
+        @NonNull V unwrap();
+
+        record ShortCircuited<U extends State<U>, V extends Stateful<U, V>>(
+                @NonNull V instance
+        ) implements InteractionResult<U, V> {
+
+            @Override
+            public @NonNull V unwrap() {
+                return this.instance;
+            }
+        }
+
+        record Succeeded<U extends State<U>, V extends Stateful<U, V>>(
+                @NonNull V instance,
+                @NonNull V result
+        ) implements InteractionResult<U, V> {
+
+            @Override
+            public @NonNull V unwrap() {
+                return this.result;
+            }
+        }
+
+        sealed interface Failed<U extends State<U>, V extends Stateful<U, V>> extends InteractionResult<U, V> {
+
+            /**
+             * Returns the exception produced by the interaction.
+             *
+             * @return interaction exception
+             */
+            @NonNull UnexpectedStateException exception();
+
+            @Override
+            default @NonNull V unwrap() {
+                throw this.exception();
+            }
+
+            record IllegalIncomingState<U extends State<U>, V extends Stateful<U, V>>(
+                    @NonNull V instance,
+                    @NonNull UnexpectedStateException exception
+            ) implements Failed<U, V> {
+            }
+
+            record IllegalOutgoingState<U extends State<U>, V extends Stateful<U, V>>(
+                    @NonNull V instance,
+                    @NonNull V result,
+                    @NonNull UnexpectedStateException exception
+            ) implements Failed<U, V> {
+
+            }
+        }
+    }
 }

state-core/src/main/java/org/incendo/state/StateInteractionImpl.java

@@ -24,7 +24,6 @@
 package org.incendo.state;
 
 import java.util.concurrent.locks.Lock;
-import java.util.function.Function;
 import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
@@ -34,11 +33,11 @@ record StateInteractionImpl<U extends State<U>, V extends Stateful<U, V>>(
         @NonNull States<U> incomingStates,
         @NonNull States<U> outgoingStates,
         @NonNull States<U> shortcircuitStates,
-        @NonNull Function<V, V> interaction
+        @NonNull Interaction<U, V> interaction
 ) implements StateInteraction<U, V> {
 
     @Override
-    public @NonNull V execute() {
+    public @NonNull InteractionResult<U, V> execute() {
         final Lock lock;
         if (this.instance instanceof AbstractLockableStateful<?, ?> lockableStateful) {
             lock = lockableStateful.lock().writeLock();
@@ -54,21 +53,36 @@ record StateInteractionImpl<U extends State<U>, V extends Stateful<U, V>>(
             final U currentState = this.instance.state();
 
             if (this.shortcircuitStates.contains(currentState)) {
-                return this.instance;
+                return new InteractionResult.ShortCircuited<>(this.instance);
             }
 
             if (!this.incomingStates.contains(currentState)) {
-                throw new UnexpectedStateException(this.incomingStates, currentState, this.instance);
+                return new InteractionResult.Failed.IllegalIncomingState<>(
+                        this.instance,
+                        new UnexpectedStateException(this.incomingStates, currentState, this.instance)
+                );
             }
 
-            final V result = this.interaction.apply(this.instance);
+            final V result;
+
+            try {
+                result = this.interaction.interact(this.instance);
+            } catch (final RuntimeException e) {
+                throw e;
+            } catch (final Throwable throwable) {
+                throw new RuntimeException(throwable);
+            }
 
             final U newState = result.state();
             if (!this.outgoingStates.contains(newState)) {
-                throw new UnexpectedStateException(this.outgoingStates, newState, result);
+                return new InteractionResult.Failed.IllegalOutgoingState<>(
+                        this.instance,
+                        result,
+                        new UnexpectedStateException(this.outgoingStates, newState, result)
+                );
             }
 
-            return result;
+            return new InteractionResult.Succeeded<>(this.instance, result);
         } finally {
             if (lock != null) {
                 lock.unlock();

state-core/src/test/java/org/incendo/state/IntegrationTest.java

@@ -68,15 +68,17 @@ void test() {
                 .outgoingStates(States.of(TestState.INTERMEDIARY_FOO))
                 .shortCircuitStates(States.of(TestState.INTERMEDIARY_FOO))
                 .interaction(instance -> instance.foo().transitionTo(TestState.INTERMEDIARY_FOO))
-                .execute();
+                .execute()
+                .unwrap();
     }
 
     private @NonNull TestObject end(final @NonNull TestObject object) {
         return object.interact()
                 .outgoingStates(States.of(TestState.END_STATE))
                 .shortCircuitStates(States.of(TestState.END_STATE))
                 .interaction(instance -> instance.transitionTo(TestState.END_STATE))
-                .execute();
+                .execute()
+                .unwrap();
     }
 
     enum TestState implements State<TestState> {