=doc #3685 Add FAQ to documentation

* The links at http://akka.io will changed to point at this faq
* Some rewording of guarantees/reliability

akka-docs/rst/additional/code/docs/faq/Faq.scala

@@ -0,0 +1,27 @@
+package docs.faq
+
+import akka.actor.Actor
+
+//#exhaustiveness-check
+object MyActor {
+  // these are the messages we accept
+  sealed abstract trait Message
+  case class FooMessage(foo: String) extends Message
+  case class BarMessage(bar: Int) extends Message
+
+  // these are the replies we send
+  sealed abstract trait Reply
+  case class BazMessage(baz: String) extends Reply
+}
+
+class MyActor extends Actor {
+  import MyActor._
+  def receive = {
+    case message: Message ⇒ message match {
+      case BarMessage(bar) => sender ! BazMessage("Got " + bar)
+      // warning here: 
+      // "match may not be exhaustive. It would fail on the following input: FooMessage(_)"
+    }
+  }
+}
+//#exhaustiveness-check

akka-docs/rst/additional/faq.rst

@@ -0,0 +1,160 @@
+Frequently Asked Questions
+==========================
+
+Akka Project
+^^^^^^^^^^^^
+
+Where does the name Akka come from?
+-----------------------------------
+
+It is the name of a beautiful Swedish `mountain <https://lh4.googleusercontent.com/-z28mTALX90E/UCOsd249TdI/AAAAAAAAAB0/zGyNNZla-zY/w442-h331/akka-beautiful-panorama.jpg>`_
+up in the northern part of Sweden called Laponia. The mountain is also sometimes
+called 'The Queen of Laponia'.
+
+Akka is also the name of a goddess in the Sámi (the native Swedish population)
+mythology. She is the goddess that stands for all the beauty and good in the
+world. The mountain can be seen as the symbol of this goddess.
+
+Also, the name AKKA is the a palindrome of letters A and K as in Actor Kernel.
+
+Akka is also:
+
+* the name of the goose that Nils traveled across Sweden on in `The Wonderful Adventures of Nils <http://en.wikipedia.org/wiki/The_Wonderful_Adventures_of_Nils>`_ by the Swedish writer Selma Lagerlöf.
+* the Finnish word for 'nasty elderly woman' and the word for 'elder sister' in the Indian languages Tamil, Telugu, Kannada and Marathi.
+* a `font <http://www.dafont.com/akka.font>`_
+* a town in Morocco
+* a near-earth asteroid
+
+Actors in General
+^^^^^^^^^^^^^^^^^
+
+sender()/getSender() disappears when I use Future in my Actor, why?
+-------------------------------------------------------------------
+
+When using future callbacks, inside actors you need to carefully avoid closing over
+the containing actor’s reference, i.e. do not call methods or access mutable state
+on the enclosing actor from within the callback. This breaks the actor encapsulation
+and may introduce synchronization bugs and race conditions because the callback will
+be scheduled concurrently to the enclosing actor. Unfortunately there is not yet a way
+to detect these illegal accesses at compile time.
+
+Read more about it in the docs for :ref:`jmm-shared-state`.
+
+Why OutOfMemoryError?
+---------------------
+
+It can be many reasons for OutOfMemoryError. For example, in a pure push based system with
+message consumers that are potentially slower than corresponding message producers you must
+add some kind of message flow control. Otherwise messages will be queued in the consumers'
+mailboxes and thereby filling up the heap memory.
+
+Some articles for inspiration:
+
+* `Balancing Workload across Nodes with Akka 2 <http://letitcrash.com/post/29044669086/balancing-workload-across-nodes-with-akka-2>`_.
+* `Work Pulling Pattern to prevent mailbox overflow, throttle and distribute work <http://www.michaelpollmeier.com/akka-work-pulling-pattern/>`_
+
+Actors Scala API
+^^^^^^^^^^^^^^^^
+
+How can I get compile time errors for missing messages in `receive`?
+--------------------------------------------------------------------
+
+One solution to help you get a compile time warning for not handling a message
+that you should be handling is to define your actors input and output messages
+implementing base traits, and then do a match that the will be checked for
+exhaustiveness.
+
+Here is an example where the compiler will warn you that the match in
+receive isn't exhaustive:
+
+.. includecode:: code/docs/faq/Faq.scala#exhaustiveness-check
+
+Remoting
+^^^^^^^^
+
+I want to send to a remote system but it does not do anything
+-------------------------------------------------------------
+
+Make sure that you have remoting enabled on both ends: client and server. Both
+do need hostname and port configured, and you will need to know the port of the
+server; the client can use an automatic port in most cases (i.e. configure port
+zero). If both systems are running on the same network host, their ports must
+be different
+
+If you still do not see anything, look at what the logging of remote
+life-cycle events tells you (normally logged at INFO level) or switch on 
+:ref:`logging-remote-java`
+to see all sent and received messages (logged at DEBUG level).
+
+Which options shall I enable when debugging remoting issues?
+------------------------------------------------------------
+
+Have a look at the :ref:`remote-configuration-java`, the typical candidates are:
+
+* `akka.remote.log-sent-messages`
+* `akka.remote.log-received-messages`
+* `akka.remote.log-remote-lifecycle-events` (this also includes deserialization errors)
+
+What is the name of a remote actor?
+-----------------------------------
+
+When you want to send messages to an actor on a remote host, you need to know
+its :ref:`full path <addressing>`, which is of the form::
+
+    akka.protocol://system@host:1234/user/my/actor/hierarchy/path
+
+Observe all the parts you need here:
+
+* ``protocol`` is the protocol to be used to communicate with the remote system. 
+   Most of the cases this is `tcp`.
+
+* ``system`` is the remote system’s name (must match exactly, case-sensitive!)
+
+* ``host`` is the remote system’s IP address or DNS name, and it must match that
+  system’s configuration (i.e. `akka.remote.netty.hostname`)
+
+* ``1234`` is the port number on which the remote system is listening for
+  connections and receiving messages
+
+* ``/user/my/actor/hierarchy/path`` is the absolute path of the remote actor in
+  the remote system’s supervision hierarchy, including the system’s guardian
+  (i.e. ``/user``, there are others e.g. ``/system`` which hosts loggers, ``/temp``
+  which keeps temporary actor refs used with `ask()`, `/remote` which enables
+  remote deployment, etc.); this matches how the actor prints its own ``self``
+  reference on the remote host, e.g. in log output.
+
+Why are replies not received from a remote actor?
+-------------------------------------------------
+
+The most common reason is that the local system’s name (i.e. the
+``system@host:1234`` part in the answer above) is not reachable from the remote
+system’s network location, e.g. because ``host`` was configured to be ``0.0.0.0``,
+``localhost`` or a NAT’ed IP address.
+
+How reliable is the message delivery?
+-------------------------------------
+
+The general rule is **at-most-once delivery**, i.e. no guaranteed delivery.
+Stronger reliability can be built on top, and Akka provides tools to do so.
+
+Read more in :ref:`message-delivery-reliability`.
+
+Debugging
+^^^^^^^^^
+
+How do I turn on debug logging?
+-------------------------------
+
+To turn on debug logging in your actor system add the following to your configuration::
+
+    akka.loglevel = DEBUG  
+
+To enable different types of debug logging add the following to your configuration:
+
+* ``akka.actor.debug.receive`` will log all messages sent to an actor if that actors `receive` method is a ``LoggingReceive``
+
+* ``akka.actor.debug.autoreceive`` will log all *special* messages like ``Kill``, ``PoisonPill`` e.t.c. sent to all actors
+
+* ``akka.actor.debug.lifecycle`` will log all actor lifecycle events of all actors
+
+Read more about it in the docs for :ref:`logging-java` and :ref:`actor.logging-scala`.

akka-docs/rst/additional/index.rst

@@ -4,6 +4,7 @@ Additional Information
 .. toctree::
    :maxdepth: 2
 
+   faq
    books
    recipes
    language-bindings

akka-docs/rst/additional/osgi.rst

@@ -14,7 +14,7 @@ Activator
 To bootstrap Akka inside an OSGi environment, you can use the ``akka.osgi.ActorSystemActivator`` class
 to conveniently set up the ActorSystem.
 
-.. includecode:: code/osgi/Activator.scala#Activator
+.. includecode:: code/docs/osgi/Activator.scala#Activator
 
 
 The ``ActorSystemActivator`` creates the actor system with a class loader that finds resources

akka-docs/rst/general/index.rst

@@ -11,5 +11,5 @@ General
    addressing
    remoting
    jmm
-   message-delivery-guarantees
+   message-delivery-reliability
    configuration

akka-docs/rst/general/message-delivery-reliability.rst

@@ -1,8 +1,8 @@
-.. _message-delivery-guarantees:
+.. _message-delivery-reliability:
 
-###########################
-Message Delivery Guarantees
-###########################
+############################
+Message Delivery Reliability
+############################
 
 Akka helps you build reliable applications which make use of multiple processor
 cores in one machine (“scaling up”) or distributed across a computer network
@@ -31,7 +31,7 @@ actors—you can place them always on the same JVM and enjoy stricter guarantees
 on message delivery. The details of this trade-off are discussed further below.
 
 As a supplementary part we give a few pointers at how to build stronger
-guarantees on top of the built-in ones. The chapter closes by discussing the
+reliability on top of the built-in ones. The chapter closes by discussing the
 role of the “Dead Letter Office”.
 
 The General Rules
@@ -106,9 +106,9 @@ read more about this approach in the `Erlang documentation`_ (section 10.9 and
 10.10), Akka follows it closely.
 
 Another angle on this issue is that by providing only basic guarantees those
-use cases which do not need stricter guarantees do not pay the cost of their
-implementation; it is always possible to add stricter guarantees on top of
-basic ones, but it is not possible to retro-actively remove guarantees in order
+use cases which do not need stronger reliability do not pay the cost of their
+implementation; it is always possible to add stronger reliability on top of
+basic ones, but it is not possible to retro-actively remove reliability in order
 to gain more performance.
 
 .. _message-ordering:
@@ -188,7 +188,7 @@ The Rules for In-JVM (Local) Message Sends
 Be careful what you do with this section!
 -----------------------------------------
 
-Relying on the stronger guarantees in this section is not recommended since it
+Relying on the stronger reliability in this section is not recommended since it
 will bind your application to local-only deployment: an application may have to
 be designed differently (as opposed to just employing some message exchange
 patterns local to some actors) in order to be fit for running on a cluster of
@@ -277,7 +277,7 @@ powerful, higher-level abstractions on top it.
 Messaging Patterns
 ------------------
 
-As discussed above a straight-forward answer to the requirement of guaranteed
+As discussed above a straight-forward answer to the requirement of reliable
 delivery is an explicit ACK–RETRY protocol. In its simplest form this requires
 
 - a way to identify individual messages to correlate message with

akka-docs/rst/general/terminology.rst

@@ -73,7 +73,7 @@ this can cause race conditions.
 
 .. note::
   The only guarantee that Akka provides about messages sent between a given pair of actors is that their order is
-  always preserved. see :ref:`message-delivery-guarantees`
+  always preserved. see :ref:`message-delivery-reliability`
 
 Non-blocking Guarantees (Progress Conditions)
 ---------------------------------------------

akka-docs/rst/java/logging.rst

@@ -149,6 +149,8 @@ If you want to monitor subscriptions (subscribe/unsubscribe) on the ActorSystem.
       }
     }
 
+.. _logging-remote-java:
+
 Auxiliary remote logging options
 --------------------------------