Class Behaviors


  • public class Behaviors
    extends java.lang.Object
    Factories for Behavior.
    • Constructor Detail

      • Behaviors

        public Behaviors()
    • Method Detail

      • setup

        public static <T> Behavior<T> setup​(Function<ActorContext<T>,​Behavior<T>> factory)
        setup is a factory for a behavior. Creation of the behavior instance is deferred until the actor is started, as opposed to receive(akka.japi.function.Function2<akka.actor.typed.javadsl.ActorContext<T>, T, akka.actor.typed.Behavior<T>>) that creates the behavior instance immediately before the actor is running. The factory function pass the ActorContext as parameter and that can for example be used for spawning child actors.

        setup is typically used as the outer most behavior when spawning an actor, but it can also be returned as the next behavior when processing a message or signal. In that case it will be started immediately after it is returned, i.e. next message will be processed by the started behavior.

        Parameters:
        factory - (undocumented)
        Returns:
        (undocumented)
      • same

        public static <T> Behavior<T> same()
        Return this behavior from message processing in order to advise the system to reuse the previous behavior. This is provided in order to avoid the allocation overhead of recreating the current behavior where that is not necessary.
        Returns:
        (undocumented)
      • unhandled

        public static <T> Behavior<T> unhandled()
        Return this behavior from message processing in order to advise the system to reuse the previous behavior, including the hint that the message has not been handled. This hint may be used by composite behaviors that delegate (partial) handling to other behaviors.
        Returns:
        (undocumented)
      • stopped

        public static <T> Behavior<T> stopped()
        Return this behavior from message processing to signal that this actor shall terminate voluntarily. If this actor has created child actors then these will be stopped as part of the shutdown procedure.

        The PostStop signal that results from stopping this actor will be passed to the current behavior. All other messages and signals will effectively be ignored.

        Returns:
        (undocumented)
      • stopped

        public static <T> Behavior<T> stopped​(Behavior<T> postStop)
        Return this behavior from message processing to signal that this actor shall terminate voluntarily. If this actor has created child actors then these will be stopped as part of the shutdown procedure.

        The PostStop signal that results from stopping this actor will be passed to the given postStop behavior. All other messages and signals will effectively be ignored.

        Parameters:
        postStop - (undocumented)
        Returns:
        (undocumented)
      • empty

        public static <T> Behavior<T> empty()
        A behavior that treats every incoming message as unhandled.
        Returns:
        (undocumented)
      • ignore

        public static <T> Behavior<T> ignore()
        A behavior that ignores every incoming message and returns &ldquo;same&rdquo;.
        Returns:
        (undocumented)
      • receive

        public static <T> Behavior<T> receive​(Function2<ActorContext<T>,​T,​Behavior<T>> onMessage)
        Construct an actor behavior that can react to incoming messages but not to lifecycle signals. After spawning this actor from another actor (or as the guardian of an ActorSystem) it will be executed within an ActorContext that allows access to the system, spawning and watching other actors, etc.

        Compared to using AbstractBehavior this factory is a more functional style of defining the Behavior. Processing the next message results in a new behavior that can potentially be different from this one. State is maintained by returning a new behavior that holds the new immutable state.

        Parameters:
        onMessage - (undocumented)
        Returns:
        (undocumented)
      • receive

        public static <T> Behavior<T> receive​(Function2<ActorContext<T>,​T,​Behavior<T>> onMessage,
                                              Function2<ActorContext<T>,​Signal,​Behavior<T>> onSignal)
        Construct an actor behavior that can react to both incoming messages and lifecycle signals. After spawning this actor from another actor (or as the guardian of an ActorSystem) it will be executed within an ActorContext that allows access to the system, spawning and watching other actors, etc.

        Compared to using AbstractBehavior this factory is a more functional style of defining the Behavior. Processing the next message results in a new behavior that can potentially be different from this one. State is maintained by returning a new behavior that holds the new immutable state.

        Parameters:
        onMessage - (undocumented)
        onSignal - (undocumented)
        Returns:
        (undocumented)
      • receive

        public static <T> BehaviorBuilder<T> receive​(java.lang.Class<T> type)
        Constructs an actor behavior builder that can build a behavior that can react to both incoming messages and lifecycle signals.

        Compared to using AbstractBehavior this factory is a more functional style of defining the Behavior. Processing the next message results in a new behavior that can potentially be different from this one. State is maintained by returning a new behavior that holds the new immutable state.

        Parameters:
        type - the supertype of all messages accepted by this behavior
        Returns:
        the behavior builder
      • receiveSignal

        public static <T> Behavior<T> receiveSignal​(Function2<ActorContext<T>,​Signal,​Behavior<T>> handler)
        Construct an actor behavior that can react to lifecycle signals only.
        Parameters:
        handler - (undocumented)
        Returns:
        (undocumented)
      • monitor

        public static <T> Behavior<T> monitor​(ActorRef<T> monitor,
                                              Behavior<T> behavior)
        Behavior decorator that copies all received message to the designated monitor ActorRef before invoking the wrapped behavior. The wrapped behavior can evolve (i.e. return different behavior) without needing to be wrapped in a monitor call again.
        Parameters:
        monitor - (undocumented)
        behavior - (undocumented)
        Returns:
        (undocumented)
      • logMessages

        public static <T> Behavior<T> logMessages​(Behavior<T> behavior)
        Behavior decorator that logs all messages to the Behavior using the provided LogOptions default configuration before invoking the wrapped behavior. To include an MDC context then first wrap logMessages with withMDC.
        Parameters:
        behavior - (undocumented)
        Returns:
        (undocumented)
      • logMessages

        public static <T> Behavior<T> logMessages​(LogOptions logOptions,
                                                  Behavior<T> behavior)
        Behavior decorator that logs all messages to the Behavior using the provided LogOptions configuration before invoking the wrapped behavior. To include an MDC context then first wrap logMessages with withMDC.
        Parameters:
        logOptions - (undocumented)
        behavior - (undocumented)
        Returns:
        (undocumented)
      • supervise

        public static <T> Behaviors.Supervise<T> supervise​(Behavior<T> wrapped)
        Wrap the given behavior such that it is restarted (i.e. reset to its initial state) whenever it throws an exception of the given class or a subclass thereof. Exceptions that are not subtypes of Thr will not be caught and thus lead to the termination of the actor.

        It is possible to specify different supervisor strategies, such as restart, resume, backoff.

        The SupervisorStrategy is only invoked for "non fatal" (see NonFatal) exceptions.

        Example:

        
         final Behavior[DbCommand] dbConnector = ...
        
         final Behavior[DbCommand] dbRestarts =
            Behaviors.supervise(dbConnector)
              .onFailure(SupervisorStrategy.restart) // handle all NonFatal exceptions
        
         final Behavior[DbCommand] dbSpecificResumes =
            Behaviors.supervise(dbConnector)
              .onFailure[IndexOutOfBoundsException](SupervisorStrategy.resume) // resume for IndexOutOfBoundsException exceptions
         
        Parameters:
        wrapped - (undocumented)
        Returns:
        (undocumented)
      • widened

        public static <T,​U> Behavior<U> widened​(Behavior<T> behavior,
                                                      java.util.function.Function<PFBuilder<U,​T>,​PFBuilder<U,​T>> selector)
        Widen the wrapped Behavior by placing a funnel in front of it: the supplied PartialFunction decides which message to pull in (those that it is defined at) and may transform the incoming message to place them into the wrapped Behavior&rsquo;s type hierarchy. Signals are not transformed.

        Example:

        
         Behavior<String> s = Behaviors.receive((ctx, msg) -> {
             System.out.println(msg);
             return Behaviors.same();
           });
         Behavior<Number> n = Behaviors.widened(s, pf -> pf.
                 match(BigInteger.class, i -> "BigInteger(" + i + ")").
                 match(BigDecimal.class, d -> "BigDecimal(" + d + ")")
                 // drop all other kinds of Number
             );
         

        Scheduled messages via TimerScheduler can currently not be used together with widen, see issue #25318.

        Parameters:
        behavior - the behavior that will receive the selected messages
        selector - a partial function builder for describing the selection and transformation
        Returns:
        a behavior of the widened type
      • withTimers

        public static <T> Behavior<T> withTimers​(Function<TimerScheduler<T>,​Behavior<T>> factory)
        Support for scheduled self messages in an actor. It takes care of the lifecycle of the timers such as cancelling them when the actor is restarted or stopped.
        Parameters:
        factory - (undocumented)
        Returns:
        (undocumented)
        See Also:
        TimerScheduler
      • withMdc

        public static <T> Behavior<T> withMdc​(Function<T,​java.util.Map<java.lang.String,​java.lang.Object>> mdcForMessage,
                                              Behavior<T> behavior)
        Per message MDC (Mapped Diagnostic Context) logging.

        Parameters:
        mdcForMessage - Is invoked before each message is handled, allowing to setup MDC, MDC is cleared after each message processing by the inner behavior is done.
        behavior - The actual behavior handling the messages, the MDC is used for the log entries logged through ActorContext.log

        See also akka.actor.typed.Logger.withMdc

        Returns:
        (undocumented)
      • withMdc

        public static <T> Behavior<T> withMdc​(java.util.Map<java.lang.String,​java.lang.Object> staticMdc,
                                              Behavior<T> behavior)
        Static MDC (Mapped Diagnostic Context)

        Parameters:
        staticMdc - This MDC is setup in the logging context for every message
        behavior - The actual behavior handling the messages, the MDC is used for the log entries logged through ActorContext.log

        See also akka.actor.typed.Logger.withMdc

        Returns:
        (undocumented)
      • withMdc

        public static <T> Behavior<T> withMdc​(java.util.Map<java.lang.String,​java.lang.Object> staticMdc,
                                              Function<T,​java.util.Map<java.lang.String,​java.lang.Object>> mdcForMessage,
                                              Behavior<T> behavior)
        Combination of static and per message MDC (Mapped Diagnostic Context).

        Each message will get the static MDC plus the MDC returned for the message. If the same key are in both the static and the per message MDC the per message one overwrites the static one in the resulting log entries.

        * The staticMdc or mdcForMessage may be empty.

        Parameters:
        staticMdc - A static MDC applied for each message
        mdcForMessage - Is invoked before each message is handled, allowing to setup MDC, MDC is cleared after each message processing by the inner behavior is done.
        behavior - The actual behavior handling the messages, the MDC is used for the log entries logged through ActorContext.log

        See also akka.actor.typed.Logger.withMdc

        Returns:
        (undocumented)