akka.actor
Class ActorSystem

java.lang.Object
  extended by akka.actor.ActorSystem
All Implemented Interfaces:
ActorRefFactory
Direct Known Subclasses:
ExtendedActorSystem

public abstract class ActorSystem
extends java.lang.Object
implements ActorRefFactory

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
static class ActorSystem.Settings
          Settings are the overall ActorSystem Settings which also provides a convenient access to the Config object.
 
Constructor Summary
ActorSystem()
           
 
Method Summary
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, 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.
abstract  void awaitTermination()
          Block current thread until the system has been shutdown.
abstract  void awaitTermination(scala.concurrent.duration.Duration timeout)
          Block current thread until the system has been shutdown, or the specified timeout has elapsed.
 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, 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.
static scala.Option<java.lang.String> EnvHome()
           
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.
static java.lang.ClassLoader findClassLoader()
          INTERNAL API
static scala.Option<java.lang.String> GlobalHome()
           
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  boolean isTerminated()
          Query the termination status: if it returns true, all callbacks have run and the ActorSystem has been fully stopped, i.e.
abstract  LoggingAdapter log()
          Convenient logging adapter for logging to the ActorSystem.eventStream.
abstract  void logConfiguration()
          Log the configuration.
abstract  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
<T> void
registerOnTermination(scala.Function0<T> code)
          Register a block of code (callback) to run after ActorSystem.shutdown has been issued and all actors in this actor system have been stopped.
abstract  void registerOnTermination(java.lang.Runnable code)
          Java API: Register a block of code (callback) to run after ActorSystem.shutdown 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.
abstract  void shutdown()
          Stop this actor system.
 long startTime()
          Start-up time in milliseconds since the epoch.
static scala.Option<java.lang.String> SystemHome()
           
 long uptime()
          Up-time of this actor system in seconds.
static java.lang.String Version()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface akka.actor.ActorRefFactory
actorFor, actorFor, actorFor, actorFor, actorOf, actorOf, actorSelection, actorSelection, guardian, lookupRoot, provider, stop, systemImpl
 

Constructor Detail

ActorSystem

public ActorSystem()
Method Detail

Version

public static java.lang.String Version()

EnvHome

public static scala.Option<java.lang.String> EnvHome()

SystemHome

public static scala.Option<java.lang.String> SystemHome()

GlobalHome

public static scala.Option<java.lang.String> GlobalHome()

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.

Returns:
(undocumented)

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.

Parameters:
name - (undocumented)
Returns:
(undocumented)

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.

Parameters:
name - (undocumented)
config - (undocumented)
Returns:
(undocumented)
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

Parameters:
name - (undocumented)
config - (undocumented)
classLoader - (undocumented)
Returns:
(undocumented)
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".

Parameters:
name - (undocumented)
config - (undocumented)
classLoader - (undocumented)
defaultExecutionContext - (undocumented)
Returns:
(undocumented)
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.

Returns:
(undocumented)

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.

Parameters:
name - (undocumented)
Returns:
(undocumented)

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.

Parameters:
name - (undocumented)
config - (undocumented)
Returns:
(undocumented)
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

Parameters:
name - (undocumented)
config - (undocumented)
classLoader - (undocumented)
Returns:
(undocumented)
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 deafult reference configuration using the ClassLoader.

Parameters:
name - (undocumented)
config - (undocumented)
classLoader - (undocumented)
defaultExecutionContext - (undocumented)
Returns:
(undocumented)
See Also:
The Typesafe Config Library API Documentation

findClassLoader

public static java.lang.ClassLoader findClassLoader()
INTERNAL API

Returns:
(undocumented)

name

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

Returns:
(undocumented)

settings

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

Returns:
(undocumented)

logConfiguration

public abstract void logConfiguration()
Log the configuration.


child

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

Parameters:
child - (undocumented)
Returns:
(undocumented)

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.

Parameters:
names - (undocumented)
Returns:
(undocumented)

startTime

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

Returns:
(undocumented)

uptime

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

Returns:
(undocumented)

eventStream

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

Returns:
(undocumented)

log

public abstract LoggingAdapter log()
Convenient logging adapter for logging to the ActorSystem.eventStream.

Returns:
(undocumented)

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.

Returns:
(undocumented)

scheduler

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

Returns:
(undocumented)

dispatchers

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

Returns:
(undocumented)

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
Returns:
(undocumented)

mailboxes

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

Returns:
(undocumented)

registerOnTermination

public abstract <T> void registerOnTermination(scala.Function0<T> code)
Register a block of code (callback) to run after ActorSystem.shutdown 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.

Parameters:
code - (undocumented)
Throws:
a - RejectedExecutionException if the System has already shut down or if shutdown 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.shutdown 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.

Parameters:
code - (undocumented)
Throws:
a - RejectedExecutionException if the System has already shut down or if shutdown has been initiated.

awaitTermination

public abstract void awaitTermination(scala.concurrent.duration.Duration timeout)
Block current thread until the system has been shutdown, or the specified timeout has elapsed. This will block until after all on termination callbacks have been run.

Parameters:
timeout - (undocumented)
Throws:
TimeoutException - in case of timeout

awaitTermination

public abstract void awaitTermination()
Block current thread until the system has been shutdown. This will block until after all on termination callbacks have been run.


shutdown

public abstract void shutdown()
Stop this actor system. This will stop the guardian actor, which in turn will recursively stop all its child actors, then the system guardian (below which the logging actors reside) and the execute all registered termination handlers (see ActorSystem.registerOnTermination).


isTerminated

public abstract boolean isTerminated()
Query the termination status: if it returns true, all callbacks have run and the ActorSystem has been fully stopped, i.e. awaitTermination(0 seconds) would return normally. If this method returns false, the status is actually unknown, since it might have changed since you queried it.

Returns:
(undocumented)

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

Parameters:
ext - (undocumented)
Returns:
(undocumented)

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

Parameters:
ext - (undocumented)
Returns:
(undocumented)

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

Parameters:
ext - (undocumented)
Returns:
(undocumented)