move code to src/test

* so that it compiles and tests pass
* fix some additional snip references in getting started

akka-docs/src/test/java/jdocs/io/japi/EchoHandler.java

@@ -0,0 +1,243 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+import java.net.InetSocketAddress;
+import java.util.LinkedList;
+import java.util.Queue;
+
+import akka.actor.ActorRef;
+import akka.actor.AbstractActor;
+import akka.event.Logging;
+import akka.event.LoggingAdapter;
+import akka.io.Tcp.CommandFailed;
+import akka.io.Tcp.ConnectionClosed;
+import akka.io.Tcp.Event;
+import akka.io.Tcp.Received;
+import akka.io.Tcp.Write;
+import akka.io.Tcp.WritingResumed;
+import akka.io.TcpMessage;
+import akka.util.ByteString;
+
+//#echo-handler
+public class EchoHandler extends AbstractActor {
+
+  final LoggingAdapter log = Logging
+      .getLogger(getContext().getSystem(), getSelf());
+
+  final ActorRef connection;
+  final InetSocketAddress remote;
+
+  public static final long MAX_STORED = 100000000;
+  public static final long HIGH_WATERMARK = MAX_STORED * 5 / 10;
+  public static final long LOW_WATERMARK = MAX_STORED * 2 / 10;
+  
+  private long transferred;
+  private int storageOffset = 0;
+  private long stored = 0;
+  private Queue<ByteString> storage = new LinkedList<ByteString>();
+
+  private boolean suspended = false;
+  
+  private static class Ack implements Event {
+    public final int ack;
+    public Ack(int ack) {
+      this.ack = ack;
+    }
+  }
+
+  public EchoHandler(ActorRef connection, InetSocketAddress remote) {
+    this.connection = connection;
+    this.remote = remote;
+    
+    writing = writing();
+
+    // sign death pact: this actor stops when the connection is closed
+    getContext().watch(connection);
+
+    // start out in optimistic write-through mode
+    getContext().become(writing);
+  }
+  
+  @Override
+    public Receive createReceive() {
+      return writing;
+    }
+
+  private final Receive writing;
+  
+  private Receive writing() { 
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        final ByteString data = msg.data();
+        connection.tell(TcpMessage.write(data, new Ack(currentOffset())), getSelf());
+        buffer(data);
+
+      })
+      .match(Integer.class,  msg -> {
+        acknowledge(msg);
+      })
+      .match(CommandFailed.class, msg -> {
+        final Write w = (Write) msg.cmd();
+        connection.tell(TcpMessage.resumeWriting(), getSelf());
+        getContext().become(buffering((Ack) w.ack()));
+      })
+      .match(ConnectionClosed.class, msg -> {
+        if (msg.isPeerClosed()) {
+          if (storage.isEmpty()) {
+            getContext().stop(getSelf());
+          } else {
+            getContext().become(closing());
+          }
+        }
+      })
+      .build();
+  }
+
+  //#buffering
+  
+  final static class BufferingState {
+    int toAck = 10;
+    boolean peerClosed = false;
+  }
+  
+  protected Receive buffering(final Ack nack) {
+    final BufferingState state = new BufferingState();
+    
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        buffer(msg.data());
+
+      })
+      .match(WritingResumed.class, msg -> {
+        writeFirst();
+
+      })
+      .match(ConnectionClosed.class, msg -> {
+        if (msg.isPeerClosed())
+          state.peerClosed = true;
+        else
+          getContext().stop(getSelf());
+
+      })
+      .match(Integer.class, ack -> {
+        acknowledge(ack);
+
+        if (ack >= nack.ack) {
+          // otherwise it was the ack of the last successful write
+
+          if (storage.isEmpty()) {
+            if (state.peerClosed)
+              getContext().stop(getSelf());
+            else
+              getContext().become(writing);
+
+          } else {
+            if (state.toAck > 0) {
+              // stay in ACK-based mode for a short while
+              writeFirst();
+              --state.toAck;
+            } else {
+              // then return to NACK-based again
+              writeAll();
+              if (state.peerClosed)
+                getContext().become(closing());
+              else
+                getContext().become(writing);
+            }
+          }
+        }
+      })
+      .build();
+  }
+  //#buffering
+
+  //#closing
+  protected Receive closing() {
+    return receiveBuilder()
+      .match(CommandFailed.class, msg -> {
+        // the command can only have been a Write
+        connection.tell(TcpMessage.resumeWriting(), getSelf());
+        getContext().become(closeResend(), false);
+      })
+      .match(Integer.class, msg -> {  
+        acknowledge(msg);
+        if (storage.isEmpty())
+          getContext().stop(getSelf());
+      })
+      .build();
+  }
+
+  protected Receive closeResend() {
+    return receiveBuilder()
+      .match(WritingResumed.class, msg -> {
+        writeAll();
+        getContext().unbecome();
+      })
+      .match(Integer.class, msg -> {
+        acknowledge(msg);
+      })
+      .build();
+  }
+  //#closing
+
+  //#storage-omitted
+
+  @Override
+  public void postStop() {
+    log.info("transferred {} bytes from/to [{}]", transferred, remote);
+  }
+
+  //#helpers
+  protected void buffer(ByteString data) {
+    storage.add(data);
+    stored += data.size();
+
+    if (stored > MAX_STORED) {
+      log.warning("drop connection to [{}] (buffer overrun)", remote);
+      getContext().stop(getSelf());
+
+    } else if (stored > HIGH_WATERMARK) {
+      log.debug("suspending reading at {}", currentOffset());
+      connection.tell(TcpMessage.suspendReading(), getSelf());
+      suspended = true;
+    }
+  }
+
+  protected void acknowledge(int ack) {
+    assert ack == storageOffset;
+    assert !storage.isEmpty();
+
+    final ByteString acked = storage.remove();
+    stored -= acked.size();
+    transferred += acked.size();
+    storageOffset += 1;
+
+    if (suspended && stored < LOW_WATERMARK) {
+      log.debug("resuming reading");
+      connection.tell(TcpMessage.resumeReading(), getSelf());
+      suspended = false;
+    }
+  }
+  //#helpers
+
+  protected int currentOffset() {
+    return storageOffset + storage.size();
+  }
+
+  protected void writeAll() {
+    int i = 0;
+    for (ByteString data : storage) {
+      connection.tell(TcpMessage.write(data, new Ack(storageOffset + i++)), getSelf());
+    }
+  }
+
+  protected void writeFirst() {
+    connection.tell(TcpMessage.write(storage.peek(), new Ack(storageOffset)), getSelf());
+  }
+
+  //#storage-omitted
+}
+//#echo-handler

akka-docs/src/test/java/jdocs/io/japi/EchoManager.java

@@ -0,0 +1,81 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+import java.net.InetSocketAddress;
+
+import akka.actor.ActorRef;
+import akka.actor.Props;
+import akka.actor.SupervisorStrategy;
+import akka.actor.AbstractActor;
+import akka.event.Logging;
+import akka.event.LoggingAdapter;
+import akka.io.Tcp;
+import akka.io.Tcp.Bind;
+import akka.io.Tcp.Bound;
+import akka.io.Tcp.Connected;
+import akka.io.TcpMessage;
+
+public class EchoManager extends AbstractActor {
+
+  final LoggingAdapter log = Logging
+      .getLogger(getContext().getSystem(), getSelf());
+
+  final Class<?> handlerClass;
+
+  public EchoManager(Class<?> handlerClass) {
+    this.handlerClass = handlerClass;
+  }
+
+  @Override
+  public SupervisorStrategy supervisorStrategy() {
+    return SupervisorStrategy.stoppingStrategy();
+  }
+
+  @Override
+  public void preStart() throws Exception {
+    //#manager
+    final ActorRef tcpManager = Tcp.get(getContext().getSystem()).manager();
+    //#manager
+    tcpManager.tell(
+        TcpMessage.bind(getSelf(), new InetSocketAddress("localhost", 0), 100),
+       getSelf());
+  }
+
+  @Override
+  public void postRestart(Throwable arg0) throws Exception {
+    // do not restart
+    getContext().stop(getSelf());
+  }
+
+  @Override
+  public Receive createReceive() {
+    return receiveBuilder()
+      .match(Bound.class, msg -> {
+        log.info("listening on [{}]", msg.localAddress());
+      })
+      .match(Tcp.CommandFailed.class, failed -> {
+        if (failed.cmd() instanceof Bind) {
+          log.warning("cannot bind to [{}]", ((Bind) failed.cmd()).localAddress());
+          getContext().stop(getSelf());
+        } else {
+          log.warning("unknown command failed [{}]", failed.cmd());
+        }
+      })
+      .match(Connected.class, conn -> {
+        log.info("received connection from [{}]", conn.remoteAddress());
+        final ActorRef connection = getSender();
+        final ActorRef handler = getContext().actorOf(
+            Props.create(handlerClass, connection, conn.remoteAddress()));
+        //#echo-manager
+        connection.tell(TcpMessage.register(handler,
+            true, // <-- keepOpenOnPeerClosed flag
+            true), getSelf());
+        //#echo-manager
+      })
+      .build();
+  }
+
+}

akka-docs/src/test/java/jdocs/io/japi/EchoServer.java

@@ -0,0 +1,35 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+
+import com.typesafe.config.Config;
+import com.typesafe.config.ConfigFactory;
+
+public class EchoServer {
+
+  public static void main(String[] args) throws InterruptedException {
+    final Config config = ConfigFactory.parseString("akka.loglevel=DEBUG");
+    final ActorSystem system = ActorSystem.create("EchoServer", config);
+    try {
+      final CountDownLatch latch = new CountDownLatch(1);
+      final ActorRef watcher = system.actorOf(Props.create(Watcher.class, latch), "watcher");
+      final ActorRef nackServer = system.actorOf(Props.create(EchoManager.class, EchoHandler.class), "nack");
+      final ActorRef ackServer = system.actorOf(Props.create(EchoManager.class, SimpleEchoHandler.class), "ack");
+      watcher.tell(nackServer, ActorRef.noSender());
+      watcher.tell(ackServer, ActorRef.noSender());
+      latch.await(10, TimeUnit.MINUTES);
+    } finally {
+      system.terminate();
+    }
+  }
+
+}

akka-docs/src/test/java/jdocs/io/japi/IODocTest.java

@@ -0,0 +1,186 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+
+import akka.testkit.AkkaJUnitActorSystemResource;
+import jdocs.AbstractJavaTest;
+import akka.testkit.javadsl.TestKit;
+import org.junit.ClassRule;
+import org.junit.Test;
+
+//#imports
+import java.net.InetSocketAddress;
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+import akka.actor.AbstractActor;
+import akka.io.Tcp;
+import akka.io.Tcp.Bound;
+import akka.io.Tcp.CommandFailed;
+import akka.io.Tcp.Connected;
+import akka.io.Tcp.ConnectionClosed;
+import akka.io.Tcp.Received;
+import akka.io.TcpMessage;
+import akka.util.ByteString;
+//#imports
+
+import akka.testkit.AkkaSpec;
+
+public class IODocTest extends AbstractJavaTest {
+
+  static
+  //#server
+  public class Server extends AbstractActor {
+    
+    final ActorRef manager;
+    
+    public Server(ActorRef manager) {
+      this.manager = manager;
+    }
+    
+    public static Props props(ActorRef manager) {
+      return Props.create(Server.class, manager);
+    }
+
+    @Override
+    public void preStart() throws Exception {
+      final ActorRef tcp = Tcp.get(getContext().getSystem()).manager();
+      tcp.tell(TcpMessage.bind(getSelf(),
+          new InetSocketAddress("localhost", 0), 100), getSelf());
+    }
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .match(Bound.class, msg -> {
+          manager.tell(msg, getSelf());
+  
+        })
+        .match(CommandFailed.class, msg -> {
+          getContext().stop(getSelf());
+        
+        })
+        .match(Connected.class, conn -> {
+          manager.tell(conn, getSelf());
+          final ActorRef handler = getContext().actorOf(
+              Props.create(SimplisticHandler.class));
+          getSender().tell(TcpMessage.register(handler), getSelf());
+        })
+        .build();
+    }
+    
+  }
+  //#server
+
+  static
+  //#simplistic-handler
+  public class SimplisticHandler extends AbstractActor {
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .match(Received.class, msg -> {
+          final ByteString data = msg.data();
+          System.out.println(data);
+          getSender().tell(TcpMessage.write(data), getSelf());
+        })
+        .match(ConnectionClosed.class, msg -> {
+          getContext().stop(getSelf());
+        })
+        .build();
+    }
+  }
+  //#simplistic-handler
+  
+  static
+  //#client
+  public class Client extends AbstractActor {
+    
+    final InetSocketAddress remote;
+    final ActorRef listener;
+    
+    public static Props props(InetSocketAddress remote, ActorRef listener) {
+        return Props.create(Client.class, remote, listener);
+    }
+
+    public Client(InetSocketAddress remote, ActorRef listener) {
+      this.remote = remote;
+      this.listener = listener;
+      
+      final ActorRef tcp = Tcp.get(getContext().getSystem()).manager();
+      tcp.tell(TcpMessage.connect(remote), getSelf());
+    }
+
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .match(CommandFailed.class, msg -> {
+          listener.tell("failed", getSelf());
+          getContext().stop(getSelf());
+          
+        })
+        .match(Connected.class, msg -> {
+          listener.tell(msg, getSelf());
+          getSender().tell(TcpMessage.register(getSelf()), getSelf());
+          getContext().become(connected(getSender()));
+        })
+        .build();
+    }
+
+    private Receive connected(final ActorRef connection) {
+      return receiveBuilder()
+        .match(ByteString.class, msg -> {
+            connection.tell(TcpMessage.write((ByteString) msg), getSelf());
+        })
+        .match(CommandFailed.class, msg -> {
+          // OS kernel socket buffer was full
+        })
+        .match(Received.class, msg -> {
+          listener.tell(msg.data(), getSelf());
+        })
+        .matchEquals("close", msg -> {
+          connection.tell(TcpMessage.close(), getSelf());
+        })
+        .match(ConnectionClosed.class, msg -> {
+          getContext().stop(getSelf());
+        })
+        .build();
+    }
+    
+  }
+  //#client
+
+  @ClassRule
+  public static AkkaJUnitActorSystemResource actorSystemResource =
+    new AkkaJUnitActorSystemResource("IODocTest", AkkaSpec.testConf());
+
+  private final ActorSystem system = actorSystemResource.getSystem();
+
+  @Test
+  public void testConnection() {
+    new TestKit(system) {
+      {
+        @SuppressWarnings("unused")
+        final ActorRef server = system.actorOf(Server.props(getRef()), "server1");
+        final InetSocketAddress listen = expectMsgClass(Bound.class).localAddress();
+        final ActorRef client = system.actorOf(Client.props(listen, getRef()), "client1");
+        
+        final Connected c1 = expectMsgClass(Connected.class);
+        final Connected c2 = expectMsgClass(Connected.class);
+        assert c1.localAddress().equals(c2.remoteAddress());
+        assert c2.localAddress().equals(c1.remoteAddress());
+        
+        client.tell(ByteString.fromString("hello"), getRef());
+        final ByteString reply = expectMsgClass(ByteString.class);
+        assert reply.utf8String().equals("hello");
+        
+        watch(client);
+        client.tell("close", getRef());
+        expectTerminated(client);
+      }
+    };
+  }
+
+}

akka-docs/src/test/java/jdocs/io/japi/Message.java

@@ -0,0 +1,45 @@
+/**
+ * Copyright (C) 2013-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+//#message
+public class Message {
+  
+  static public class Person {
+    private final String first;
+    private final String last;
+
+    public Person(String first, String last) {
+      this.first = first;
+      this.last = last;
+    }
+
+    public String getFirst() {
+      return first;
+    }
+
+    public String getLast() {
+      return last;
+    }
+
+  }
+
+  private final Person[] persons;
+  private final double[] happinessCurve;
+
+  public Message(Person[] persons, double[] happinessCurve) {
+    this.persons = persons;
+    this.happinessCurve = happinessCurve;
+  }
+
+  public Person[] getPersons() {
+    return persons;
+  }
+
+  public double[] getHappinessCurve() {
+    return happinessCurve;
+  }
+}
+//#message

akka-docs/src/test/java/jdocs/io/japi/SimpleEchoHandler.java

@@ -0,0 +1,134 @@
+/**
+ * Copyright (C) 2009-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package jdocs.io.japi;
+
+import java.net.InetSocketAddress;
+import java.util.LinkedList;
+import java.util.Queue;
+
+import akka.actor.ActorRef;
+import akka.actor.AbstractActor;
+import akka.event.Logging;
+import akka.event.LoggingAdapter;
+import akka.io.Tcp.ConnectionClosed;
+import akka.io.Tcp.Event;
+import akka.io.Tcp.Received;
+import akka.io.TcpMessage;
+import akka.util.ByteString;
+
+//#simple-echo-handler
+public class SimpleEchoHandler extends AbstractActor {
+  
+  final LoggingAdapter log = Logging
+      .getLogger(getContext().getSystem(), getSelf());
+
+  final ActorRef connection;
+  final InetSocketAddress remote;
+
+  public static final long maxStored = 100000000;
+  public static final long highWatermark = maxStored * 5 / 10;
+  public static final long lowWatermark = maxStored * 2 / 10;
+
+  public SimpleEchoHandler(ActorRef connection, InetSocketAddress remote) {
+    this.connection = connection;
+    this.remote = remote;
+
+    // sign death pact: this actor stops when the connection is closed
+    getContext().watch(connection);
+  }
+
+  @Override
+  public Receive createReceive() {
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        final ByteString data = msg.data();
+        buffer(data);
+        connection.tell(TcpMessage.write(data, ACK), getSelf());
+        // now switch behavior to “waiting for acknowledgement”
+        getContext().become(buffering(), false);
+  
+      })
+      .match(ConnectionClosed.class, msg -> {
+        getContext().stop(getSelf());
+      })
+      .build();
+  }
+
+  private final Receive buffering() {
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        buffer(msg.data());
+        
+      })
+      .match(Event.class, msg -> msg == ACK, msg -> {
+        acknowledge();
+
+      })
+      .match(ConnectionClosed.class, msg -> {
+        if (msg.isPeerClosed()) {
+          closing = true;
+        } else {
+          // could also be ErrorClosed, in which case we just give up
+          getContext().stop(getSelf());
+        }
+      })
+      .build();
+  }
+
+  //#storage-omitted
+  public void postStop() {
+    log.info("transferred {} bytes from/to [{}]", transferred, remote);
+  }
+
+  private long transferred;
+  private long stored = 0;
+  private Queue<ByteString> storage = new LinkedList<ByteString>();
+
+  private boolean suspended = false;
+  private boolean closing = false;
+  
+  private final Event ACK = new Event() {};
+
+  //#simple-helpers
+  protected void buffer(ByteString data) {
+    storage.add(data);
+    stored += data.size();
+
+    if (stored > maxStored) {
+      log.warning("drop connection to [{}] (buffer overrun)", remote);
+      getContext().stop(getSelf());
+
+    } else if (stored > highWatermark) {
+      log.debug("suspending reading");
+      connection.tell(TcpMessage.suspendReading(), getSelf());
+      suspended = true;
+    }
+  }
+
+  protected void acknowledge() {
+    final ByteString acked = storage.remove();
+    stored -= acked.size();
+    transferred += acked.size();
+
+    if (suspended && stored < lowWatermark) {
+      log.debug("resuming reading");
+      connection.tell(TcpMessage.resumeReading(), getSelf());
+      suspended = false;
+    }
+    
+    if (storage.isEmpty()) {
+      if (closing) {
+        getContext().stop(getSelf());
+      } else {
+        getContext().unbecome();
+      }
+    } else {
+      connection.tell(TcpMessage.write(storage.peek(), ACK), getSelf());
+    }
+  }
+  //#simple-helpers
+  //#storage-omitted
+}
+//#simple-echo-handler

akka-docs/src/test/java/jdocs/io/japi/Watcher.java

@@ -0,0 +1,37 @@
+package jdocs.io.japi;
+
+import java.util.concurrent.CountDownLatch;
+
+import akka.actor.ActorRef;
+import akka.actor.Terminated;
+import akka.actor.AbstractActor;
+
+public class Watcher extends AbstractActor {
+  
+  static public class Watch {
+    final ActorRef target;
+    public Watch(ActorRef target) {
+      this.target = target;
+    }
+  }
+  
+  final CountDownLatch latch;
+
+  public Watcher(CountDownLatch latch) {
+    this.latch = latch;
+  }
+
+  @Override
+  public Receive createReceive() {
+    return receiveBuilder()
+      .match(Watch.class, msg -> {
+        getContext().watch(msg.target);
+      })
+      .match(Terminated.class, msg -> {
+        latch.countDown();
+        if (latch.getCount() == 0) getContext().stop(getSelf());
+      })
+      .build();
+  }
+
+}