=doc #3639 Show complete custom mailbox example.

akka-docs/rst/java/code/docs/dispatcher/DispatcherDocTest.java

@@ -3,6 +3,15 @@
  */
 package docs.dispatcher;
 
+import akka.dispatch.RequiresMessageQueue;
+import akka.testkit.AkkaSpec;
+import com.typesafe.config.ConfigFactory;
+import docs.actor.MyBoundedUntypedActor;
+import docs.actor.MyUntypedActor;
+import org.junit.ClassRule;
+import org.junit.Test;
+import scala.concurrent.ExecutionContext;
+
 //#imports
 import akka.actor.*;
 //#imports
@@ -18,35 +27,14 @@ import akka.dispatch.PriorityGenerator;
 import akka.dispatch.UnboundedPriorityMailbox;
 import akka.testkit.AkkaJUnitActorSystemResource;
 import akka.testkit.JavaTestKit;
-import akka.testkit.TestKit;
 import com.typesafe.config.Config;
 
 //#imports-prio-mailbox
 
-//#imports-custom
-import akka.dispatch.Envelope;
-import akka.dispatch.MessageQueue;
-import akka.dispatch.MailboxType;
-import java.util.Queue;
-import java.util.concurrent.ConcurrentLinkedQueue;
-
-//#imports-custom
-
 //#imports-required-mailbox
 
 //#imports-required-mailbox
 
-import docs.actor.MyBoundedUntypedActor;
-import org.junit.ClassRule;
-import org.junit.Test;
-import scala.Option;
-import scala.concurrent.ExecutionContext;
-
-import com.typesafe.config.ConfigFactory;
-
-import docs.actor.MyUntypedActor;
-import akka.testkit.AkkaSpec;
-
 public class DispatcherDocTest {
 
   @ClassRule
@@ -185,34 +173,29 @@ public class DispatcherDocTest {
   }
   //#prio-mailbox
 
-  static
-  //#mailbox-implementation-example
-  public class MyUnboundedMailbox implements MailboxType {
-
-    // This constructor signature must exist, it will be called by Akka
-    public MyUnboundedMailbox(ActorSystem.Settings settings, Config config) {
-      // put your initialization code here
-    }
-
-    // The create method is called to create the MessageQueue
-    public MessageQueue create(Option<ActorRef> owner, Option<ActorSystem> system) {
-      return new MessageQueue() {
-        private final Queue<Envelope> queue = new ConcurrentLinkedQueue<Envelope>();
-        
-        // these must be implemented; queue used as example
-        public void enqueue(ActorRef receiver, Envelope handle) {
-          queue.offer(handle);
-        }
-        public Envelope dequeue() { return queue.poll(); }
-        public int numberOfMessages() { return queue.size(); }
-        public boolean hasMessages() { return !queue.isEmpty(); }
-        public void cleanUp(ActorRef owner, MessageQueue deadLetters) {
-          for (Envelope handle: queue) {
-            deadLetters.enqueue(owner, handle);
-          }
-        }
-      };
-    }
+  @Test
+  public void requiredMailboxDispatcher() throws Exception {
+    ActorRef myActor = system.actorOf(Props.create(MyUntypedActor.class)
+      .withDispatcher("custom-dispatcher"));
   }
-  //#mailbox-implementation-example
+
+  static
+  //#require-mailbox-on-actor
+  public class MySpecialActor extends UntypedActor implements
+    RequiresMessageQueue<MyUnboundedJMessageQueueSemantics> {
+    //#require-mailbox-on-actor
+    @Override
+    public void onReceive(Object message) throws Exception {
+      unhandled(message);
+    }
+    //#require-mailbox-on-actor
+    // ...
+  }
+  //#require-mailbox-on-actor
+
+  @Test
+  public void requiredMailboxActor() throws Exception {
+    ActorRef myActor = system.actorOf(Props.create(MySpecialActor.class));
+  }
+
 }

akka-docs/rst/java/code/docs/dispatcher/MyUnboundedJMailbox.java

@@ -0,0 +1,51 @@
+/**
+ * Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.dispatcher;
+
+//#mailbox-implementation-example
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.dispatch.Envelope;
+import akka.dispatch.MailboxType;
+import akka.dispatch.MessageQueue;
+import akka.dispatch.ProducesMessageQueue;
+import com.typesafe.config.Config;
+import java.util.concurrent.ConcurrentLinkedQueue;
+import java.util.Queue;
+import scala.Option;
+
+public class MyUnboundedJMailbox implements MailboxType,
+  ProducesMessageQueue<MyUnboundedJMailbox.MyMessageQueue> {
+
+  // This is the MessageQueue implementation
+  public static class MyMessageQueue implements MessageQueue,
+    MyUnboundedJMessageQueueSemantics {
+    private final Queue<Envelope> queue =
+      new ConcurrentLinkedQueue<Envelope>();
+
+    // these must be implemented; queue used as example
+    public void enqueue(ActorRef receiver, Envelope handle) {
+      queue.offer(handle);
+    }
+    public Envelope dequeue() { return queue.poll(); }
+    public int numberOfMessages() { return queue.size(); }
+    public boolean hasMessages() { return !queue.isEmpty(); }
+    public void cleanUp(ActorRef owner, MessageQueue deadLetters) {
+      for (Envelope handle: queue) {
+        deadLetters.enqueue(owner, handle);
+      }
+    }
+  }
+
+  // This constructor signature must exist, it will be called by Akka
+  public MyUnboundedJMailbox(ActorSystem.Settings settings, Config config) {
+    // put your initialization code here
+  }
+
+  // The create method is called to create the MessageQueue
+  public MessageQueue create(Option<ActorRef> owner, Option<ActorSystem> system) {
+    return new MyMessageQueue();
+  }
+}
+//#mailbox-implementation-example

akka-docs/rst/java/code/docs/dispatcher/MyUnboundedJMessageQueueSemantics.java

@@ -0,0 +1,11 @@
+/**
+ * Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.dispatcher;
+
+//#mailbox-implementation-example
+// Marker interface used for mailbox requirements mapping
+public interface MyUnboundedJMessageQueueSemantics {
+}
+//#mailbox-implementation-example