Context handle passed to context-aware actor handlers. Provides access to the executing actor itself and to the per-dispatch capabilities needed to express FSM-style actors: behavior swaps via #become(ReactorHandler) become(...), message deferral via #stash() / #unstashAll(),
| 40 | * @since 6.0.0 |
| 41 | */ |
| 42 | public interface ActorContext<T> { |
| 43 | |
| 44 | /** |
| 45 | * Returns the actor whose handler is currently executing. |
| 46 | */ |
| 47 | Actor<T> self(); |
| 48 | |
| 49 | /** |
| 50 | * Replaces the handler used to process subsequent messages on a |
| 51 | * reactor actor. The swap takes effect on the next message — the |
| 52 | * current handler invocation completes normally, including binding |
| 53 | * any {@code sendAndGet} reply and firing {@code onError} on failure. |
| 54 | * <p> |
| 55 | * The new handler may declare a different reply type than the original; |
| 56 | * {@code sendAndGet} callers receive the new handler's return value. |
| 57 | * <p> |
| 58 | * Messages already queued at the moment of the swap, and messages sent |
| 59 | * by other threads that have not yet observed the swap, are dispatched |
| 60 | * to the new handler. The new handler is responsible for tolerating any |
| 61 | * message its predecessor could have received — typically by including |
| 62 | * a default branch that ignores or rejects unexpected messages, or by |
| 63 | * deferring them with {@link #stash()} for later replay. |
| 64 | * |
| 65 | * @param newHandler the replacement reactor handler |
| 66 | * @param <R> the new reactor's reply type |
| 67 | * @throws UnsupportedOperationException if this actor is stateful, or |
| 68 | * if this {@code ActorContext} implementation does not support |
| 69 | * behavior swaps |
| 70 | * @throws IllegalStateException if called outside a handler dispatch |
| 71 | * or from a thread other than the actor's worker thread |
| 72 | * @throws NullPointerException if {@code newHandler} is null |
| 73 | * @since 6.0.0 |
| 74 | */ |
| 75 | default <R> void become(ReactorHandler<T, R> newHandler) { |
| 76 | throw new UnsupportedOperationException( |
| 77 | "become(ReactorHandler) requires a reactor actor"); |
| 78 | } |
| 79 | |
| 80 | /** |
| 81 | * Replaces the handler used to process subsequent messages on a |
| 82 | * stateful actor. The current state value is preserved verbatim and |
| 83 | * passed unchanged to the new handler. The swap takes effect on the |
| 84 | * next message. |
| 85 | * <p> |
| 86 | * The state type {@code S} is unchecked at the swap site: if the new |
| 87 | * handler's expected state type is incompatible with the actor's |
| 88 | * current state, a {@link ClassCastException} is thrown when the next |
| 89 | * message is dispatched. |
| 90 | * |
| 91 | * @param newHandler the replacement stateful handler |
| 92 | * @param <S> the state type expected by the new handler |
| 93 | * @throws UnsupportedOperationException if this actor is a reactor, or |
| 94 | * if this {@code ActorContext} implementation does not support |
| 95 | * behavior swaps |
| 96 | * @throws IllegalStateException if called outside a handler dispatch |
| 97 | * or from a thread other than the actor's worker thread |
| 98 | * @throws NullPointerException if {@code newHandler} is null |
| 99 | * @since 6.0.0 |
no outgoing calls
no test coverage detected