pekko/supervisor/README

--- OVERVIEW ---
Scala Actors Behavior Module

Implements Erlang-style Behaviors for Scala; Supervisor, GenericServer, GenericEvent and GenericFiniteStateMachine allowing creating fault-tolerant actor-based enterprise systems.

The implementation consists of four main abstractions; 

* Supervisor -- The Supervisor manages hierarchies of Scala actors and provides fault-tolerance in terms of different restart 
semantics. The configuration and semantics is almost a 1-1 port of the Erlang Supervisor implementation, explained 
here: http://www.erlang.org/doc/design_principles/sup_princ.html, read this document in order to understand how to 
configure the Supervisor properly. 

* GenericServer -- The GenericServer (which subclasses Actor) is a trait that forms the base for a server to be managed by a Supervisor. 
The GenericServer is wrapped by a GenericServerContainer instance providing a necessary indirection needed to be able to 
fully manage the life-cycle of the GenericServer. 

* GenericEvent -- TBD

* GenericFiniteStateMachine -- TBD

--- CHECK OUT ---
The SCM system used is Git. 

1. Download and install Git (google git). 
2. Invoke 'git clone git://github.com/jboner/scala-otp.git'.

--- BUILD ---
The build system used is Maven.

1. Download and install Maven 2. 
2. Step into the root dir 'scala-otp'.
3. Invoke 'mvn install' 

This will build the project, run all tests, create a jar and upload it to your local Maven repository ready for use.

--- RUNTIME DEPENDENCIES ---
1. Scala 2.7.1-final
2. SLF4J 1.5.2
3. LogBack Classic 0.9.9

--- USAGE ---
Here is a small step-by-step runnable tutorial on how to create a server, configure it, use it, hotswap its 
implementation etc. For more details on the API, look at the code or the tests.

You can find this code in the sample.scala file in the root directory. Run it by invoking 'scala -cp 
target/scala-behavior-0.1-SNAPSHOT.jar:<path to slf4j and logback jars> sample.scala'

// =============================================
// 1. Import statements and Server messages

import scala.actors._
import scala.actors.Actor._

import scala.actors.behavior._
import scala.actors.behavior.Helpers._

sealed abstract class SampleMessage
case object Ping extends SampleMessage
case object Pong extends SampleMessage
case object OneWay extends SampleMessage
case object Die extends SampleMessage

// =============================================
// 2. Create the GenericServer by extending the GenericServer trait and override the 'body' method

class SampleServer extends GenericServer {

  // This method implements the core server logic and naturally has to be overridden
  override def body: PartialFunction[Any, Unit] = {
    case Ping => 
      println("Received Ping"); reply(Pong)

    case OneWay => 
      println("Received OneWay")

    case Die => 
      println("Received Die..dying...") 
      throw new RuntimeException("Received Die message")
  }

  // GenericServer also has some callback life-cycle methods, such as init(..) and shutdown(..) 
}

// =============================================
// 3. Wrap our SampleServer in  a GenericServerContainer and give it a name to be able to refer to it later.

object sampleServer1 extends GenericServerContainer("sample1", () => new SampleServer)
object sampleServer2 extends GenericServerContainer("sample2", () => new SampleServer)

// =============================================
// 4. Create a Supervisor configuration (and a SupervisorFactory) that is configuring our SampleServer (takes a list of 
'Worker' configurations, one or many)

object factory extends SupervisorFactory {
  override protected def getSupervisorConfig: SupervisorConfig = {
    SupervisorConfig(
      RestartStrategy(AllForOne, 3, 10000),
       Worker(
        sampleServer1,
        LifeCycle(Permanent, 1000)) ::
       Worker(
        sampleServer2,
        LifeCycle(Permanent, 1000)) ::
      Nil)
  }
}

// =============================================
// 5. Create a new Supervisor with the custom factory

val supervisor = factory.newSupervisor

// =============================================
// 6. Start the Supervisor (which starts the server(s))

supervisor ! Start

// =============================================
// 7. Try to send a one way asyncronous message to our servers

sampleServer1 ! OneWay

// Try to get sampleServer2 from the Supervisor before sending a message
supervisor.getServer("sample2") match {
  case Some(server2) => server2 ! OneWay
  case None => println("server [sample2] could not be found")
}

// =============================================
// 8. Try to send an asyncronous message - receive a future - wait 100 ms (time-out) for the reply

val future = sampleServer1 !! Ping
val reply1 = future.receiveWithin(100) match {
  case Some(reply) => 
    println("Received reply: " + reply)
  case None => 
    println("Did not get a reply witin 100 ms")
}

// =============================================
// 9. Try to send a message (Die) telling the server to kill itself (throw an exception)

sampleServer1 ! Die

// =============================================
// 10. Send an asyncronous message and wait on a future. If it times out -> use error handler (in this case throw an 
exception). It is likely that this call will time out since the server is in the middle of recovering from failure.

val reply2 = try {
  sampleServer1 !!! (Ping, throw new RuntimeException("Time-out"), 10) // time out is set to 10 ms (very low on purpose)
  
} catch { case e => println("Expected exception: " + e.toString); Pong } 

// =============================================
// 11. Server should be up again. Try the same call again

val reply3 = try {
  sampleServer1 !!! (Ping, throw new RuntimeException("Time-out"), 1000) 
} catch { case e => println("Expected exception: " + e.toString); Pong } 

// Also check server number 2
sampleServer2 ! Ping 

// =============================================
// 11. Try to hotswap the server implementation

sampleServer1.hotswap(Some({
  case Ping => 
    println("Hotswapped Ping")
}))

// =============================================
// 12. Try the hotswapped server out

sampleServer1 ! Ping

// =============================================
// 13. Hotswap again

sampleServer1.hotswap(Some({
  case Pong => 
    println("Hotswapped again, now doing Pong")
    reply(Ping)
}))

// =============================================
// 14. Send an asyncronous message that will wait on a future. Method returns an Option[T] => if Some(result) -> return 
result, if None -> print out an info message (or throw an exception or do whatever you like...)

val reply4 = (sampleServer1 !!! Pong).getOrElse({println("Time out when sending Pong"); Ping})

// Same invocation with pattern matching syntax.

val reply5 = sampleServer1 !!! Pong match {
  case Some(result) => result
  case None => println("Time out when sending Pong"); Ping  
}

// =============================================
// 15. Hotswap back to original implementation by passing in None

sampleServer1.hotswap(None)

// =============================================
// 16. Test the final hotswap by sending an async message

sampleServer1 !  Ping

// =============================================
// 17. Shut down the supervisor and its server(s)

supervisor ! Stop