Interface EntityRef<M>
-
- All Superinterfaces:
RecipientRef<M>
public interface EntityRef<M> extends RecipientRef<M>
A reference to an sharded Entity, which allowsActorRef
-like usage.An
EntityRef
is NOT anActorRef
–by design–in order to be explicit about the fact that the life-cycle of a sharded Entity is very different than a plain Actors. Most notably, this is shown by features of Entities such as re-balancing (an active Entity to a different node) or passivation. Both of which are aimed to be completely transparent to users of such Entity. In other words, if this were to be a plain ActorRef, it would be possible to apply DeathWatch to it, which in turn would then trigger when the sharded Actor stopped, breaking the illusion that Entity refs are "always there". Please note that while not encouraged, it is possible to expose an Actor'sself
ActorRef
and watch it in case such notification is desired. Not for user extension.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.apache.pekko.actor.typed.RecipientRef
RecipientRef.RecipientRefOps<T>, RecipientRef.RecipientRefOps$
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
$bang(M msg)
Send a message to the entity referenced by this EntityRef using *at-most-once* messaging semantics.<Res> scala.concurrent.Future<Res>
$qmark(scala.Function1<ActorRef<Res>,M> message, Timeout timeout)
Allows to "ask" theEntityRef
for a reply.EntityRef<M>
asJava()
INTERNAL API<Res> scala.concurrent.Future<Res>
ask(scala.Function1<ActorRef<Res>,M> f, Timeout timeout)
Allows to "ask" theEntityRef
for a reply.<Res> scala.concurrent.Future<Res>
askWithStatus(scala.Function1<ActorRef<StatusReply<Res>>,M> f, Timeout timeout)
The same as<Res>ask(scala.Function1<org.apache.pekko.actor.typed.ActorRef<Res>,M>,org.apache.pekko.util.Timeout)
but only for requests that result in a response of typepekko.pattern.StatusReply
.scala.Option<java.lang.String>
dataCenter()
The specified datacenter of the incarnation of the particular entity referenced by this EntityRef, if a datacenter was specified.java.lang.String
entityId()
The identifier for the particular entity referenced by this EntityRef.void
tell(M msg)
Send a message to the entity referenced by this EntityRef using *at-most-once* messaging semantics.EntityTypeKey<M>
typeKey()
The EntityTypeKey associated with this EntityRef.
-
-
-
Method Detail
-
$bang
void $bang(M msg)
Send a message to the entity referenced by this EntityRef using *at-most-once* messaging semantics.Example usage:
val target: EntityRef[String] = ... target ! "Hello"
-
$qmark
<Res> scala.concurrent.Future<Res> $qmark(scala.Function1<ActorRef<Res>,M> message, Timeout timeout)
Allows to "ask" theEntityRef
for a reply. Seepekko.actor.typed.scaladsl.AskPattern
for a complete write-up of this patternNote that if you are inside of an actor you should prefer
pekko.actor.typed.scaladsl.ActorContext.ask
as that provides better safety.Example usage:
case class Request(msg: String, replyTo: ActorRef[Reply]) case class Reply(msg: String) implicit val timeout = Timeout(3.seconds) val target: EntityRef[Request] = ... val f: Future[Reply] = target ? (replyTo => Request("hello", replyTo))
Please note that an implicit
pekko.util.Timeout
must be available to use this pattern.Note: it is preferable to use the non-symbolic ask method as it easier allows for wildcards for the
replyTo: ActorRef
.
-
ask
<Res> scala.concurrent.Future<Res> ask(scala.Function1<ActorRef<Res>,M> f, Timeout timeout)
Allows to "ask" theEntityRef
for a reply. Seepekko.actor.typed.scaladsl.AskPattern
for a complete write-up of this patternNote that if you are inside of an actor you should prefer
pekko.actor.typed.scaladsl.ActorContext.ask
as that provides better safety.Example usage:
case class Request(msg: String, replyTo: ActorRef[Reply]) case class Reply(msg: String) implicit val timeout = Timeout(3.seconds) val target: EntityRef[Request] = ... val f: Future[Reply] = target.ask(Request("hello", _))
Please note that an implicit
pekko.util.Timeout
must be available to use this pattern.
-
askWithStatus
<Res> scala.concurrent.Future<Res> askWithStatus(scala.Function1<ActorRef<StatusReply<Res>>,M> f, Timeout timeout)
The same as<Res>ask(scala.Function1<org.apache.pekko.actor.typed.ActorRef<Res>,M>,org.apache.pekko.util.Timeout)
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
).
-
dataCenter
scala.Option<java.lang.String> dataCenter()
The specified datacenter of the incarnation of the particular entity referenced by this EntityRef, if a datacenter was specified.
-
entityId
java.lang.String entityId()
The identifier for the particular entity referenced by this EntityRef.// given sharding, typeKey sharding.entityRefFor(typeKey, "someId").entityId == "someId" // always true
-
tell
void tell(M msg)
Send a message to the entity referenced by this EntityRef using *at-most-once* messaging semantics.Example usage:
val target: EntityRef[String] = ... target.tell("Hello")
- Specified by:
tell
in interfaceRecipientRef<M>
-
typeKey
EntityTypeKey<M> typeKey()
The EntityTypeKey associated with this EntityRef.
-
-