ActorContext.getParent for Java API #22413

akka-docs/rst/java/code/jdocs/testkit/ParentChildTest.java

@@ -0,0 +1,217 @@
+/**
+ * Copyright (C) 2014-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+package jdocs.testkit;
+
+import static org.junit.Assert.*;
+import akka.actor.*;
+import akka.japi.Creator;
+import akka.japi.Function;
+import akka.testkit.AkkaJUnitActorSystemResource;
+import akka.testkit.JavaTestKit;
+import akka.testkit.TestActorRef;
+import akka.testkit.TestProbe;
+
+import com.typesafe.config.ConfigFactory;
+
+import docs.testkit.MockedChild;
+import jdocs.AbstractJavaTest;
+import org.junit.ClassRule;
+import org.junit.Test;
+
+public class ParentChildTest extends AbstractJavaTest {
+  @ClassRule
+  public static AkkaJUnitActorSystemResource actorSystemResource =
+    new AkkaJUnitActorSystemResource("TestKitDocTest",
+                                     ConfigFactory.parseString("akka.loggers = [akka.testkit.TestEventListener]"));
+
+
+  private final ActorSystem system = actorSystemResource.getSystem();
+
+  //#test-example
+  static class Parent extends AbstractActor {
+    final ActorRef child = getContext().actorOf(Props.create(Child.class), "child");
+    boolean ponged = false;
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("pingit", message -> child.tell("ping", getSelf()))
+        .matchEquals("pong", message -> ponged = true)
+        .build();
+    }
+  }
+
+  static class Child extends AbstractActor {
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("ping", message -> {
+          getContext().getParent().tell("pong", getSelf());
+        })
+        .build();
+    }
+  }
+  //#test-example
+
+  static
+  //#test-dependentchild
+  class DependentChild extends AbstractActor {
+    private final ActorRef parent;
+
+    public DependentChild(ActorRef parent) {
+      this.parent = parent;
+    }
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("ping", message -> parent.tell("pong", getSelf()))
+        .build();
+    }
+  }
+  //#test-dependentchild
+
+  static
+  //#test-dependentparent
+  class DependentParent extends AbstractActor {
+    final ActorRef child;
+    boolean ponged = false;
+
+    public DependentParent(Props childProps) {
+      child = getContext().actorOf(childProps, "child");
+    }
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("pingit", message -> child.tell("ping", getSelf()))
+        .matchEquals("pong", message -> ponged = true)
+        .build();
+    }
+  }
+  //#test-dependentparent
+
+  static
+  //#test-dependentparent-generic
+  class GenericDependentParent extends AbstractActor {
+    final ActorRef child;
+    boolean ponged = false;
+
+    public GenericDependentParent(Function<ActorRefFactory, ActorRef> childMaker)
+      throws Exception {
+      child = childMaker.apply(getContext());
+    }
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("pingit", message -> child.tell("ping", getSelf()))
+        .matchEquals("pong", message -> ponged = true)
+        .build();
+    }
+  }
+  //#test-dependentparent-generic
+
+  @Test
+  public void testingWithoutParent() {
+    TestProbe probe = new TestProbe(system);
+    ActorRef child = system.actorOf(Props.create(DependentChild.class, probe.ref()));
+    probe.send(child, "ping");
+    probe.expectMsg("pong");
+  }
+
+  @Test
+  public void testingWithCustomProps() {
+    TestProbe probe = new TestProbe(system);
+    Props childProps = Props.create(MockedChild.class);
+    TestActorRef<DependentParent> parent = TestActorRef.create(system, Props.create(DependentParent.class, childProps));
+
+    probe.send(parent, "pingit");
+
+    // test some parent state change
+    assertTrue(parent.underlyingActor().ponged == true || parent.underlyingActor().ponged == false);
+  }
+
+
+  @Test
+  public void testingWithChildProbe() throws Exception {
+    final TestProbe probe = new TestProbe(system);
+    //#child-maker-test
+    Function<ActorRefFactory, ActorRef> maker = new Function<ActorRefFactory, ActorRef>() {
+      @Override public ActorRef apply(ActorRefFactory param) throws Exception {
+        return probe.ref();
+      }
+    };
+    ActorRef parent = system.actorOf(Props.create(GenericDependentParent.class, maker));
+    //#child-maker-test
+    probe.send(parent, "pingit");
+    probe.expectMsg("ping");
+  }
+
+  public void exampleProdActorFactoryFunction() throws Exception {
+    //#child-maker-prod
+    Function<ActorRefFactory, ActorRef> maker = new Function<ActorRefFactory, ActorRef>() {
+      @Override public ActorRef apply(ActorRefFactory f) throws Exception {
+        return f.actorOf(Props.create(Child.class));
+      }
+    };
+    ActorRef parent = system.actorOf(Props.create(GenericDependentParent.class, maker));
+    //#child-maker-prod
+  }
+
+  static
+  //#test-fabricated-parent-creator
+  class FabricatedParentCreator implements Creator<Actor> {
+    private final TestProbe proxy;
+
+    public FabricatedParentCreator(TestProbe proxy) {
+      this.proxy = proxy;
+    }
+
+    @Override public Actor create() throws Exception {
+      return new AbstractActor() {
+        final ActorRef child = getContext().actorOf(Props.create(Child.class), "child");
+
+        @Override
+        public Receive createReceive() {
+          return receiveBuilder()
+            .matchAny(message -> {
+              if (sender().equals(child)) {
+                proxy.ref().forward(message, getContext());
+              } else {
+                child.forward(message, getContext());
+              }
+            })
+            .build();
+
+        }
+      };
+    }
+  }
+  //#test-fabricated-parent-creator
+
+  @Test
+  public void testProbeParentTest() throws Exception {
+  //#test-TestProbe-parent
+    JavaTestKit parent = new JavaTestKit(system);
+    ActorRef child = parent.childActorOf(Props.create(Child.class));
+    
+    parent.send(child, "ping");
+    parent.expectMsgEquals("pong");
+  //#test-TestProbe-parent
+  }
+  
+  @Test
+  public void fabricatedParentTestsItsChildResponses() throws Exception {
+    // didn't put final on these in order to make the parent fit in one line in the html docs
+    //#test-fabricated-parent
+    TestProbe proxy = new TestProbe(system);
+    ActorRef parent = system.actorOf(Props.create(new FabricatedParentCreator(proxy)));
+
+    proxy.send(parent, "ping");
+    proxy.expectMsg("pong");
+    //#test-fabricated-parent
+  }
+
+}

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

@@ -0,0 +1,441 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+package jdocs.testkit;
+
+import static org.junit.Assert.*;
+
+import akka.pattern.PatternsCS;
+import akka.testkit.*;
+import jdocs.AbstractJavaTest;
+import org.junit.Assert;
+import org.junit.ClassRule;
+import org.junit.Test;
+
+import com.typesafe.config.ConfigFactory;
+
+import akka.actor.ActorKilledException;
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.Kill;
+import akka.actor.PoisonPill;
+import akka.actor.Props;
+import akka.actor.Terminated;
+import akka.actor.AbstractActor;
+import akka.testkit.TestActor.AutoPilot;
+import scala.concurrent.duration.Duration;
+
+import java.util.concurrent.CompletableFuture;
+
+public class TestKitDocTest extends AbstractJavaTest {
+
+  @ClassRule
+  public static AkkaJUnitActorSystemResource actorSystemResource =
+    new AkkaJUnitActorSystemResource("TestKitDocTest",
+      ConfigFactory.parseString("akka.loggers = [akka.testkit.TestEventListener]"));
+
+  private final ActorSystem system = actorSystemResource.getSystem();
+
+  //#test-actor-ref
+  static class MyActor extends AbstractActor {
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("say42", message -> {
+          getSender().tell(42, getSelf());
+        })
+        .match(Exception.class, (Exception ex) -> {
+          throw ex;
+        })
+        .build();
+    }
+    public boolean testMe() { return true; }
+  }
+
+  @Test
+  public void demonstrateTestActorRef() {
+    final Props props = Props.create(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.create(system, props, "testA");
+    final MyActor actor = ref.underlyingActor();
+    assertTrue(actor.testMe());
+  }
+  //#test-actor-ref
+
+  @Test
+  public void demonstrateAsk() throws Exception {
+    //#test-behavior
+    final Props props = Props.create(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.create(system, props, "testB");
+    final CompletableFuture<Object> future = PatternsCS.ask(ref, "say42", 3000).toCompletableFuture();
+    assertTrue(future.isDone());
+    assertEquals(42, future.get());
+    //#test-behavior
+  }
+
+  @Test
+  public void demonstrateExceptions() {
+    //#test-expecting-exceptions
+    final Props props = Props.create(MyActor.class);
+    final TestActorRef<MyActor> ref = TestActorRef.create(system, props, "myActor");
+    try {
+      ref.receive(new Exception("expected"));
+      Assert.fail("expected an exception to be thrown");
+    } catch (Exception e) {
+      assertEquals("expected", e.getMessage());
+    }
+    //#test-expecting-exceptions
+  }
+
+  @Test
+  public void demonstrateWithin() {
+    //#test-within
+    new JavaTestKit(system) {{
+      getRef().tell(42, ActorRef.noSender());
+      new Within(Duration.Zero(), Duration.create(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 demonstrateExpectMsg() {
+    //#test-expectmsg
+    new JavaTestKit(system) {{
+      getRef().tell(42, ActorRef.noSender());
+      final String out = new ExpectMsg<String>("match hint") {
+          // do not put code outside this method, will run afterwards
+          protected String match(Object in) {
+            if (in instanceof Integer) {
+              return "match";
+            } else {
+              throw noMatch();
+            }
+          }
+        }.get(); // this extracts the received message
+      assertEquals("match", out);
+    }};
+    //#test-expectmsg
+  }
+
+  @Test
+  public void demonstrateReceiveWhile() {
+    //#test-receivewhile
+    new JavaTestKit(system) {{
+      getRef().tell(42, ActorRef.noSender());
+      getRef().tell(43, ActorRef.noSender());
+      getRef().tell("hello", ActorRef.noSender());
+      final String[] out =
+        new ReceiveWhile<String>(String.class, duration("1 second")) {
+          // do not put code outside this method, will run afterwards
+          protected String match(Object in) {
+            if (in instanceof Integer) {
+              return in.toString();
+            } else {
+              throw noMatch();
+            }
+          }
+        }.get(); // this extracts the received messages
+      assertArrayEquals(new String[] {"42", "43"}, out);
+      expectMsgEquals("hello");
+    }};
+    //#test-receivewhile
+    new JavaTestKit(system) {{
+      //#test-receivewhile-full
+      new ReceiveWhile<String>(     // type of array to be created must match ...
+            String.class,           // ... this class which is needed to that end
+            duration("100 millis"), // maximum collect time
+            duration("50 millis"),  // maximum time between messages
+            12                      // maximum number of messages to collect
+            ) {
+        //#match-elided
+        protected String match(Object in) {
+          throw noMatch();
+        }
+        //#match-elided
+      };
+      //#test-receivewhile-full
+    }};
+  }
+
+  @Test
+  public void demonstrateAwaitCond() {
+    //#test-awaitCond
+    new JavaTestKit(system) {{
+      getRef().tell(42, ActorRef.noSender());
+      new AwaitCond(
+            duration("1 second"),  // maximum wait time
+            duration("100 millis") // interval at which to check the condition
+            ) {
+        // do not put code outside this method, will run afterwards
+        protected boolean cond() {
+          // typically used to wait for something to start up
+          return msgAvailable();
+        }
+      };
+    }};
+    //#test-awaitCond
+  }
+
+  @Test
+  public void demonstrateAwaitAssert() {
+    //#test-awaitAssert
+    new JavaTestKit(system) {{
+      getRef().tell(42, ActorRef.noSender());
+      new AwaitAssert(
+            duration("1 second"),  // maximum wait time
+            duration("100 millis") // interval at which to check the condition
+            ) {
+        // do not put code outside this method, will run afterwards
+        protected void check() {
+          assertEquals(msgAvailable(), true);
+        }
+      };
+    }};
+    //#test-awaitAssert
+  }
+
+  @Test
+  @SuppressWarnings({ "unchecked", "unused" }) // due to generic varargs
+  public void demonstrateExpect() {
+    new JavaTestKit(system) {{
+      getRef().tell("hello", ActorRef.noSender());
+      getRef().tell("hello", ActorRef.noSender());
+      getRef().tell("hello", ActorRef.noSender());
+      getRef().tell("world", ActorRef.noSender());
+      getRef().tell(42, ActorRef.noSender());
+      getRef().tell(42, ActorRef.noSender());
+      //#test-expect
+      final String hello = expectMsgEquals("hello");
+      final Object   any = expectMsgAnyOf("hello", "world");
+      final Object[] all = expectMsgAllOf("hello", "world");
+      final int i        = expectMsgClass(Integer.class);
+      final Number j     = expectMsgAnyClassOf(Integer.class, Long.class);
+      expectNoMsg();
+      //#test-expect
+      getRef().tell("receveN-1", ActorRef.noSender());
+      getRef().tell("receveN-2", ActorRef.noSender());
+      //#test-expect
+      final Object[] two = receiveN(2);
+      //#test-expect
+      assertEquals("hello", hello);
+      assertEquals("hello", any);
+      assertEquals(42, i);
+      assertEquals(42, j);
+      assertArrayEquals(new String[] {"hello", "world"}, all);
+    }};
+  }
+
+  @Test
+  public void demonstrateIgnoreMsg() {
+    //#test-ignoreMsg
+    new JavaTestKit(system) {{
+      // ignore all Strings
+      new IgnoreMsg() {
+        protected boolean ignore(Object msg) {
+          return msg instanceof String;
+        }
+      };
+      getRef().tell("hello", ActorRef.noSender());
+      getRef().tell(42, ActorRef.noSender());
+      expectMsgEquals(42);
+      // remove message filter
+      ignoreNoMsg();
+      getRef().tell("hello", ActorRef.noSender());
+      expectMsgEquals("hello");
+    }};
+    //#test-ignoreMsg
+  }
+
+  @Test
+  public void demonstrateDilated() {
+    //#duration-dilation
+    new JavaTestKit(system) {{
+      final Duration original = duration("1 second");
+      final Duration stretched = dilated(original);
+      assertTrue("dilated", stretched.gteq(original));
+    }};
+    //#duration-dilation
+  }
+
+  @Test
+  public void demonstrateProbe() {
+    //#test-probe
+    new JavaTestKit(system) {{
+      // simple actor which just forwards messages
+      class Forwarder extends AbstractActor {
+        final ActorRef target;
+        @SuppressWarnings("unused")
+        public Forwarder(ActorRef target) {
+          this.target = target;
+        }
+        @Override
+        public Receive createReceive() {
+          return receiveBuilder()
+            .matchAny(message -> target.forward(message, getContext()))
+            .build();
+        }
+      }
+      
+      // create a test probe
+      final JavaTestKit probe = new JavaTestKit(system);
+
+      // create a forwarder, injecting the probe’s testActor
+      final Props props = Props.create(Forwarder.class, this, probe.getRef());
+      final ActorRef forwarder = system.actorOf(props, "forwarder");
+
+      // verify correct forwarding
+      forwarder.tell(42, getRef());
+      probe.expectMsgEquals(42);
+      assertEquals(getRef(), probe.getLastSender());
+    }};
+    //#test-probe
+  }
+
+  @Test
+  public void demonstrateTestProbeWithCustomName() {
+    //#test-probe-with-custom-name
+    new JavaTestKit(system) {{
+      final TestProbe worker = new TestProbe(system, "worker");
+      final TestProbe aggregator = new TestProbe(system, "aggregator");
+
+      assertTrue(worker.ref().path().name().startsWith("worker"));
+      assertTrue(aggregator.ref().path().name().startsWith("aggregator"));
+    }};
+    //#test-probe-with-custom-name
+  }
+
+  @Test
+  public void demonstrateSpecialProbe() {
+    //#test-special-probe
+    new JavaTestKit(system) {{
+      class MyProbe extends JavaTestKit {
+        public MyProbe() {
+          super(system);
+        }
+        public void assertHello() {
+          expectMsgEquals("hello");
+        }
+      }
+
+      final MyProbe probe = new MyProbe();
+      probe.getRef().tell("hello", ActorRef.noSender());
+      probe.assertHello();
+    }};
+    //#test-special-probe
+  }
+
+  @Test
+  public void demonstrateWatch() {
+    final ActorRef target = system.actorOf(Props.create(MyActor.class));
+    //#test-probe-watch
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      probe.watch(target);
+      target.tell(PoisonPill.getInstance(), ActorRef.noSender());
+      final Terminated msg = probe.expectMsgClass(Terminated.class);
+      assertEquals(msg.getActor(), target);
+    }};
+    //#test-probe-watch
+  }
+
+  @Test
+  public void demonstrateReply() {
+    //#test-probe-reply
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      probe.getRef().tell("hello", getRef());
+      probe.expectMsgEquals("hello");
+      probe.reply("world");
+      expectMsgEquals("world");
+      assertEquals(probe.getRef(), getLastSender());
+    }};
+    //#test-probe-reply
+  }
+
+  @Test
+  public void demonstrateForward() {
+    //#test-probe-forward
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      probe.getRef().tell("hello", getRef());
+      probe.expectMsgEquals("hello");
+      probe.forward(getRef());
+      expectMsgEquals("hello");
+      assertEquals(getRef(), getLastSender());
+    }};
+    //#test-probe-forward
+  }
+
+  @Test
+  public void demonstrateWithinProbe() {
+    try {
+    //#test-within-probe
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      new Within(duration("1 second")) {
+        public void run() {
+          probe.expectMsgEquals("hello");
+        }
+      };
+    }};
+    //#test-within-probe
+    } catch (AssertionError e) {
+      // expected to fail
+    }
+  }
+
+  @Test
+  public void demonstrateAutoPilot() {
+    //#test-auto-pilot
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      // install auto-pilot
+      probe.setAutoPilot(new TestActor.AutoPilot() {
+        public AutoPilot run(ActorRef sender, Object msg) {
+          sender.tell(msg, ActorRef.noSender());
+          return noAutoPilot();
+        }
+      });
+      // first one is replied to directly ...
+      probe.getRef().tell("hello", getRef());
+      expectMsgEquals("hello");
+      // ... but then the auto-pilot switched itself off
+      probe.getRef().tell("world", getRef());
+      expectNoMsg();
+    }};
+    //#test-auto-pilot
+  }
+
+  // only compilation
+  public void demonstrateCTD() {
+    //#calling-thread-dispatcher
+    system.actorOf(
+      Props.create(MyActor.class)
+        .withDispatcher(CallingThreadDispatcher.Id()));
+    //#calling-thread-dispatcher
+  }
+
+  @Test
+  public void demonstrateEventFilter() {
+    //#test-event-filter
+    new JavaTestKit(system) {{
+      assertEquals("TestKitDocTest", system.name());
+      final ActorRef victim = system.actorOf(Props.empty(), "victim");
+
+      final int result = new EventFilter<Integer>(ActorKilledException.class) {
+        protected Integer run() {
+          victim.tell(Kill.getInstance(), ActorRef.noSender());
+          return 42;
+        }
+      }.from("akka://TestKitDocTest/user/victim").occurrences(1).exec();
+
+      assertEquals(42, result);
+    }};
+    //#test-event-filter
+  }
+
+}

akka-docs/rst/java/code/jdocs/testkit/TestKitSampleTest.java

@@ -0,0 +1,99 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+package jdocs.testkit;
+
+//#fullsample
+import jdocs.AbstractJavaTest;
+import org.junit.AfterClass;
+import org.junit.Assert;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+import akka.actor.AbstractActor;
+import akka.testkit.JavaTestKit;
+import scala.concurrent.duration.Duration;
+
+public class TestKitSampleTest extends AbstractJavaTest {
+  
+  public static class SomeActor extends AbstractActor {
+    ActorRef target = null;
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("hello", message -> {
+          getSender().tell("world", getSelf());
+          if (target != null) target.forward(message, getContext());
+        })
+        .match(ActorRef.class, actorRef -> {
+          target = actorRef;
+          getSender().tell("done", getSelf());
+        })
+        .build();
+    }
+  }
+  
+  static ActorSystem system;
+  
+  @BeforeClass
+  public static void setup() {
+    system = ActorSystem.create();
+  }
+  
+  @AfterClass
+  public static void teardown() {
+    JavaTestKit.shutdownActorSystem(system);
+    system = null;
+  }
+
+  @Test
+  public void testIt() {
+    /*
+     * Wrap the whole test procedure within a testkit constructor 
+     * if you want to receive actor replies or use Within(), etc.
+     */
+    new JavaTestKit(system) {{
+      final Props props = Props.create(SomeActor.class);
+      final ActorRef subject = system.actorOf(props);
+
+      // can also use JavaTestKit “from the outside”
+      final JavaTestKit probe = new JavaTestKit(system);
+      // “inject” the probe by passing it to the test subject
+      // like a real resource would be passed in production
+      subject.tell(probe.getRef(), getRef());
+      // await the correct response
+      expectMsgEquals(duration("1 second"), "done");
+      
+      // the run() method needs to finish within 3 seconds
+      new Within(duration("3 seconds")) {
+        protected void run() {
+
+          subject.tell("hello", getRef());
+
+          // This is a demo: would normally use expectMsgEquals().
+          // Wait time is bounded by 3-second deadline above.
+          new AwaitCond() {
+            protected boolean cond() {
+              return probe.msgAvailable();
+            }
+          };
+
+          // response must have been enqueued to us before probe
+          expectMsgEquals(Duration.Zero(), "world");
+          // check that the probe we injected earlier got the msg
+          probe.expectMsgEquals(Duration.Zero(), "hello");
+          Assert.assertEquals(getRef(), probe.getLastSender());
+
+          // Will wait for the rest of the 3 seconds
+          expectNoMsg();
+        }
+      };
+    }};
+  }
+  
+}
+//#fullsample