Updated microkernel

- no config files used by microkernel
- boot classes are specified as main arguments
- actor system creation is left to user in Bootable
- added on-out-of-memory handler to java args
- updated docs

akka-kernel/src/main/scala/akka/kernel/Main.scala

@@ -5,92 +5,134 @@
 package akka.kernel
 
 import akka.actor.ActorSystem
-import com.typesafe.config.ConfigFactory
 import java.io.File
 import java.lang.Boolean.getBoolean
 import java.net.{ URL, URLClassLoader }
 import java.util.jar.JarFile
 import scala.collection.JavaConverters._
 
+/**
+ * To use the microkernel at least one 'boot class' needs to be specified.
+ * A boot class implements this interface ([[akka.kernel.Bootable]]) and
+ * must have an empty default constructor.
+ *
+ * ActorSystems can be created within the boot class.
+ *
+ * An example of a simple boot class:
+ * {{{
+ * class BootApp extends Bootable {
+ *   val system = ActorSystem("app")
+ *
+ *   def startup = {
+ *     system.actorOf(Props[FirstActor]) ! FirstMessage
+ *   }
+ *
+ *   def shutdown = {
+ *     system.shutdown()
+ *   }
+ * }
+ * }}}
+ *
+ * Boot classes are specified as main arguments to the microkernel.
+ *
+ * For example, using the akka script an application can be started with
+ * the following at the command line:
+ * {{{
+ * bin/akka org.app.BootApp
+ * }}}
+ */
 trait Bootable {
-  def startup(system: ActorSystem): Unit
-  def shutdown(system: ActorSystem): Unit
+  /**
+   * Callback run on microkernel startup.
+   * Create initial actors and messages here.
+   */
+  def startup(): Unit
+
+  /**
+   * Callback run on microkernel shutdown.
+   * Shutdown actor systems here.
+   */
+  def shutdown(): Unit
 }
 
+/**
+ * Main class for running the microkernel.
+ */
 object Main {
   val quiet = getBoolean("akka.kernel.quiet")
 
   def log(s: String) = if (!quiet) println(s)
 
   def main(args: Array[String]) = {
+    if (args.isEmpty) {
+      log("[error] No boot classes specified")
+      System.exit(1)
+    }
+
     log(banner)
     log("Starting Akka...")
     log("Running Akka " + ActorSystem.Version)
 
-    val config = ConfigFactory.load("akka.conf")
-    val name = config.getString("akka.kernel.system.name")
-    val system = ActorSystem(name, config)
-    val classLoader = deployJars(system)
-
-    log("Created actor system '%s'" format name)
+    val classLoader = createClassLoader()
 
     Thread.currentThread.setContextClassLoader(classLoader)
 
-    val bootClasses: Seq[String] = system.settings.config.getStringList("akka.kernel.boot").asScala
+    val bootClasses: Seq[String] = args.toSeq
     val bootables: Seq[Bootable] = bootClasses map { c ⇒ classLoader.loadClass(c).newInstance.asInstanceOf[Bootable] }
 
     for (bootable ← bootables) {
       log("Starting up " + bootable.getClass.getName)
-      bootable.startup(system)
+      bootable.startup()
     }
 
-    addShutdownHook(system, bootables)
+    addShutdownHook(bootables)
 
     log("Successfully started Akka")
   }
 
-  def deployJars(system: ActorSystem): ClassLoader = {
-    if (system.settings.Home.isEmpty) {
-      log("Akka home is not defined")
-      System.exit(1)
-      Thread.currentThread.getContextClassLoader
-    } else {
-      val home = system.settings.Home.get
+  def createClassLoader(): ClassLoader = {
+    if (ActorSystem.GlobalHome.isDefined) {
+      val home = ActorSystem.GlobalHome.get
       val deploy = new File(home, "deploy")
-
-      if (!deploy.exists) {
-        log("No deploy dir found at " + deploy)
-        log("Please check that akka home is defined correctly")
-        System.exit(1)
+      if (deploy.exists) {
+        loadDeployJars(deploy)
+      } else {
+        log("[warning] No deploy dir found at " + deploy)
+        Thread.currentThread.getContextClassLoader
       }
-
-      val jars = deploy.listFiles.filter(_.getName.endsWith(".jar"))
-
-      val nestedJars = jars flatMap { jar ⇒
-        val jarFile = new JarFile(jar)
-        val jarEntries = jarFile.entries.asScala.toArray.filter(_.getName.endsWith(".jar"))
-        jarEntries map { entry ⇒ new File("jar:file:%s!/%s" format (jarFile.getName, entry.getName)) }
-      }
-
-      val urls = (jars ++ nestedJars) map { _.toURI.toURL }
-
-      urls foreach { url ⇒ log("Deploying " + url) }
-
-      new URLClassLoader(urls, Thread.currentThread.getContextClassLoader)
+    } else {
+      log("[warning] Akka home is not defined")
+      Thread.currentThread.getContextClassLoader
     }
   }
 
-  def addShutdownHook(system: ActorSystem, bootables: Seq[Bootable]): Unit = {
+  def loadDeployJars(deploy: File): ClassLoader = {
+    val jars = deploy.listFiles.filter(_.getName.endsWith(".jar"))
+
+    val nestedJars = jars flatMap { jar ⇒
+      val jarFile = new JarFile(jar)
+      val jarEntries = jarFile.entries.asScala.toArray.filter(_.getName.endsWith(".jar"))
+      jarEntries map { entry ⇒ new File("jar:file:%s!/%s" format (jarFile.getName, entry.getName)) }
+    }
+
+    val urls = (jars ++ nestedJars) map { _.toURI.toURL }
+
+    urls foreach { url ⇒ log("Deploying " + url) }
+
+    new URLClassLoader(urls, Thread.currentThread.getContextClassLoader)
+  }
+
+  def addShutdownHook(bootables: Seq[Bootable]): Unit = {
     Runtime.getRuntime.addShutdownHook(new Thread(new Runnable {
       def run = {
         log("")
-        log("Received signal to stop")
         log("Shutting down Akka...")
+
         for (bootable ← bootables) {
           log("Shutting down " + bootable.getClass.getName)
-          bootable.shutdown(system)
+          bootable.shutdown()
         }
-        system.stop()
+
         log("Successfully shut down Akka")
       }
     }))