+doc #19429 initial merge of docs-dev and docs

akka-docs/rst/java/code/docs/actor/fsm/Buncher.java

@@ -0,0 +1,136 @@
+/**
+ * Copyright (C) 2009-2014 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.actor.fsm;
+
+//#simple-imports
+import akka.actor.AbstractFSM;
+import akka.actor.ActorRef;
+import akka.japi.pf.UnitMatch;
+import java.util.Arrays;
+import java.util.LinkedList;
+import java.util.List;
+import scala.concurrent.duration.Duration;
+//#simple-imports
+
+import static docs.actor.fsm.Buncher.Data;
+import static docs.actor.fsm.Buncher.State.*;
+import static docs.actor.fsm.Buncher.State;
+import static docs.actor.fsm.Buncher.Uninitialized.*;
+import static docs.actor.fsm.Events.*;
+
+//#simple-fsm
+public class Buncher extends AbstractFSM<State, Data> {
+  {
+    //#fsm-body
+    startWith(Idle, Uninitialized);
+
+    //#when-syntax
+    when(Idle,
+      matchEvent(SetTarget.class, Uninitialized.class,
+        (setTarget, uninitialized) ->
+          stay().using(new Todo(setTarget.getRef(), new LinkedList<>()))));
+    //#when-syntax
+
+    //#transition-elided
+    onTransition(
+      matchState(Active, Idle, () -> {
+        // reuse this matcher
+        final UnitMatch<Data> m = UnitMatch.create(
+          matchData(Todo.class,
+            todo -> todo.getTarget().tell(new Batch(todo.getQueue()), self())));
+        m.match(stateData());
+      }).
+      state(Idle, Active, () -> {/* Do something here */}));
+    //#transition-elided
+
+    when(Active, Duration.create(1, "second"),
+      matchEvent(Arrays.asList(Flush.class, StateTimeout()), Todo.class,
+        (event, todo) -> goTo(Idle).using(todo.copy(new LinkedList<>()))));
+
+    //#unhandled-elided
+    whenUnhandled(
+      matchEvent(Queue.class, Todo.class,
+        (queue, todo) -> goTo(Active).using(todo.addElement(queue.getObj()))).
+        anyEvent((event, state) -> {
+          log().warning("received unhandled request {} in state {}/{}",
+            event, stateName(), state);
+          return stay();
+        }));
+    //#unhandled-elided
+
+    initialize();
+    //#fsm-body
+  }
+  //#simple-fsm
+
+  static
+  //#simple-state
+  // states
+  enum State {
+    Idle, Active
+  }
+
+  //#simple-state
+  static
+  //#simple-state
+  // state data
+  interface Data {
+  }
+
+  //#simple-state
+  static
+  //#simple-state
+  enum Uninitialized implements Data {
+    Uninitialized
+  }
+
+  //#simple-state
+  static
+  //#simple-state
+  final class Todo implements Data {
+    private final ActorRef target;
+    private final List<Object> queue;
+
+    public Todo(ActorRef target, List<Object> queue) {
+      this.target = target;
+      this.queue = queue;
+    }
+
+    public ActorRef getTarget() {
+      return target;
+    }
+
+    public List<Object> getQueue() {
+      return queue;
+    }
+    //#boilerplate
+
+    @Override
+    public String toString() {
+      return "Todo{" +
+        "target=" + target +
+        ", queue=" + queue +
+        '}';
+    }
+
+    public Todo addElement(Object element) {
+      List<Object> nQueue = new LinkedList<>(queue);
+      nQueue.add(element);
+      return new Todo(this.target, nQueue);
+    }
+
+    public Todo copy(List<Object> queue) {
+      return new Todo(this.target, queue);
+    }
+
+    public Todo copy(ActorRef target) {
+      return new Todo(target, this.queue);
+    }
+    //#boilerplate
+  }
+  //#simple-state
+  //#simple-fsm
+}
+//#simple-fsm

akka-docs/rst/java/code/docs/actor/fsm/BuncherTest.java

@@ -0,0 +1,78 @@
+/**
+ * Copyright (C) 2009-2014 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.actor.fsm;
+
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+import akka.testkit.JavaTestKit;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import java.util.LinkedList;
+
+import docs.actor.fsm.*;
+import static docs.actor.fsm.Events.Batch;
+import static docs.actor.fsm.Events.Queue;
+import static docs.actor.fsm.Events.SetTarget;
+import static docs.actor.fsm.Events.Flush.Flush;
+
+//#test-code
+public class BuncherTest {
+
+  static ActorSystem system;
+
+  @BeforeClass
+  public static void setup() {
+    system = ActorSystem.create("BuncherTest");
+  }
+
+  @AfterClass
+  public static void tearDown() {
+    JavaTestKit.shutdownActorSystem(system);
+    system = null;
+  }
+
+  @Test
+  public void testBuncherActorBatchesCorrectly() {
+    new JavaTestKit(system) {{
+      final ActorRef buncher =
+        system.actorOf(Props.create(Buncher.class));
+      final ActorRef probe = getRef();
+
+      buncher.tell(new SetTarget(probe), probe);
+      buncher.tell(new Queue(42), probe);
+      buncher.tell(new Queue(43), probe);
+      LinkedList<Object> list1 = new LinkedList<>();
+      list1.add(42);
+      list1.add(43);
+      expectMsgEquals(new Batch(list1));
+      buncher.tell(new Queue(44), probe);
+      buncher.tell(Flush, probe);
+      buncher.tell(new Queue(45), probe);
+      LinkedList<Object> list2 = new LinkedList<>();
+      list2.add(44);
+      expectMsgEquals(new Batch(list2));
+      LinkedList<Object> list3 = new LinkedList<>();
+      list3.add(45);
+      expectMsgEquals(new Batch(list3));
+      system.stop(buncher);
+    }};
+  }
+
+  @Test
+  public void testBuncherActorDoesntBatchUninitialized() {
+    new JavaTestKit(system) {{
+      final ActorRef buncher =
+        system.actorOf(Props.create(Buncher.class));
+      final ActorRef probe = getRef();
+
+      buncher.tell(new Queue(42), probe);
+      expectNoMsg();
+      system.stop(buncher);
+    }};
+  }
+}
+//#test-code

akka-docs/rst/java/code/docs/actor/fsm/Events.java

@@ -0,0 +1,108 @@
+/**
+ * Copyright (C) 2009-2014 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.actor.fsm;
+
+import akka.actor.ActorRef;
+import java.util.List;
+
+public class Events {
+
+  static
+  //#simple-events
+  public final class SetTarget {
+    private final ActorRef ref;
+
+    public SetTarget(ActorRef ref) {
+      this.ref = ref;
+    }
+
+    public ActorRef getRef() {
+      return ref;
+    }
+    //#boilerplate
+
+    @Override
+    public String toString() {
+      return "SetTarget{" +
+        "ref=" + ref +
+        '}';
+    }
+    //#boilerplate
+  }
+
+  //#simple-events
+  static
+  //#simple-events
+  public final class Queue {
+    private final Object obj;
+
+    public Queue(Object obj) {
+      this.obj = obj;
+    }
+
+    public Object getObj() {
+      return obj;
+    }
+    //#boilerplate
+
+    @Override
+    public String toString() {
+      return "Queue{" +
+        "obj=" + obj +
+        '}';
+    }
+    //#boilerplate
+  }
+
+  //#simple-events
+  static
+  //#simple-events
+  public final class Batch {
+    private final List<Object> list;
+
+    public Batch(List<Object> list) {
+      this.list = list;
+    }
+
+    public List<Object> getList() {
+      return list;
+    }
+    //#boilerplate
+
+    @Override
+    public boolean equals(Object o) {
+      if (this == o) return true;
+      if (o == null || getClass() != o.getClass()) return false;
+
+      Batch batch = (Batch) o;
+
+      return list.equals(batch.list);
+    }
+
+    @Override
+    public int hashCode() {
+      return list.hashCode();
+    }
+
+    @Override
+    public String toString() {
+      final StringBuilder builder = new StringBuilder();
+      builder.append( "Batch{list=");
+      list.stream().forEachOrdered(e -> { builder.append(e); builder.append(","); });
+      int len = builder.length();
+      builder.replace(len, len, "}");
+      return builder.toString();
+    }
+    //#boilerplate
+  }
+
+  //#simple-events
+  static
+  //#simple-events
+  public enum Flush {
+    Flush
+  }
+  //#simple-events
+}

akka-docs/rst/java/code/docs/actor/fsm/FSMDocTest.java

@@ -0,0 +1,179 @@
+/**
+ * Copyright (C) 2009-2014 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.actor.fsm;
+
+import akka.actor.*;
+import akka.testkit.JavaTestKit;
+import org.hamcrest.CoreMatchers;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import scala.concurrent.duration.Duration;
+
+import static org.junit.Assert.*;
+
+import static docs.actor.fsm.FSMDocTest.StateType.*;
+import static docs.actor.fsm.FSMDocTest.Messages.*;
+import static java.util.concurrent.TimeUnit.*;
+
+public class FSMDocTest {
+  static ActorSystem system;
+
+  @BeforeClass
+  public static void setup() {
+    system = ActorSystem.create("FSMDocTest");
+  }
+
+  @AfterClass
+  public static void tearDown() {
+    JavaTestKit.shutdownActorSystem(system);
+    system = null;
+  }
+
+  public static enum StateType {
+    SomeState,
+    Processing,
+    Idle,
+    Active,
+    Error
+  }
+
+  public static enum Messages {
+    WillDo,
+    Tick
+  }
+
+  public static enum Data {
+    Foo,
+    Bar
+  };
+
+  public static interface X {};
+
+  public static class DummyFSM extends AbstractFSM<StateType, Integer> {
+    Integer newData = 42;
+    //#alt-transition-syntax
+    public void handler(StateType from, StateType to) {
+      // handle transition here
+    }
+
+    //#alt-transition-syntax
+    {
+    //#modifier-syntax
+    when(SomeState, matchAnyEvent((msg, data) -> {
+        return goTo(Processing).using(newData).
+          forMax(Duration.create(5, SECONDS)).replying(WillDo);
+    }));
+    //#modifier-syntax
+
+    //#NullFunction
+    when(SomeState, AbstractFSM.NullFunction());
+    //#NullFunction
+
+    //#transition-syntax
+    onTransition(
+      matchState(Active, Idle, () -> setTimer("timeout",
+        Tick, Duration.create(1, SECONDS), true)).
+      state(Active, null, () -> cancelTimer("timeout")).
+      state(null, Idle, (f, t) -> log().info("entering Idle from " + f)));
+    //#transition-syntax
+
+    //#alt-transition-syntax
+    onTransition(this::handler);
+    //#alt-transition-syntax
+
+    //#stop-syntax
+    when(Error, matchEventEquals("stop", (event, data) -> {
+      // do cleanup ...
+      return stop();
+    }));
+    //#stop-syntax
+
+    //#termination-syntax
+    onTermination(
+      matchStop(Normal(),
+        (state, data) -> {/* Do something here */}).
+        stop(Shutdown(),
+          (state, data) -> {/* Do something here */}).
+        stop(Failure.class,
+          (reason, state, data) -> {/* Do something here */}));
+    //#termination-syntax
+
+    //#unhandled-syntax
+    whenUnhandled(
+      matchEvent(X.class, (x, data) -> {
+        log().info("Received unhandled event: " + x);
+        return stay();
+      }).
+      anyEvent((event, data) -> {
+        log().warning("Received unknown event: " + event);
+        return goTo(Error);
+      }));
+    }
+    //#unhandled-syntax
+    }
+
+  static
+  //#logging-fsm
+  public class MyFSM extends AbstractLoggingFSM<StateType, Data> {
+    //#body-elided
+    //#logging-fsm
+    ActorRef target = null;
+    //#logging-fsm
+    @Override
+    public int logDepth() { return 12; }
+    {
+      onTermination(
+        matchStop(Failure.class, (reason, state, data) -> {
+          String lastEvents = getLog().mkString("\n\t");
+          log().warning("Failure in state " + state + " with data " + data + "\n" +
+            "Events leading up to this point:\n\t" + lastEvents);
+          //#logging-fsm
+          target.tell(reason.cause(), self());
+          target.tell(state, self());
+          target.tell(data, self());
+          target.tell(lastEvents, self());
+          //#logging-fsm
+        })
+      );
+      //...
+      //#logging-fsm
+      startWith(SomeState, Data.Foo);
+      when(SomeState, matchEvent(ActorRef.class, Data.class, (ref, data) -> {
+        target = ref;
+        target.tell("going active", self());
+        return goTo(Active);
+      }));
+      when(Active, matchEventEquals("stop", (event, data) -> {
+        target.tell("stopping", self());
+        return stop(new Failure("This is not the error you're looking for"));
+      }));
+      initialize();
+      //#logging-fsm
+    }
+    //#body-elided
+  }
+  //#logging-fsm
+
+  @Test
+  public void testLoggingFSM()
+  {
+    new JavaTestKit(system) {{
+      final ActorRef logger =
+        system.actorOf(Props.create(MyFSM.class));
+      final ActorRef probe = getRef();
+
+      logger.tell(probe, probe);
+      expectMsgEquals("going active");
+      logger.tell("stop", probe);
+      expectMsgEquals("stopping");
+      expectMsgEquals("This is not the error you're looking for");
+      expectMsgEquals(Active);
+      expectMsgEquals(Data.Foo);
+      String msg = expectMsgClass(String.class);
+      assertThat(msg, CoreMatchers.startsWith("LogEntry(SomeState,Foo,Actor[akka://FSMDocTest/system/"));
+    }};
+  }
+}