Interface ActorContext<T>
-
- All Superinterfaces:
ClassicActorContextProvider
,TypedActorContext<T>
- All Known Subinterfaces:
ActorContextImpl<T>
public interface ActorContext<T> extends TypedActorContext<T>, ClassicActorContextProvider
An Actor is given by the combination of aBehavior
and a context in which this behavior is executed. As per the Actor Model an Actor can perform the following actions when processing a message:- send a finite number of messages to other Actors it knows - create a finite number of Actors - designate the behavior for the next message
In Pekko, the first capability is accessed by using the
tell
method on anActorRef
, the second is provided byspawn(org.apache.pekko.actor.typed.Behavior<U>, java.lang.String)
and the third is implicit in the signature ofBehavior
in that the next behavior is always returned from the message processing logic.An
ActorContext
in addition provides access to the Actor’s own identity (“getSelf
”), theActorSystem
it is part of, methods for querying the list of child Actors it created, access toTerminated
and timed message scheduling.Not for user extension.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <Req,Res>
voidask(java.lang.Class<Res> resClass, RecipientRef<Req> target, java.time.Duration responseTimeout, Function<ActorRef<Res>,Req> createRequest, Function2<Res,java.lang.Throwable,T> applyToResponse)
Perform a single request-response message interaction with another actor, and transform the messages back to the protocol of this actor.<Req,Res>
voidaskWithStatus(java.lang.Class<Res> resClass, RecipientRef<Req> target, java.time.Duration responseTimeout, Function<ActorRef<StatusReply<Res>>,Req> createRequest, Function2<Res,java.lang.Throwable,T> applyToResponse)
The same as<Req,Res>ask(java.lang.Class<Res>,org.apache.pekko.actor.typed.RecipientRef<Req>,java.time.Duration,org.apache.pekko.japi.function.Function<org.apache.pekko.actor.typed.ActorRef<Res>,Req>,org.apache.pekko.japi.function.Function2<Res,java.lang.Throwable,T>)
but only for requests that result in a response of typepekko.pattern.StatusReply
.ActorContext<T>
asScala()
Get thescaladsl
of thisActorContext
.void
cancelReceiveTimeout()
Cancel the sending of receive timeout notifications.Behavior<T>
delegate(Behavior<T> delegator, T msg)
Delegate message and signal's execution by givenpekko.actor.typed.Behavior
usingBehavior.interpretMessage
orBehavior.interpretSignal
java.util.Optional<ActorRef<java.lang.Void>>
getChild(java.lang.String name)
The named child Actor if it is alive.java.util.List<ActorRef<java.lang.Void>>
getChildren()
The list of child Actors created by this Actor during its lifetime that are still alive, in no particular order.scala.concurrent.ExecutionContextExecutor
getExecutionContext()
This Actor’s execution context.org.slf4j.Logger
getLog()
An actor specific logger.ActorRef<T>
getSelf()
The identity of this Actor, bound to the lifecycle of this Actor instance.ActorSystem<java.lang.Void>
getSystem()
TheActorSystem
to which this Actor belongs.<U> ActorRef<U>
messageAdapter(java.lang.Class<U> messageClass, Function<U,T> f)
Create a message adapter that will convert or wrap messages such that other Actor’s protocols can be ingested by this Actor.<Value> void
pipeToSelf(java.util.concurrent.CompletionStage<Value> future, Function2<Value,java.lang.Throwable,T> applyToResult)
Sends the result of the givenCompletionStage
to this Actor (“self
”), after adapted it with the given function.<U> Cancellable
scheduleOnce(java.time.Duration delay, ActorRef<U> target, U msg)
Schedule the sending of the given message to the given target Actor after the given time period has elapsed.void
setLoggerName(java.lang.Class<?> clazz)
Replace the current logger (or initialize a new logger if the logger was not touched before) with one that has ghe given class name as logger name.void
setLoggerName(java.lang.String name)
Replace the current logger (or initialize a new logger if the logger was not touched before) with one that has ghe given name as logger name.void
setReceiveTimeout(java.time.Duration timeout, T msg)
Schedule the sending of a notification in case no other message is received during the given period of time.<U> ActorRef<U>
spawn(Behavior<U> behavior, java.lang.String name)
Create a child Actor from the givenpekko.actor.typed.Behavior
and with the given name.<U> ActorRef<U>
spawn(Behavior<U> behavior, java.lang.String name, Props props)
Create a child Actor from the givenpekko.actor.typed.Behavior
and with the given name.<U> ActorRef<U>
spawnAnonymous(Behavior<U> behavior)
Create a child Actor from the givenpekko.actor.typed.Behavior
under a randomly chosen name.<U> ActorRef<U>
spawnAnonymous(Behavior<U> behavior, Props props)
Create a child Actor from the givenpekko.actor.typed.Behavior
under a randomly chosen name.<U> void
stop(ActorRef<U> child)
Force the child Actor under the given name to terminate after it finishes processing its current message.<U> void
unwatch(ActorRef<U> other)
Revoke the registration established bywatch
.<U> void
watch(ActorRef<U> other)
Register forTerminated
notification once the Actor identified by the givenActorRef
terminates.<U> void
watchWith(ActorRef<U> other, T msg)
Register for termination notification with a custom message once the Actor identified by the givenActorRef
terminates.-
Methods inherited from interface org.apache.pekko.actor.ClassicActorContextProvider
classicActorContext
-
Methods inherited from interface org.apache.pekko.actor.typed.TypedActorContext
asJava
-
-
-
-
Method Detail
-
asScala
ActorContext<T> asScala()
Get thescaladsl
of thisActorContext
.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.- Specified by:
asScala
in interfaceTypedActorContext<T>
-
ask
<Req,Res> void ask(java.lang.Class<Res> resClass, RecipientRef<Req> target, java.time.Duration responseTimeout, Function<ActorRef<Res>,Req> createRequest, Function2<Res,java.lang.Throwable,T> applyToResponse)
Perform a single request-response message interaction with another actor, and transform the messages back to the protocol of this actor.The interaction has a timeout (to avoid a resource leak). If the timeout hits without any response it will be passed as an
TimeoutException
to theapplyToResponse
function.For other messaging patterns with other actors, see
messageAdapter(java.lang.Class<U>, org.apache.pekko.japi.function.Function<U, T>)
.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.- Parameters:
createRequest
- A function that creates a message for the other actor, containing the providedActorRef[Res]
that the other actor can send a message back through.applyToResponse
- Transforms the response from thetarget
into a message this actor understands. Will be invoked with either the response message or an AskTimeoutException failed or potentially another exception if the remote actor is classic and sent apekko.actor.Status.Failure
as response. The returned message of typeT
is then fed into this actor as a message. Should be a pure function but is executed inside the actor when the response arrives so can safely touch the actor internals. If this function throws an exception it is just as if the normal message receiving logic would throw.
-
askWithStatus
<Req,Res> void askWithStatus(java.lang.Class<Res> resClass, RecipientRef<Req> target, java.time.Duration responseTimeout, Function<ActorRef<StatusReply<Res>>,Req> createRequest, Function2<Res,java.lang.Throwable,T> applyToResponse)
The same as<Req,Res>ask(java.lang.Class<Res>,org.apache.pekko.actor.typed.RecipientRef<Req>,java.time.Duration,org.apache.pekko.japi.function.Function<org.apache.pekko.actor.typed.ActorRef<Res>,Req>,org.apache.pekko.japi.function.Function2<Res,java.lang.Throwable,T>)
but only for requests that result in a response of typepekko.pattern.StatusReply
. If the response is apekko.pattern.StatusReply#success
the returned future is completed successfully with the wrapped response. If the status response is apekko.pattern.StatusReply#error
the returned future will be failed with the exception in the error (normally apekko.pattern.StatusReply.ErrorMessage
).
-
cancelReceiveTimeout
void cancelReceiveTimeout()
Cancel the sending of receive timeout notifications.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
delegate
Behavior<T> delegate(Behavior<T> delegator, T msg)
Delegate message and signal's execution by givenpekko.actor.typed.Behavior
usingBehavior.interpretMessage
orBehavior.interpretSignal
note: if given
pekko.actor.typed.Behavior
resultingBehaviors.same
that will cause context switching to the given behavior and if result isBehaviors.unhandled
that will trigger thepekko.actor.typed.scaladsl.ActorContext.onUnhandled
then switching to the given behavior.
-
getChild
java.util.Optional<ActorRef<java.lang.Void>> getChild(java.lang.String name)
The named child Actor if it is alive.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
getChildren
java.util.List<ActorRef<java.lang.Void>> getChildren()
The list of child Actors created by this Actor during its lifetime that are still alive, in no particular order.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
getExecutionContext
scala.concurrent.ExecutionContextExecutor getExecutionContext()
This Actor’s execution context. It can be used to run asynchronous tasks likeFuture
combinators.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
getLog
org.slf4j.Logger getLog()
An actor specific logger.The logger name will be an estimated source class for the actor which is calculated when the logger is first used (the logger is lazily created upon first use). If this yields the wrong class or another class is preferred this can be changed with
setLoggerName
.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
getSelf
ActorRef<T> getSelf()
The identity of this Actor, bound to the lifecycle of this Actor instance. An Actor with the same name that lives before or after this instance will have a differentActorRef
.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
getSystem
ActorSystem<java.lang.Void> getSystem()
TheActorSystem
to which this Actor belongs.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
messageAdapter
<U> ActorRef<U> messageAdapter(java.lang.Class<U> messageClass, Function<U,T> f)
Create a message adapter that will convert or wrap messages such that other Actor’s protocols can be ingested by this Actor.You can register several message adapters for different message classes. It's only possible to have one message adapter per message class to make sure that the number of adapters are not growing unbounded if registered repeatedly. That also means that a registered adapter will replace an existing adapter for the same message class.
A message adapter will be used if the message class matches the given class or is a subclass thereof. The registered adapters are tried in reverse order of their registration order, i.e. the last registered first.
A message adapter (and the returned
ActorRef
) has the same lifecycle as this actor. It's recommended to register the adapters in a top levelBehaviors.setup
or constructor ofAbstractBehavior
but it's possible to register them later also if needed. Message adapters don't have to be stopped since they consume no resources other than an entry in an internalMap
and the number of adapters are bounded since it's only possible to have one per message class.The function is running in this actor and can safely access state of it.
*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
pipeToSelf
<Value> void pipeToSelf(java.util.concurrent.CompletionStage<Value> future, Function2<Value,java.lang.Throwable,T> applyToResult)
Sends the result of the givenCompletionStage
to this Actor (“self
”), after adapted it with the given function.This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
scheduleOnce
<U> Cancellable scheduleOnce(java.time.Duration delay, ActorRef<U> target, U msg)
Schedule the sending of the given message to the given target Actor after the given time period has elapsed. The scheduled action can be cancelled by invokingpekko.actor.Cancellable#cancel
on the returned handle.For scheduling messages to the actor itself, use
Behaviors.withTimers
This method is thread-safe and can be called from other threads than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
setLoggerName
void setLoggerName(java.lang.String name)
Replace the current logger (or initialize a new logger if the logger was not touched before) with one that has ghe given name as logger name. Logger source MDC entry "pekkoSource" will be the actor path.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
setLoggerName
void setLoggerName(java.lang.Class<?> clazz)
Replace the current logger (or initialize a new logger if the logger was not touched before) with one that has ghe given class name as logger name. Logger source MDC entry "pekkoSource" will be the actor path.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
setReceiveTimeout
void setReceiveTimeout(java.time.Duration timeout, T msg)
Schedule the sending of a notification in case no other message is received during the given period of time. The timeout starts anew with each received message. UsecancelReceiveTimeout
to switch off this mechanism.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
spawn
<U> ActorRef<U> spawn(Behavior<U> behavior, java.lang.String name)
Create a child Actor from the givenpekko.actor.typed.Behavior
and with the given name.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
spawn
<U> ActorRef<U> spawn(Behavior<U> behavior, java.lang.String name, Props props)
Create a child Actor from the givenpekko.actor.typed.Behavior
and with the given name.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
spawnAnonymous
<U> ActorRef<U> spawnAnonymous(Behavior<U> behavior)
Create a child Actor from the givenpekko.actor.typed.Behavior
under a randomly chosen name. It is good practice to name Actors wherever practical.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
spawnAnonymous
<U> ActorRef<U> spawnAnonymous(Behavior<U> behavior, Props props)
Create a child Actor from the givenpekko.actor.typed.Behavior
under a randomly chosen name. It is good practice to name Actors wherever practical.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
stop
<U> void stop(ActorRef<U> child)
Force the child Actor under the given name to terminate after it finishes processing its current message. Nothing happens if the ActorRef is a child that is already stopped.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.- Throws:
java.lang.IllegalArgumentException
- if the given actor ref is not a direct child of this actorc
-
unwatch
<U> void unwatch(ActorRef<U> other)
Revoke the registration established bywatch
. ATerminated
notification will not subsequently be received for the referenced Actor.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
watch
<U> void watch(ActorRef<U> other)
Register forTerminated
notification once the Actor identified by the givenActorRef
terminates. This message is also sent when the watched actor is on a node that has been removed from the cluster when using Pekko Cluster.watch
is idempotent if it is not mixed withwatchWith
.It will fail with an
IllegalStateException
if the same subject was watched before usingwatchWith
. To clear the termination message, unwatch first.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
watchWith
<U> void watchWith(ActorRef<U> other, T msg)
Register for termination notification with a custom message once the Actor identified by the givenActorRef
terminates. This message is also sent when the watched actor is on a node that has been removed from the cluster when using Pekko Cluster.watchWith
is idempotent if it is called with the samemsg
and not mixed withwatch
.It will fail with an
IllegalStateException
if the same subject was watched before usingwatch
orwatchWith
with another termination message. To change the termination message, unwatch first.*Warning*: This method is not thread-safe and must not be accessed from threads other than the ordinary actor message processing thread, such as
CompletionStage
callbacks.
-
-