Scala 2.11 API: Each extension typically provide a concrete ExtensionSetup
that can be used in
akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default
implementation of the extension.
Scala 2.11 API: Each extension typically provide a concrete ExtensionSetup
that can be used in
akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default
implementation of the extension. Intended for tests that need to replace
extension with stub/mock implementations.
This trait is not meant to be extended by user code.
This trait is not meant to be extended by user code. If you do so, you may lose binary compatibility.
Not for user extension.
An ActorRef is the identity or address of an Actor instance.
An ActorRef is the identity or address of an Actor instance. It is valid only during the Actor’s lifetime and allows messages to be sent to that Actor instance. Sending a message to an Actor that has terminated before receiving the message will lead to that message being discarded; such messages are delivered to the DeadLetter channel of the akka.event.EventStream on a best effort basis (i.e. this delivery is not reliable).
Serialization and deserialization of ActorRef
.
Serialization and deserialization of ActorRef
.
This class is not intended for user extension other than for test purposes (e.g. stub implementation). More methods may be added in the future and that may break such implementations.
Can be used in akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default implementation of the ActorRefResolver extension.
Can be used in akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default implementation of the ActorRefResolver extension. Intended for tests that need to replace extension with stub/mock implementations.
An ActorSystem is home to a hierarchy of Actors.
An ActorSystem is home to a hierarchy of Actors. It is created using ActorSystem#apply from a Behavior object that describes the root Actor of this hierarchy and which will create all other Actors beneath it. A system also implements the ActorRef type, and sending a message to the system directs that message to the root Actor.
Not for user extension.
The behavior of an actor defines how it reacts to the messages that it receives.
The behavior of an actor defines how it reacts to the messages that it receives. The message may either be of the type that the Actor declares and which is part of the ActorRef signature, or it may be a system Signal that expresses a lifecycle event of either this actor or one of its child actors.
Behaviors can be formulated in a number of different ways, either by using the DSLs in akka.actor.typed.scaladsl.Behaviors and akka.actor.typed.javadsl.Behaviors or extending the abstract ExtensibleBehavior class.
Closing over ActorContext makes a Behavior immobile: it cannot be moved to another context and executed there, and therefore it cannot be replicated or forked either.
This base class is not meant to be extended by user code. If you do so, you may lose binary compatibility.
Not for user extension.
Envelope for dead letters.
Exception that an actor fails with if it does not handle a Terminated message.
Not for user extension.
Not for user extension.
An ActorSystem looks up all its thread pools via a Dispatchers instance.
Envelope that is published on the eventStream for every message that is dropped due to overfull queues.
Extension point for implementing custom behaviors in addition to the existing set of behaviors available through the DSLs in akka.actor.typed.scaladsl.Behaviors and akka.actor.typed.javadsl.Behaviors
Marker trait/interface for extensions.
Marker trait/interface for extensions. An extension can be registered in the ActorSystem and is guaranteed to only
have one instance per ActorSystem instance per ExtensionId. The extension internals must be thread safe.
For mutable state it should be preferred to use an Actor
rather than extensions as first choice.
Identifier and factory for an extension.
Identifier and factory for an extension. Is used to look up an extension from the ActorSystem
, and possibly create
an instance if no instance was already registered. The extension can also be listed in the actor system configuration
to have it eagerly loaded and registered on actor system startup.
*Scala API*
The ExtensionId
for an extension written in Scala is best done by letting it be the companion object of the
extension. If the extension will be used from Java special care needs to be taken to provide a get
method with the
concrete extension type as return (as this will not be inferred correctly by the Java compiler with the default
implementation)
Example:
object MyExt extends ExtensionId[Ext] { override def createExtension(system: ActorSystem[_]): MyExt = new MyExt(system) // Java API: retrieve the extension instance for the given system. def get(system: ActorSystem[_]): MyExt = apply(system) } class MyExt(system: ActorSystem[_]) extends Extension { ... } // can be loaded eagerly on system startup through configuration // note that the name is the JVM/Java class name, with a dollar sign in the end // and not the Scala object name akka.actor.typed.extensions = ["com.example.MyExt$"] // Allows access like this from Scala MyExt().someMethodOnTheExtension() // and from Java MyExt.get(system).someMethodOnTheExtension()
*Java API*
To implement an extension in Java you should first create an ExtensionId
singleton by implementing a static method
called getInstance
, this is needed to be able to list the extension among the akka.actor.typed.extensions
in the configuration
and have it loaded when the actor system starts up.
public class MyExt extends AbstractExtensionId<MyExtImpl> { // single instance of the identifier private final static MyExt instance = new MyExt(); // protect against other instances than the singleton private MyExt() {} // This static method singleton accessor is needed to be able to enable the extension through config when // implementing extensions in Java. public static MyExt getInstance() { return instance; } public MyExtImpl createExtension(ActorSystem<?> system) { return new MyExtImpl(); } // convenience accessor public static MyExtImpl get(ActorSystem<?> system) { return instance.apply(system); } } public class MyExtImpl implements Extension { ... } // can be loaded eagerly on system startup through configuration akka.actor.typed.extensions = ["com.example.MyExt"] // Allows access like this from Scala MyExt.someMethodOnTheExtension() // and from Java MyExt.get(system).someMethodOnTheExtension()
For testing purposes extensions typically provide a concrete ExtensionSetup that can be used in akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default implementation of the extension.
The concrete extension type
Each extension typically provide a concrete ExtensionSetup
that can be used in
akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default
implementation of the extension.
Each extension typically provide a concrete ExtensionSetup
that can be used in
akka.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default
implementation of the extension. Intended for tests that need to replace
extension with stub/mock implementations.
API for registering and looking up extensions.
API for registering and looking up extensions.
Not for user extension.
A log marker is an additional metadata tag supported by some logging backends to identify "special" log events.
A log marker is an additional metadata tag supported by some logging backends to identify "special" log events. In the Akka internal actors for example the "SECURITY" marker is used for warnings related to security.
Not for user extension, create instances using factory methods
Logging API provided inside of actors through the actor context.
Logging API provided inside of actors through the actor context.
All log-level methods support simple interpolation templates with up to four
arguments placed by using {}
within the template (first string
argument):
ctx.log.error(exception, "Exception while processing {} in state {}", msg, state)
More than four arguments can be defined by using an Array
with the method with
one argument parameter.
*Rationale for an Akka-specific logging API:* Provided rather than a specific logging library logging API to not enforce a specific logging library on users but still providing a convenient, performant, asynchronous and testable logging solution. Additionally it allows unified logging for both user implemented actors and built in Akka actors where the actual logging backend can be selected by the user. This logging facade is also used by Akka internally, without having to depend on specific logging frameworks.
The Logger of an actor is tied to the actor path and should not be shared with other threads outside of the actor.
Not for user extension
Lifecycle signal that is fired after this actor and all its child actors (transitively) have terminated.
Lifecycle signal that is fired after this actor and all its child actors (transitively) have terminated. The Terminated signal is only sent to registered watchers after this signal has been processed.
Lifecycle signal that is fired upon restart of the Actor before replacing the behavior with the fresh one (i.e.
Lifecycle signal that is fired upon restart of the Actor before replacing the behavior with the fresh one (i.e. this signal is received within the behavior that failed). The replacement behavior will receive PreStart as its first signal.
Data structure for describing an actor’s props details like which executor to run it on.
Data structure for describing an actor’s props details like which executor to run it on. For each type of setting (e.g. DispatcherSelector) the FIRST occurrence is used when creating the actor; this means that adding configuration using the "with" methods overrides what was configured previously.
Deliberately not sealed in order to emphasize future extensibility by the framework—this is not intended to be extended by user code.
Not for user extension.
The configuration settings that were parsed from the config by an ActorSystem.
The configuration settings that were parsed from the config by an ActorSystem. This class is immutable.
System signals are notifications that are generated by the system and delivered to the Actor behavior in a reliable fashion (i.e.
System signals are notifications that are generated by the system and delivered to the Actor behavior in a reliable fashion (i.e. they are guaranteed to arrive in contrast to the at-most-once semantics of normal Actor messages).
A message protocol for actors that support spawning a child actor when receiving a SpawnProtocol#Spawn message and sending back the ActorRef of the child actor.
A message protocol for actors that support spawning a child actor when receiving a SpawnProtocol#Spawn message and sending back the ActorRef of the child actor. An implementation of a behavior for this protocol is defined in SpawnProtocol#behavior. That can be used as is or composed with other behavior using Behavior#orElse.
The typical usage of this is to use it as the guardian actor of the ActorSystem, possibly combined with
Behaviors.setup
to starts some initial tasks or actors. Child actors can then be started from the outside
by telling or asking SpawnProtocol#Spawn to the actor reference of the system. When using ask
this is
similar to how akka.actor.ActorSystem#actorOf can be used in untyped actors with the difference that
a Future
/ CompletionStage
of the ActorRef
is returned.
Lifecycle signal that is fired when an Actor that was watched has terminated.
Lifecycle signal that is fired when an Actor that was watched has terminated. Watching is performed by invoking the akka.actor.typed.scaladsl.ActorContext.watch. The DeathWatch service is idempotent, meaning that registering twice has the same effect as registering once. Registration does not need to happen before the Actor terminates, a notification is guaranteed to arrive after both registration and termination have occurred. This message is also sent when the watched actor is on a node that has been removed from the cluster when using akka-cluster or has been marked unreachable when using akka-remote directly.
Scala API: the ActorRef
for the terminated actor
Factories for DispatcherSelectors which describe which thread pool shall be used to run the actor to which this configuration is applied.
Factories for DispatcherSelectors which describe which thread pool shall be used to run the actor to which this configuration is applied. Se the individual factory methods for details on the options.
The default configuration if none of these options are present is to run the actor on the default ActorSystem executor.
Factories for log markers
Lifecycle signal that is fired after this actor and all its child actors (transitively) have terminated.
Lifecycle signal that is fired after this actor and all its child actors (transitively) have terminated. The Terminated signal is only sent to registered watchers after this signal has been processed.