stashin commit so Iulian can play with it

.gitignore

@@ -64,3 +64,4 @@ mongoDB/
 redis/
 beanstalk/
 .scalastyle
+bin/

akka-actor/src/main/java/akka/japi/JAPI.java

@@ -0,0 +1,11 @@
+package akka.japi;
+
+import scala.collection.Seq;
+
+public class JAPI {
+
+  public static <T> Seq<T> seq(T... ts) {
+    return Util.arrayToSeq(ts);
+  }
+
+}

akka-actor/src/main/scala/akka/japi/JavaAPI.scala

@@ -5,6 +5,7 @@
 package akka.japi
 
 import scala.Some
+import scala.util.control.NoStackTrace
 
 /**
  * A Function interface. Used to create first-class-functions is Java.
@@ -44,6 +45,50 @@ trait Creator[T] {
   def create(): T
 }
 
+object PurePartialFunction {
+  case object NoMatch extends RuntimeException with NoStackTrace
+}
+
+/**
+ * Helper for implementing a *pure* partial function: it will possibly be
+ * invoked multiple times for a single “application”, because its only abstract
+ * method is used for both isDefinedAt() and apply(); the former is mapped to
+ * `isCheck == true` and the latter to `isCheck == false` for those cases where
+ * this is important to know.
+ *
+ * {{{
+ * new PurePartialFunction<Object, String>() {
+ *   public String apply(Object in, boolean isCheck) {
+ *     if (in instanceof TheThing) {
+ *       if (isCheck) return null; // to spare the expensive or side-effecting code
+ *       return doSomethingWithTheThing((TheThing) in);
+ *     } else {
+ *       throw noMatch();
+ *     }
+ *   }
+ * }
+ * }}}
+ *
+ * The typical use of partial functions from Akka looks like the following:
+ *
+ * {{{
+ * if (pf.isDefinedAt(x)) pf.apply(x)
+ * }}}
+ *
+ * i.e. it will first call `PurePartialFunction.apply(x, true)` and if that
+ * does not throw `noMatch()` it will continue with calling
+ * `PurePartialFunction.apply(x, false)`.
+ */
+abstract class PurePartialFunction[A, B] extends scala.runtime.AbstractFunction1[A, B] with PartialFunction[A, B] {
+  import PurePartialFunction._
+
+  def apply(x: A, isCheck: Boolean): B
+
+  final def isDefinedAt(x: A): Boolean = try { apply(x, true); true } catch { case NoMatch ⇒ false }
+  final def apply(x: A): B = try apply(x, false) catch { case NoMatch ⇒ throw new MatchError }
+  final def noMatch(): RuntimeException = NoMatch
+}
+
 /**
  * This class represents optional values. Instances of <code>Option</code>
  * are either instances of case class <code>Some</code> or it is case
@@ -117,4 +162,6 @@ object Util {
    * Given a Class returns a Scala Manifest of that Class
    */
   def manifest[T](clazz: Class[T]): Manifest[T] = Manifest.classType(clazz)
+
+  def arrayToSeq[T](arr: Array[T]): Seq[T] = arr.toSeq
 }

akka-docs/java/code/docs/testkit/TestKitDocTest.java

@@ -0,0 +1,131 @@
+/*
+ * 
+ */
+package docs.testkit;
+
+import static org.junit.Assert.*;
+
+import org.junit.AfterClass;
+import org.junit.Test;
+
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+import akka.actor.UntypedActor;
+import akka.dispatch.Await;
+import akka.dispatch.Future;
+import akka.japi.JAPI;
+import akka.japi.PurePartialFunction;
+import akka.testkit.TestActorRef;
+import akka.testkit.TestKit;
+import akka.util.Duration;
+
+public class TestKitDocTest {
+
+  //#test-actor-ref
+  static class MyActor extends UntypedActor {
+    public void onReceive(Object o) throws Exception {
+      if (o.equals("say42")) {
+        getSender().tell(42, getSelf());
+      } else if (o instanceof Exception) {
+        throw (Exception) o;
+      }
+    }
+    public boolean testMe() { return true; }
+  }
+
+  //#test-actor-ref
+
+  private static ActorSystem system;
+
+  public TestKitDocTest() {
+    system = ActorSystem.create();
+  }
+
+  @AfterClass
+  public static void cleanup() {
+    system.shutdown();
+  }
+
+  //#test-actor-ref
+  @Test
+  public void demonstrateTestActorRef() {
+    final Props props = new Props(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.apply(props, system);
+    final MyActor actor = ref.underlyingActor();
+    assertTrue(actor.testMe());
+  }
+  //#test-actor-ref
+
+  //#test-behavior
+  @Test
+  public void demonstrateAsk() throws Exception {
+    final Props props = new Props(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.apply(props, system);
+    final Future<Object> future = akka.pattern.Patterns.ask(ref, "say42", 3000);
+    assertTrue(future.isCompleted());
+    assertEquals(42, Await.result(future, Duration.Zero()));
+  }
+  //#test-behavior
+
+  //#test-expecting-exceptions
+  @Test
+  public void demonstrateExceptions() {
+    final Props props = new Props(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.apply(props, system);
+    try {
+      ref.receive(new Exception("expected"));
+      fail("expected an exception to be thrown");
+    } catch (Exception e) {
+      assertEquals("expected", e.getMessage());
+    }
+  }
+  //#test-expecting-exceptions
+
+  //#test-within
+  @Test
+  public void demonstrateWithin() {
+    new TestKit(system) {{
+      testActor().tell(42);
+      new Within(Duration.parse("1 second")) {
+        // do not put code outside this method, will run afterwards
+        public void run() {
+          assertEquals((Integer) 42, expectMsgClass(Integer.class));
+        }
+      };
+    }};
+  }
+  //#test-within
+
+  @Test
+  public void demonstrateExpectMsgPF() {
+    new TestKit(system) {{
+      testActor().tell(42);
+      //#test-expect-pf
+      final String out = expectMsgPF(Duration.parse("1 second"), "fourty-two",
+        new PurePartialFunction<Object, String>() {
+          public String apply(Object in, boolean isCheck) {
+            if (Integer.valueOf(42).equals(in)) {
+              return "match";
+            } else {
+              throw noMatch();
+            }
+          }
+        }
+      );
+      assertEquals("match", out);
+      //#test-expect-pf
+      testActor().tell("world");
+      //#test-expect-anyof
+      final String any = expectMsgAnyOf(remaining(), JAPI.seq("hello", "world"));
+      //#test-expect-anyof
+      assertEquals("world", any);
+      testActor().tell("world");
+      //#test-expect-anyclassof
+      @SuppressWarnings("unchecked")
+      final String anyClass = expectMsgAnyClassOf(remaining(), JAPI.<Class<? extends String>>seq(String.class));
+      //#test-expect-anyclassof
+      assertEquals("world", any);
+    }};
+  }
+
+}