akka.actor

Class ActorSystem

java.lang.Object

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

Nested Classes

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

Constructor Summary

Constructors

Constructor and Description
ActorSystem()

Method Summary

Modifier and Type	Method and Description
static ActorRef	actorFor(ActorPath path)
static ActorRef	actorFor(scala.collection.Iterable<java.lang.String> path)
static ActorRef	actorFor(java.lang.Iterable<java.lang.String> path)
static ActorRef	actorFor(java.lang.String path)
abstract static ActorRef	actorOf(Props props)
abstract static ActorRef	actorOf(Props props, java.lang.String name)
static ActorSelection	actorSelection(ActorPath path)
static ActorSelection	actorSelection(java.lang.String path)
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, 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, BootstrapSetup bootstrapSetup) Scala API: Shortcut for creating an actor system with custom bootstrap settings.
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() Deprecated. Use Await.result(whenTerminated, Duration.Inf) instead. Since 2.4.
abstract void	awaitTermination(scala.concurrent.duration.Duration timeout) Deprecated. Use Await.result(whenTerminated, timeout) instead. Since 2.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, 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, BootstrapSetup bootstrapSetup) Java API: Shortcut for creating an actor system with custom bootstrap settings.
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()
static scala.Option<java.lang.String>	GlobalHome()
protected abstract static InternalActorRef	guardian()
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() Deprecated. Use the whenTerminated method instead. Since 2.4.
abstract LoggingAdapter	log() Convenient logging adapter for logging to the eventStream().
abstract void	logConfiguration() Log the configuration.
protected abstract static InternalActorRef	lookupRoot()
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.
protected abstract static ActorRefProvider	provider()
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() Deprecated. Use the terminate() method instead. Since 2.4.
long	startTime() Start-up time in milliseconds since the epoch.
abstract static void	stop(ActorRef actor)
static scala.Option<java.lang.String>	SystemHome()
protected abstract static ActorSystemImpl	systemImpl()
abstract scala.concurrent.Future<Terminated>	terminate() Terminates this actor system.
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

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,
                                 ActorSystemSetup setups)

Java API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

Parameters:

name - (undocumented)

setups - (undocumented)

Returns:

(undocumented)

create

public static ActorSystem create(java.lang.String name,
                                 BootstrapSetup bootstrapSetup)

Java API: Shortcut for creating an actor system with custom bootstrap settings. Same behaviour as calling ActorSystem.create(name, ActorSystemSetup.create(bootstrapSettings))

Parameters:

name - (undocumented)

bootstrapSetup - (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,
                                ActorSystemSetup setup)

Scala API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

Parameters:

name - (undocumented)

setup - (undocumented)

Returns:

(undocumented)

apply

public static ActorSystem apply(java.lang.String name,
                                BootstrapSetup bootstrapSetup)

Scala API: Shortcut for creating an actor system with custom bootstrap settings. Same behaviour as calling ActorSystem(name, ActorSystemSetup(bootstrapSetup))

Parameters:

name - (undocumented)

bootstrapSetup - (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 default 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()

systemImpl

protected abstract static ActorSystemImpl systemImpl()

provider

protected abstract static ActorRefProvider provider()

guardian

protected abstract static InternalActorRef guardian()

lookupRoot

protected abstract static InternalActorRef lookupRoot()

actorOf

public abstract static ActorRef actorOf(Props props)

actorOf

public abstract static ActorRef actorOf(Props props,
                                        java.lang.String name)

actorFor

public static ActorRef actorFor(ActorPath path)

actorFor

public static ActorRef actorFor(java.lang.String path)

actorFor

public static ActorRef actorFor(scala.collection.Iterable<java.lang.String> path)

actorFor

public static ActorRef actorFor(java.lang.Iterable<java.lang.String> path)

actorSelection

public static ActorSelection actorSelection(java.lang.String path)

actorSelection

public static ActorSelection actorSelection(ActorPath path)

stop

public abstract static void stop(ActorRef actor)

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’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 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.

Throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.

Scala API

Parameters:

code - (undocumented)

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.

Throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.

Parameters:

code - (undocumented)

awaitTermination

public abstract void awaitTermination(scala.concurrent.duration.Duration timeout)

Deprecated. Use Await.result(whenTerminated, timeout) instead. Since 2.4.

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.

Throws TimeoutException in case of timeout.

Parameters:

timeout - (undocumented)

awaitTermination

public abstract void awaitTermination()

Deprecated. Use Await.result(whenTerminated, Duration.Inf) instead. Since 2.4.

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()

Deprecated. Use the terminate() method instead. Since 2.4.

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 registerOnTermination(scala.Function0<T>)).

isTerminated

public abstract boolean isTerminated()

Deprecated. Use the whenTerminated method instead. Since 2.4.

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)

terminate

public abstract scala.concurrent.Future<Terminated> terminate()

Terminates 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 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.

Returns:

(undocumented)

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. Be careful to not schedule any operations on the dispatcher of this actor system as it will have been shut down before this future completes.

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)