Document router handling of PoisonPill messages. Fixes #2874

Ready for review now. I will create a ticket to document the receiveN method I added to the JavaTestKit.