Microkernel (Java)

Microkernel (Java)

The Akka Microkernel is included in the Akka download found at downloads.

To run an application with the microkernel you need to create a Bootable class that handles the startup and shutdown the application. An example is included below.

Put your application jar in the deploy directory to have it automatically loaded.

To start the kernel use the scripts in the bin directory, passing the boot classes for your application.

There is a simple example of an application setup for running with the microkernel included in the akka download. This can be run with the following command (on a unix-based system):

bin/akka sample.kernel.hello.HelloKernel

Use Ctrl-C to interrupt and exit the microkernel.

On a Windows machine you can also use the bin/akka.bat script.

The code for the Hello Kernel example (see the HelloKernel class for an example of creating a Bootable):

 *  Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
package sample.kernel.hello.java;

import akka.actor.ActorRef;
import akka.actor.UntypedActor;
import akka.actor.ActorSystem;
import akka.actor.Props;
import akka.kernel.Bootable;

public class HelloKernel implements Bootable {
  final ActorSystem system = ActorSystem.create("hellokernel");

  public static class HelloActor extends UntypedActor {
    final ActorRef worldActor = 
      getContext().actorOf(new Props(WorldActor.class));

  public void onReceive(Object message) {
    if (message == "start")
    else if (message instanceof String)
      System.out.println("Received message '%s'".format((String)message));
    else unhandled(message);

public static class WorldActor extends UntypedActor {
  public void onReceive(Object message) {
    if (message instanceof String)
      getSender().tell(((String)message).toUpperCase() + " world!");
    else unhandled(message);

  public void startup() {
    system.actorOf(new Props(HelloActor.class)).tell("start");

  public void shutdown() {

Distribution of microkernel application

To make a distribution package of the microkernel and your application the akka-sbt-plugin provides AkkaKernelPlugin. It creates the directory structure, with jar files, configuration files and start scripts.

To use the sbt plugin you define it in your project/plugins.sbt:

resolvers += "Typesafe Repo" at "http://repo.typesafe.com/typesafe/releases/"

addSbtPlugin("com.typesafe.akka" % "akka-sbt-plugin" % "2.0.5")

Then you add it to the settings of your project/Build.scala. It is also important that you add the akka-kernel dependency. This is an example of a complete sbt build file:

import sbt._
import Keys._
import akka.sbt.AkkaKernelPlugin
import akka.sbt.AkkaKernelPlugin.{ Dist, outputDirectory, distJvmOptions}

object HelloKernelBuild extends Build {
  val Organization = "akka.sample"
  val Version      = "2.0.5"
  val ScalaVersion = "2.9.2"

  lazy val HelloKernel = Project(
    id = "hello-kernel",
    base = file("."),
    settings = defaultSettings ++ AkkaKernelPlugin.distSettings ++ Seq(
      libraryDependencies ++= Dependencies.helloKernel,
      distJvmOptions in Dist := "-Xms256M -Xmx1024M",
      outputDirectory in Dist := file("target/hello-dist")

  lazy val buildSettings = Defaults.defaultSettings ++ Seq(
    organization := Organization,
    version      := Version,
    scalaVersion := ScalaVersion,
    crossPaths   := false,
    organizationName := "Typesafe Inc.",
    organizationHomepage := Some(url("http://www.typesafe.com"))
  lazy val defaultSettings = buildSettings ++ Seq(
    resolvers += "Typesafe Repo" at "http://repo.typesafe.com/typesafe/releases/",

    // compile options
    scalacOptions ++= Seq("-encoding", "UTF-8", "-deprecation", "-unchecked"),
    javacOptions  ++= Seq("-Xlint:unchecked", "-Xlint:deprecation")


object Dependencies {
  import Dependency._

  val helloKernel = Seq(
    akkaKernel, akkaSlf4j, logback

object Dependency {
  // Versions
  object V {
    val Akka      = "2.0.5"

  val akkaKernel        = "com.typesafe.akka" % "akka-kernel"        % V.Akka
  val akkaSlf4j         = "com.typesafe.akka" % "akka-slf4j"         % V.Akka
  val logback           = "ch.qos.logback"    % "logback-classic"    % "1.0.0"

Run the plugin with sbt:

> dist
> dist:clean

There are several settings that can be defined:

  • outputDirectory - destination directory of the package, default target/dist
  • distJvmOptions - JVM parameters to be used in the start script
  • configSourceDirs - Configuration files are copied from these directories, default src/config, src/main/config, src/main/resources
  • distMainClass - Kernel main class to use in start script
  • libFilter - Filter of dependency jar files
  • additionalLibs - Additional dependency jar files