Package akka.actor

Class ActorSystem

  • All Implemented Interfaces:
    ActorRefFactory, ClassicActorSystemProvider
    Direct Known Subclasses:
    ExtendedActorSystem
    public abstract class ActorSystem
extends java.lang.Object
implements ActorRefFactory, ClassicActorSystemProvider
    An actor system is a hierarchical group of actors which share common configuration, e.g. dispatchers, deployments, remote capabilities and addresses. It is also the entry point for creating or looking up actors.

    There are several possibilities for creating actors (see Props for details on props): 

    
 // Java or Scala
 system.actorOf(props, "name")
 system.actorOf(props)

 // Scala
 system.actorOf(Props[MyActor], "name")
 system.actorOf(Props(classOf[MyActor], arg1, arg2), "name")

 // Java
 system.actorOf(Props.create(MyActor.class), "name");
 system.actorOf(Props.create(MyActor.class, arg1, arg2), "name");

    Where no name is given explicitly, one will be automatically generated.

    Important Notice:

    This class is not meant to be extended by user code. If you want to actually roll your own Akka, it will probably be better to look into extending ExtendedActorSystem instead, but beware that you are completely on your own in that case!

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ActorSystem.Settings
      Settings are the overall ActorSystem Settings which also provides a convenient access to the Config object.
      static class  ActorSystem.Settings$
      INTERNAL API

    • Constructor Summary

      Constructors 
      Constructor Description
      ActorSystem()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract ActorPath $div​(java.lang.String name)
      Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).
      abstract ActorPath $div​(scala.collection.Iterable<java.lang.String> name)
      Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).
      static ActorSystem apply()
      Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem apply​(java.lang.String name)
      Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem apply​(java.lang.String name, BootstrapSetup bootstrapSetup)
      Scala API: Shortcut for creating an actor system with custom bootstrap settings.
      static ActorSystem apply​(java.lang.String name, ActorSystemSetup setup)
      Scala API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup
      static ActorSystem apply​(java.lang.String name, com.typesafe.config.Config config)
      Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem apply​(java.lang.String name, com.typesafe.config.Config config, java.lang.ClassLoader classLoader)
      Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader
      static ActorSystem apply​(java.lang.String name, scala.Option<com.typesafe.config.Config> config, scala.Option<java.lang.ClassLoader> classLoader, scala.Option<scala.concurrent.ExecutionContext> defaultExecutionContext)
      Creates a new ActorSystem with the specified name, the specified ClassLoader if given, otherwise obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static scala.Option<com.typesafe.config.Config> apply$default$2()  
      static scala.Option<java.lang.ClassLoader> apply$default$3()  
      static scala.Option<scala.concurrent.ExecutionContext> apply$default$4()  
      ActorPath child​(java.lang.String child)
      Java API: Create a new child actor path.
      static ActorSystem create()
      Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem create​(java.lang.String name)
      Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem create​(java.lang.String name, BootstrapSetup bootstrapSetup)
      Java API: Shortcut for creating an actor system with custom bootstrap settings.
      static ActorSystem create​(java.lang.String name, ActorSystemSetup setups)
      Java API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup
      static ActorSystem create​(java.lang.String name, com.typesafe.config.Config config)
      Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
      static ActorSystem create​(java.lang.String name, com.typesafe.config.Config config, java.lang.ClassLoader classLoader)
      Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader
      static ActorSystem create​(java.lang.String name, com.typesafe.config.Config config, java.lang.ClassLoader classLoader, scala.concurrent.ExecutionContext defaultExecutionContext)
      Creates a new ActorSystem with the specified name, the specified Config, the specified ClassLoader, and the specified ExecutionContext.
      abstract ActorRef deadLetters()
      Actor reference where messages are re-routed to which were addressed to stopped or non-existing actors.
      ActorPath descendant​(java.lang.Iterable<java.lang.String> names)
      Java API: Recursively create a descendant&rsquo;s path by appending all child names.
      abstract scala.concurrent.ExecutionContextExecutor dispatcher()
      Default dispatcher as configured.
      abstract Dispatchers dispatchers()
      Helper object for looking up configured dispatchers.
      abstract EventStream eventStream()
      Main event bus of this actor system, used for example for logging.
      abstract <T extends Extension>
      T      		 extension​(ExtensionId<T> ext)
      Returns the payload that is associated with the provided extension throws an IllegalStateException if it is not registered.
      scala.concurrent.ExecutionContextExecutor getDispatcher()
      Java API: Default dispatcher as configured.
      EventStream getEventStream()
      Java API: Main event bus of this actor system, used for example for logging.
      abstract java.util.Optional<java.time.LocalDate> getLicenseKeyExpiry()
      Java API: When the license key will expire.
      Scheduler getScheduler()
      Java API: Light-weight scheduler for running asynchronous tasks after some deadline in the future.
      abstract java.util.concurrent.CompletionStage<Terminated> getWhenTerminated()
      Returns a CompletionStage which will be completed after the ActorSystem has been terminated and termination hooks have been executed.
      abstract boolean hasExtension​(ExtensionId<? extends Extension> ext)
      Returns whether the specified extension is already registered, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution
      abstract scala.Option<java.time.LocalDate> licenseKeyExpiry()
      Scala API: When the license key will expire.
      abstract LoggingAdapter log()
      Convenient logging adapter for logging to the eventStream().
      abstract void logConfiguration()
      Log the configuration.
      abstract akka.dispatch.Mailboxes mailboxes()
      Helper object for looking up configured mailbox types.
      abstract java.lang.String name()
      The name of this actor system, used to distinguish multiple ones within the same JVM & class loader.
      abstract <T extends Extension>
      T      		 registerExtension​(ExtensionId<T> ext)
      Registers the provided extension and creates its payload, if this extension isn't already registered This method has putIfAbsent-semantics, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution
      abstract void registerOnTermination​(java.lang.Runnable code)
      Java API: Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped.
      abstract <T> void registerOnTermination​(scala.Function0<T> code)
      Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped.
      abstract Scheduler scheduler()
      Light-weight scheduler for running asynchronous tasks after some deadline in the future.
      abstract ActorSystem.Settings settings()
      The core settings extracted from the supplied configuration.
      long startTime()
      Start-up time in milliseconds since the epoch.
      abstract scala.concurrent.Future<Terminated> terminate()
      Terminates this actor system by running CoordinatedShutdown with reason CoordinatedShutdown.ActorSystemTerminateReason.
      long uptime()
      Up-time of this actor system in seconds.
      static java.lang.String Version()  
      abstract scala.concurrent.Future<Terminated> whenTerminated()
      Returns a Future which will be completed after the ActorSystem has been terminated and termination hooks have been executed.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • ActorSystem

        public ActorSystem()

    • Method Detail

      • Version

        public static java.lang.String Version()

      • create

        public static ActorSystem create()
        Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

      • create

        public static ActorSystem create​(java.lang.String name)
        Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

      • create

        public static ActorSystem create​(java.lang.String name,
                                 ActorSystemSetup setups)
        Java API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

      • create

        public static ActorSystem create​(java.lang.String name,
                                 BootstrapSetup bootstrapSetup)
        Java API: Shortcut for creating an actor system with custom bootstrap settings. Same behavior as calling ActorSystem.create(name, ActorSystemSetup.create(bootstrapSettings))

      • create

        public static ActorSystem create​(java.lang.String name,
                                 com.typesafe.config.Config config)
        Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.

        See Also:
        The Typesafe Config Library API Documentation

      • create

        public static ActorSystem create​(java.lang.String name,
                                 com.typesafe.config.Config config,
                                 java.lang.ClassLoader classLoader)
        Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader

        See Also:
        The Typesafe Config Library API Documentation

      • create

        public static ActorSystem create​(java.lang.String name,
                                 com.typesafe.config.Config config,
                                 java.lang.ClassLoader classLoader,
                                 scala.concurrent.ExecutionContext defaultExecutionContext)
        Creates a new ActorSystem with the specified name, the specified Config, the specified ClassLoader, and the specified ExecutionContext. The ExecutionContext will be used as the default executor inside this ActorSystem. If null is passed in for the Config, ClassLoader and/or ExecutionContext parameters, the respective default value will be used. If no Config is given, the default reference config will be obtained from the ClassLoader. If no ClassLoader is given, it obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. If no ExecutionContext is given, the system will fallback to the executor configured under "akka.actor.default-dispatcher.default-executor.fallback". Note that the given ExecutionContext will be used by all dispatchers that have been configured with executor = "default-executor", including those that have not defined the executor setting and thereby fallback to the default of "default-dispatcher.executor".

        See Also:
        The Typesafe Config Library API Documentation

      • apply

        public static ActorSystem apply()
        Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

      • apply

        public static ActorSystem apply​(java.lang.String name)
        Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

      • apply

        public static ActorSystem apply​(java.lang.String name,
                                ActorSystemSetup setup)
        Scala API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

      • apply

        public static ActorSystem apply​(java.lang.String name,
                                BootstrapSetup bootstrapSetup)
        Scala API: Shortcut for creating an actor system with custom bootstrap settings. Same behavior as calling ActorSystem(name, ActorSystemSetup(bootstrapSetup))

      • apply

        public static ActorSystem apply​(java.lang.String name,
                                com.typesafe.config.Config config)
        Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.

        See Also:
        The Typesafe Config Library API Documentation

      • apply

        public static ActorSystem apply​(java.lang.String name,
                                com.typesafe.config.Config config,
                                java.lang.ClassLoader classLoader)
        Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader

        See Also:
        The Typesafe Config Library API Documentation

      • apply

        public static ActorSystem apply​(java.lang.String name,
                                scala.Option<com.typesafe.config.Config> config,
                                scala.Option<java.lang.ClassLoader> classLoader,
                                scala.Option<scala.concurrent.ExecutionContext> defaultExecutionContext)
        Creates a new ActorSystem with the specified name, the specified ClassLoader if given, otherwise obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. If an ExecutionContext is given, it will be used as the default executor inside this ActorSystem. If no ExecutionContext is given, the system will fallback to the executor configured under "akka.actor.default-dispatcher.default-executor.fallback". The system will use the passed in config, or falls back to the default reference configuration using the ClassLoader.

        See Also:
        The Typesafe Config Library API Documentation

      • apply$default$2

        public static scala.Option<com.typesafe.config.Config> apply$default$2()

      • apply$default$3

        public static scala.Option<java.lang.ClassLoader> apply$default$3()

      • apply$default$4

        public static scala.Option<scala.concurrent.ExecutionContext> apply$default$4()

      • name

        public abstract java.lang.String name()
        The name of this actor system, used to distinguish multiple ones within the same JVM & class loader.

      • settings

        public abstract ActorSystem.Settings settings()
        The core settings extracted from the supplied configuration.

      • logConfiguration

        public abstract void logConfiguration()
        Log the configuration.

      • child

        public ActorPath child​(java.lang.String child)
        Java API: Create a new child actor path.

      • descendant

        public ActorPath descendant​(java.lang.Iterable<java.lang.String> names)
        Java API: Recursively create a descendant&rsquo;s path by appending all child names.

      • startTime

        public long startTime()
        Start-up time in milliseconds since the epoch.

      • uptime

        public long uptime()
        Up-time of this actor system in seconds.

      • eventStream

        public abstract EventStream eventStream()
        Main event bus of this actor system, used for example for logging.

      • getEventStream

        public EventStream getEventStream()
        Java API: Main event bus of this actor system, used for example for logging.

      • deadLetters

        public abstract ActorRef deadLetters()
        Actor reference where messages are re-routed to which were addressed to stopped or non-existing actors. Delivery to this actor is done on a best effort basis and hence not strictly guaranteed.

      • scheduler

        public abstract Scheduler scheduler()
        Light-weight scheduler for running asynchronous tasks after some deadline in the future. Not terribly precise but cheap.

      • getScheduler

        public Scheduler getScheduler()
        Java API: Light-weight scheduler for running asynchronous tasks after some deadline in the future. Not terribly precise but cheap.

      • dispatchers

        public abstract Dispatchers dispatchers()
        Helper object for looking up configured dispatchers.

      • dispatcher

        public abstract scala.concurrent.ExecutionContextExecutor dispatcher()
        Default dispatcher as configured. This dispatcher is used for all actors in the actor system which do not have a different dispatcher configured explicitly. Importing this member will place the default MessageDispatcher in scope.
        Specified by:
        dispatcher in interface ActorRefFactory

      • getDispatcher

        public scala.concurrent.ExecutionContextExecutor getDispatcher()
        Java API: Default dispatcher as configured. This dispatcher is used for all actors in the actor system which do not have a different dispatcher configured explicitly. Importing this member will place the default MessageDispatcher in scope.

      • mailboxes

        public abstract akka.dispatch.Mailboxes mailboxes()
        Helper object for looking up configured mailbox types.

      • registerOnTermination

        public abstract <T> void registerOnTermination​(scala.Function0<T> code)
        Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped. Multiple code blocks may be registered by calling this method multiple times. The callbacks will be run sequentially in reverse order of registration, i.e. last registration is run first. Note that ActorSystem will not terminate until all the registered callbacks are finished.

        Throws a RejectedExecutionException if the System has already been terminated or if termination has been initiated.

        Scala API

      • registerOnTermination

        public abstract void registerOnTermination​(java.lang.Runnable code)
        Java API: Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped. Multiple code blocks may be registered by calling this method multiple times. The callbacks will be run sequentially in reverse order of registration, i.e. last registration is run first. Note that ActorSystem will not terminate until all the registered callbacks are finished.

        Throws a RejectedExecutionException if the System has already been terminated or if termination has been initiated.

      • terminate

        public abstract scala.concurrent.Future<Terminated> terminate()
        Terminates this actor system by running CoordinatedShutdown with reason CoordinatedShutdown.ActorSystemTerminateReason.

        If akka.coordinated-shutdown.run-by-actor-system-terminate is configured to off it will not run CoordinatedShutdown, but the ActorSystem and its actors will still be terminated.

        This will stop the guardian actor, which in turn will recursively stop all its child actors, and finally the system guardian (below which the logging actors reside) and then execute all registered termination handlers (see registerOnTermination(scala.Function0<T>)). Be careful to not schedule any operations on completion of the returned future using the dispatcher of this actor system as it will have been shut down before the future completes.

      • whenTerminated

        public abstract scala.concurrent.Future<Terminated> whenTerminated()
        Returns a Future which will be completed after the ActorSystem has been terminated and termination hooks have been executed. If you registered any callback with registerOnTermination(scala.Function0<T>), the returned Future from this method will not complete until all the registered callbacks are finished. Be careful to not schedule any operations, such as onComplete, on the dispatchers (ExecutionContext) of this actor system as they will have been shut down before this future completes.

      • getWhenTerminated

        public abstract java.util.concurrent.CompletionStage<Terminated> getWhenTerminated()
        Returns a CompletionStage which will be completed after the ActorSystem has been terminated and termination hooks have been executed. If you registered any callback with registerOnTermination(scala.Function0<T>), the returned CompletionStage from this method will not complete until all the registered callbacks are finished. Be careful to not schedule any operations, such as thenRunAsync, on the dispatchers (Executor) of this actor system as they will have been shut down before this CompletionStage completes.

      • registerExtension

        public abstract <T extends Extension> T registerExtension​(ExtensionId<T> ext)
        Registers the provided extension and creates its payload, if this extension isn't already registered This method has putIfAbsent-semantics, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution

      • extension

        public abstract <T extends Extension> T extension​(ExtensionId<T> ext)
        Returns the payload that is associated with the provided extension throws an IllegalStateException if it is not registered. This method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution

      • hasExtension

        public abstract boolean hasExtension​(ExtensionId<? extends Extension> ext)
        Returns whether the specified extension is already registered, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution

      • licenseKeyExpiry

        public abstract scala.Option<java.time.LocalDate> licenseKeyExpiry()
        Scala API: When the license key will expire. None for perpetual keys. If a license key is not defined the expiry date will be today's date.

      • getLicenseKeyExpiry

        public abstract java.util.Optional<java.time.LocalDate> getLicenseKeyExpiry()
        Java API: When the license key will expire. Optional.empty for perpetual keys. If a license key is not defined the expiry date will be today's date.