Merge pull request #910 from akka/wip-docs-∂π

Wip docs ∂π

akka-docs/rst/java/code/docs/serialization/SerializationDocTestBase.java

@@ -138,12 +138,7 @@ public class SerializationDocTestBase {
     }
 
     public Address getAddress() {
-      final ActorRefProvider provider = system.provider();
+      return system.provider().getDefaultAddress();
-      if (provider instanceof RemoteActorRefProvider) {
-        return ((RemoteActorRefProvider) provider).transport().address();
-      } else {
-        throw new UnsupportedOperationException("need RemoteActorRefProvider");
-      }
     }
   }
 

akka-docs/rst/java/serialization.rst

@@ -149,16 +149,12 @@ concrete address handy you can create a dummy one for the right protocol using
 ``new Address(protocol, "", "", 0)`` (assuming that the actual transport used is as
 lenient as Akka’s RemoteActorRefProvider).
 
-There is a possible simplification available if you are just using the default
+There is also a default remote address which is the one used by cluster support
-:class:`NettyRemoteTransport` with the :meth:`RemoteActorRefProvider`, which is
+(and typical systems have just this one); you can get it like this:
-enabled by the fact that this combination has just a single remote address:
 
 .. includecode:: code/docs/serialization/SerializationDocTestBase.java
    :include: external-address-default
 
-This solution has to be adapted once other providers are used (like the planned
-extensions for clustering).
-
 Deep serialization of Actors
 ----------------------------
 

akka-docs/rst/scala/code/docs/actor/FSMDocSpec.scala

@@ -189,6 +189,15 @@ class FSMDocSpec extends MyFavoriteTestFrameWorkPlusAkkaTestKit {
     }
     //#fsm-code-elided
 
+    "demonstrate NullFunction" in {
+      class A extends Actor with FSM[Int, Null] {
+        val SomeState = 0
+        //#NullFunction
+        when(SomeState)(FSM.NullFunction)
+        //#NullFunction
+      }
+    }
+
     "batch correctly" in {
       val buncher = system.actorOf(Props(new Buncher))
       buncher ! SetTarget(testActor)

akka-docs/rst/scala/code/docs/serialization/SerializationDocSpec.scala

@@ -2,19 +2,6 @@
  * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
  */
 
-//#extract-transport
-package object akka {
-  // needs to be inside the akka package because accessing unsupported API !
-  def transportOf(system: actor.ExtendedActorSystem): remote.RemoteTransport =
-    system.provider match {
-      case r: remote.RemoteActorRefProvider ⇒ r.transport
-      case _ ⇒
-        throw new UnsupportedOperationException(
-          "this method requires the RemoteActorRefProvider to be configured")
-    }
-}
-//#extract-transport
-
 package docs.serialization {
 
   import org.scalatest.matchers.MustMatchers
@@ -216,7 +203,7 @@ package docs.serialization {
       object ExternalAddress extends ExtensionKey[ExternalAddressExt]
 
       class ExternalAddressExt(system: ExtendedActorSystem) extends Extension {
-        def addressForAkka: Address = akka.transportOf(system).address
+        def addressForAkka: Address = system.provider.getDefaultAddress
       }
 
       def serializeAkkaDefault(ref: ActorRef): String =

akka-docs/rst/scala/fsm.rst

@@ -179,6 +179,18 @@ demonstrated below:
 The :class:`Event(msg: Any, data: D)` case class is parameterized with the data
 type held by the FSM for convenient pattern matching.
 
+.. warning::
+
+  It is required that you define handlers for each of the possible FSM states,
+  otherwise there will be failures when trying to switch to undeclared states.
+
+It is recommended practice to declare the states as objects extending a
+sealed trait and then verify that there is a ``when`` clause for each of the
+states. If you want to leave the handling of a state “unhandled” (more below),
+it still needs to be declared like this:
+
+.. includecode:: code/docs/actor/FSMDocSpec.scala#NullFunction
+
 Defining the Initial State
 --------------------------
 

akka-docs/rst/scala/serialization.rst

@@ -138,24 +138,12 @@ concrete address handy you can create a dummy one for the right protocol using
 ``Address(protocol, "", "", 0)`` (assuming that the actual transport used is as
 lenient as Akka’s RemoteActorRefProvider).
 
-There is a possible simplification available if you are just using the default
+There is also a default remote address which is the one used by cluster support
-:class:`NettyRemoteTransport` with the :meth:`RemoteActorRefProvider`, which is
+(and typical systems have just this one); you can get it like this:
-enabled by the fact that this combination has just a single remote address.
-This approach relies on internal API, which means that it is not guaranteed to
-be supported in future versions. To make this caveat more obvious, some bridge
-code in the ``akka`` package is required to make it work:
-
-.. includecode:: code/docs/serialization/SerializationDocSpec.scala
-   :include: extract-transport
-
-And with this, the address extraction goes like this:
 
 .. includecode:: code/docs/serialization/SerializationDocSpec.scala
    :include: external-address-default
 
-This solution has to be adapted once other providers are used (like the planned
-extensions for clustering).
-
 Deep serialization of Actors
 ----------------------------
 

akka-remote/src/main/resources/reference.conf

@@ -109,6 +109,11 @@ akka {
       # (I) EXPERIMENTAL If "<id.of.dispatcher>" then the specified dispatcher
       # will be used to accept inbound connections, and perform IO. If "" then
       # dedicated threads will be used.
+      #
+      # CAUTION: This might lead to the used dispatcher not shutting down properly!
+      #          - may prevent the JVM from shutting down normally
+      #          - may leak threads when shutting down an ActorSystem
+      #
       use-dispatcher-for-io = ""
 
       # (I) The hostname or ip to bind the remoting to,