Provide Untyped escape for typed actors

Author: knutwalker

core/src/main/scala/de/knutwalker/akka/typed/TypedActor.scala

@@ -18,23 +18,19 @@ package de.knutwalker.akka.typed
 
 import _root_.akka.actor.Actor
 import _root_.akka.event.LoggingReceive
-import de.knutwalker.akka.typed.TypedActor.TypedReceiver
+import akka.actor.Actor.Receive
+import de.knutwalker.akka.typed.TypedActor.{ Downcast, TypedReceiver }
+
+import scala.reflect.ClassTag
 
 /**
  * TypedActor base trait that should be extended by to create a typed Actor.
  * This actor is designed to only receive one type of message in its lifetime.
  * Typically, this is some ADT/sealed trait that defines the protocol for this actor.
  *
- * The message type is defined by the abstract type member `Message`.
- * The object [[TypedActor$]] defines a helper trait to provide the message type
- * via a type paramter instead of a type member. These two are equivalent:
+ * The message type is defined by extending [[TypedActor.Of]]:
  *
  * {{{
- *   class ExampleActor extends TypeActor {
- *     type Message = ExampleProtocol
- *     // ...
- *   }
- *
  *   class ExampleActor extends TypeActor.Of[ExampleProtocol] {
  *     // ...
  *   }
@@ -59,11 +55,14 @@ import de.knutwalker.akka.typed.TypedActor.TypedReceiver
  *   }
  * }}}
  *
+ * If you must go back to untyped land, use the [[TypedActor#Untyped]] wrapper.
+ *
  * @see [[akka.actor.Actor]] for more about Actors in general.
  */
-trait TypedActor extends Actor {
+sealed trait TypedActor extends Actor {
   type Message
   type TypedReceive = PartialFunction[Message, Unit]
+  implicit def _ct: ClassTag[Message]
 
   /** Typed variant of [[self]]. */
   final val typedSelf: ActorRef[Message] =
@@ -79,16 +78,30 @@ trait TypedActor extends Actor {
    *
    * {{{
    *   // error: match may not be exhaustive. It would fail on the following inputs: None
-   *   class ExampleActor extends TypedActor {
-   *     type Message = Option[String]
+   *   class ExampleActor extends TypedActor.Of[Option[String]] {
    *     def typedReceive: TypedReceive = Total {
    *       case Some("foo") ⇒
    *     }
    *   }
    * }}}
    */
   final def Total(f: Message ⇒ Unit): TypedReceive =
-    PartialFunction(f)
+    new Downcast[Message](_ct.runtimeClass.asInstanceOf[Class[Message]])(f)
+
+  /**
+   * Wraps an untyped receiver and returns it as a [[TypedReceive]].
+   * Use this to match for messages that are outside of your protocol, e.g. [[akka.actor.Terminated]].
+   *
+   * {{{
+   *   class ExampleActor extends TypedActor.Of[ExampleMessage] {
+   *     def typedReceive: TypedReceive = Untyped {
+   *       case Terminated(ref) => println(s"$$ref terminated")
+   *     }
+   *   }
+   * }}}
+   */
+  final def Untyped(f: Receive): TypedReceive =
+    f // .asInstanceOf[TypedReceive]
 
   /**
    * `TypedActor`s delegate to [[typedReceive]].
@@ -116,31 +129,38 @@ trait TypedActor extends Actor {
 }
 object TypedActor {
   /**
-   * A convenience trait to provide the message type via type parameters.
-   *
-   * * {{{
-   *   class ExampleActor extends TypeActor {
-   *     type Message = ExampleProtocol
-   *     // ...
-   *   }
+   * Abstract class to extend from in order to get a [[TypedActor]].
+   * If you want to have the message type provided as a type parameter,
+   * you have to add a context bound for [[scala.reflect.ClassTag]].
    *
+   * {{{
    *   class ExampleActor extends TypeActor.Of[ExampleProtocol] {
    *     // ...
    *   }
    * }}}
    *
    * @tparam A the message type this actor is receiving
    */
-  trait Of[A] extends TypedActor {final type Message = A}
+  abstract class Of[A](implicit val _ct: ClassTag[A]) extends TypedActor {
+    final type Message = A
+  }
+
+  private class Downcast[A](cls: Class[A])(f: A ⇒ Unit) extends Receive {
+    def isDefinedAt(x: Any): Boolean = cls.isInstance(x)
+    def apply(v1: Any): Unit = f(cls.cast(v1))
+  }
+
+  private class TypedReceiver[A](f: PartialFunction[A, Unit]) extends Receive {
+    private[this] val receive: Receive =
+      f.asInstanceOf[Receive]
 
-  private class TypedReceiver[A](f: PartialFunction[A, Unit]) extends PartialFunction[Any, Unit] {
     def isDefinedAt(x: Any): Boolean = try {
-      f.isDefinedAt(x.asInstanceOf[A])
+      receive.isDefinedAt(x)
     } catch {
       case _: ClassCastException ⇒ false
     }
 
     def apply(x: Any): Unit =
-      f(x.asInstanceOf[A])
+      receive(x)
   }
 }

docs/src/tut/typed-actor.md

@@ -24,11 +24,11 @@ akka.actor.debug.receive=off
 Having a typed reference to an actor is one thing, but how can we improve type-safety within the actor itself?
 **Typed Actors** offers a `trait` called `TypedActor` which you can extend from instead of `Actor`.
 `TypedActor` itself extends `Actor` but contains an abstract type member and typed receive method
-instead of just an untyped receive method. In order to use the `TypedActor`, you have to provide both.
+instead of just an untyped receive method.
+In order to use the `TypedActor`, you have to extend `TypedActor.Of[_]` and provide your message type via type parameter (you cannot extend directly from `TypedActor`).
 
 ```tut
-class MyActor extends TypedActor {
-  type Message = MyMessage
+class MyActor extends TypedActor.Of[MyMessage] {
   def typedReceive = {
     case Foo(foo) => println(s"received a Foo: $foo")
     case Bar(bar) => println(s"received a Bar: $bar")
@@ -50,20 +50,6 @@ class MyActor extends TypedActor {
 }
 ```
 
-#### Message as type parameter
-
-The message type can also be provided as a type parameter on `TypedActor.Of[_]`.
-
-```tut
-class MyActor extends TypedActor.Of[MyMessage] {
-  def typedReceive = {
-    case Foo(foo) => println(s"received a Foo: $foo")
-  }
-}
-val ref = ActorOf(Props[MyMessage, MyActor], name = "my-actor-2")
-ref ! Foo("foo")
-```
-
 
 #### Divergence
 
@@ -81,8 +67,7 @@ akka.actor.debug.receive=on
 ```
 
 ```tut
-class MyOtherActor extends TypedActor {
-  type Message = MyMessage
+class MyOtherActor extends TypedActor.Of[MyMessage] {
   def typedReceive = {
     case Foo(foo) => println(s"received a Foo: $foo")  
     case Bar(bar) => context become LoggingReceive {
@@ -127,6 +112,23 @@ class MyOtherActor extends TypedActor.Of[MyMessage] {
 }
 ```
 
+#### Going back to untyped land
+
+Sometimes you have to receive messages that are outside of your protocol. A typical case is `Terminated`, but other modules and patterns have those messages as well.
+You can use `Untyped` to specify a regular untyped receive block, just as if `receive` were actually the way to go.  
+
+
+```tut
+class MyOtherActor extends TypedActor.Of[MyMessage] {
+  def typedReceive = Untyped {
+    case Terminated(ref) => println(s"$ref terminated")
+    case Foo(foo) => println(s"received a Foo: $foo")
+  }
+}
+```
+
+With `Untyped`, you won't get any compiler support, it is meant as an escape hatch; If you find yourself using `Untyped` all over the place, consider just using a regular `Actor` instead.
+
 Next, learn more ways to create `Props`.
 
 ##### [» Building Props](props.html)

project/plugins.sbt

@@ -1,3 +1,4 @@
+libraryDependencies += "org.slf4j" % "slf4j-nop" % "1.7.10"
 resolvers += Resolver.url(
   "tut-plugin",
   url("http://dl.bintray.com/content/tpolecat/sbt-plugin-releases"))(

tests/src/test/scala/de/knutwalker/akka/typed/TypedActorSpec.scala

@@ -0,0 +1,118 @@
+/*
+ * Copyright 2015 Paul Horn
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package de.knutwalker.akka.typed
+
+import akka.actor.{ UnhandledMessage, DeadLetter, Inbox, ActorSystem }
+import org.specs2.mutable.Specification
+import org.specs2.specification.AfterAll
+
+import scala.concurrent.duration.Duration
+
+import java.util.concurrent.TimeUnit
+
+object TypedActorSpec extends Specification with AfterAll {
+  sequential
+
+  sealed trait MyFoo
+  case object Foo extends MyFoo
+  case object Bar extends MyFoo
+  case object Qux
+
+  implicit val system = ActorSystem("foo")
+  val inbox = Inbox.create(system)
+  system.eventStream.subscribe(inbox.getRef(), classOf[UnhandledMessage])
+
+  "The TypedActor" should {
+    "have typed partial receive" >> {
+      class MyActor extends TypedActor.Of[MyFoo] {
+        def typedReceive = {
+          case Foo => inbox.getRef() ! "received a foo"
+        }
+      }
+      val ref = ActorOf(PropsFor(new MyActor))
+
+      ref ! Foo
+      expectMsg("received a foo")
+
+      ref ! Bar
+      expectUnhandled(Bar, ref)
+
+      ref.untyped ! Qux
+      expectUnhandled(Qux, ref)
+
+      ref.untyped ! Nil
+      expectUnhandled(Nil, ref)
+    }
+
+    "have typed total receive" >> {
+      class MyActor extends TypedActor.Of[MyFoo] {
+        def typedReceive = Total {
+          case Foo => inbox.getRef() ! "received a foo"
+          case Bar => inbox.getRef() ! "received a bar"
+        }
+      }
+      val ref = ActorOf(PropsFor(new MyActor))
+
+      ref ! Foo
+      expectMsg("received a foo")
+
+      ref ! Bar
+      expectMsg("received a bar")
+
+      ref.untyped ! Qux
+      expectUnhandled(Qux, ref)
+
+      ref.untyped ! Nil
+      expectUnhandled(Nil, ref)
+    }
+
+    "have untyped partial receive" >> {
+      class MyActor extends TypedActor.Of[MyFoo] {
+        def typedReceive = Untyped {
+          case Foo => inbox.getRef() ! "received a foo"
+          case Bar => inbox.getRef() ! "received a bar"
+          case Qux => inbox.getRef() ! "receive a qux"
+        }
+      }
+      val ref = ActorOf(PropsFor(new MyActor))
+
+      ref ! Foo
+      expectMsg("received a foo")
+
+      ref ! Bar
+      expectMsg("received a bar")
+
+      ref.untyped ! Qux
+      expectMsg("receive a qux")
+
+      ref.untyped ! Nil
+      expectUnhandled(Nil, ref)
+    }
+  }
+
+
+
+  def expectUnhandled(message: Any, ref: ActorRef[_]) =
+    inbox.receive(Duration(10, TimeUnit.MILLISECONDS)) === UnhandledMessage(message, system.deadLetters, ref.untyped)
+
+  def expectMsg(expected: Any) =
+    inbox.receive(Duration(10, TimeUnit.MILLISECONDS)) === expected
+
+
+
+  def afterAll(): Unit = system.shutdown()
+}