+act #15163 allows to suppress certain messages from being dead-letter-ed

Conflicts:
	akka-actor/src/main/scala/akka/actor/ActorRef.scala

akka-docs/rst/java/code/docs/event/LoggingDocTest.java

@@ -4,6 +4,10 @@
 package docs.event;
 
 //#imports
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.actor.AllDeadLetters;
+import akka.actor.SuppressedDeadLetter;
 import akka.event.Logging;
 import akka.event.LoggingAdapter;
 
@@ -64,7 +68,30 @@ public class LoggingDocTest {
     //#deadletters
     JavaTestKit.shutdownActorSystem(system);
   }
-  
+
+  @Test
+  public void subscribeToSuppressedDeadLetters() {
+    final ActorSystem system = ActorSystem.create("SuppressedDeadLetters");
+    final ActorRef actor = system.actorOf(Props.create(DeadLetterActor.class));
+    
+    //#suppressed-deadletters
+    system.eventStream().subscribe(actor, SuppressedDeadLetter.class);
+    //#suppressed-deadletters
+
+    JavaTestKit.shutdownActorSystem(system);
+  }
+  @Test
+  public void subscribeToAllDeadLetters() {
+    final ActorSystem system = ActorSystem.create("AllDeadLetters");
+    final ActorRef actor = system.actorOf(Props.create(DeadLetterActor.class));
+
+    //#all-deadletters
+    system.eventStream().subscribe(actor, AllDeadLetters.class);
+    //#all-deadletters
+
+    JavaTestKit.shutdownActorSystem(system);
+  }
+
   @Test
   public void demonstrateMultipleArgs() {
     final ActorSystem system = ActorSystem.create("multiArg");

akka-docs/rst/java/event-bus.rst

@@ -187,6 +187,19 @@ which by default will publish the messages wrapped in :class:`DeadLetter`. This
 wrapper holds the original sender, receiver and message of the envelope which
 was redirected.
 
+Some internal messages (marked with the :class:`DeadLetterSuppression` trait) will not end up as
+dead letters like normal messages. These are by design safe and expected to sometimes arrive at a terminated actor
+and since they are nothing to worry about, they are suppressed from the default dead letters logging mechanism.
+
+However, in case you find yourself in need of debugging these kinds of low level suppressed dead letters,
+it's still possible to subscribe to them explicitly:
+
+.. includecode:: code/docs/event/LoggingDocTest.java#suppressed-deadletters
+
+or all dead letters (including the suppressed ones):
+
+.. includecode:: code/docs/event/LoggingDocTest.java#all-deadletters
+
 Other Uses
 ----------
 

akka-docs/rst/scala/code/docs/event/LoggingDocSpec.scala

@@ -3,6 +3,7 @@
  */
 package docs.event
 
+import akka.actor.AllDeadLetters
 import akka.testkit.AkkaSpec
 import akka.actor.Actor
 import akka.actor.Props
@@ -149,6 +150,23 @@ class LoggingDocSpec extends AkkaSpec {
     }
   }
 
+  "allow registration to suppressed dead letters" in {
+    new AnyRef {
+      import akka.actor.Props
+      val listener = system.actorOf(Props[MyActor])
+
+      //#suppressed-deadletters
+      import akka.actor.SuppressedDeadLetter
+      system.eventStream.subscribe(listener, classOf[SuppressedDeadLetter])
+      //#suppressed-deadletters
+
+      //#all-deadletters
+      import akka.actor.AllDeadLetters
+      system.eventStream.subscribe(listener, classOf[AllDeadLetters])
+      //#all-deadletters
+    }
+  }
+
   "demonstrate logging more arguments" in {
     //#array
     val args = Array("The", "brown", "fox", "jumps", 42)

akka-docs/rst/scala/event-bus.rst

@@ -182,6 +182,19 @@ which by default will publish the messages wrapped in :class:`DeadLetter`. This
 wrapper holds the original sender, receiver and message of the envelope which
 was redirected.
 
+Some internal messages (marked with the :class:`DeadLetterSuppression` trait) will not end up as
+dead letters like normal messages. These are by design safe and expected to sometimes arrive at a terminated actor
+and since they are nothing to worry about, they are suppressed from the default dead letters logging mechanism.
+
+However, in case you find yourself in need of debugging these kinds of low level suppressed dead letters,
+it's still possible to subscribe to them explicitly:
+
+.. includecode:: code/docs/event/LoggingDocSpec.scala#suppressed-deadletters
+
+or all dead letters (including the suppressed ones):
+
+.. includecode:: code/docs/event/LoggingDocSpec.scala#all-deadletters
+
 Other Uses
 ----------