document Specs2 + TestKit, see #2068, plus fix up broken includes
- include move of doc samples out of akka package also in the includecode directives - fix broken serialization docs, which require one thing in the akka package
This commit is contained in:
Roland
parent
7d342e5c96
commit
dd30e81a1a
44 changed files with 681 additions and 555 deletions
|
|
@ -40,17 +40,17 @@ application. An ``ActorSystem`` is required to create the underlying Actors. See
|
|||
|
||||
Here is an example of creating an Agent:
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java
|
||||
:include: import-system,import-agent
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#create
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#create
|
||||
:language: java
|
||||
|
||||
An Agent will be running until you invoke ``close`` on it. Then it will be
|
||||
eligible for garbage collection (unless you hold on to it in some way).
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#close
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#close
|
||||
:language: java
|
||||
|
||||
|
||||
|
|
@ -65,10 +65,10 @@ the update will be applied but dispatches to an Agent from a single thread will
|
|||
occur in order. You apply a value or a function by invoking the ``send``
|
||||
function.
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#import-function
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#import-function
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#send
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#send
|
||||
:language: java
|
||||
|
||||
You can also dispatch a function to update the internal state but on its own
|
||||
|
|
@ -77,7 +77,7 @@ long-running or blocking operations. You do this with the ``sendOff``
|
|||
method. Dispatches using either ``sendOff`` or ``send`` will still be executed
|
||||
in order.
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#send-off
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#send-off
|
||||
:language: java
|
||||
|
||||
|
||||
|
|
@ -87,7 +87,7 @@ Reading an Agent's value
|
|||
Agents can be dereferenced (you can get an Agent's value) by calling the get
|
||||
method:
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#read-get
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#read-get
|
||||
:language: java
|
||||
|
||||
Reading an Agent's current value does not involve any message passing and
|
||||
|
|
@ -101,8 +101,8 @@ Awaiting an Agent's value
|
|||
It is also possible to read the value after all currently queued sends have
|
||||
completed. You can do this with ``await``:
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#import-timeout
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#import-timeout
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/agent/AgentDocTest.java#read-await
|
||||
.. includecode:: code/docs/agent/AgentDocTest.java#read-await
|
||||
:language: java
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Setting the dispatcher for an Actor
|
|||
|
||||
So in case you want to give your ``Actor`` a different dispatcher than the default, you need to do two things, of which the first is:
|
||||
|
||||
.. includecode:: ../java/code/akka/docs/dispatcher/DispatcherDocTestBase.java#defining-dispatcher
|
||||
.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTestBase.java#defining-dispatcher
|
||||
|
||||
.. note::
|
||||
The "dispatcherId" you specify in withDispatcher is in fact a path into your configuration.
|
||||
|
|
@ -27,11 +27,11 @@ So in case you want to give your ``Actor`` a different dispatcher than the defau
|
|||
|
||||
And then you just need to configure that dispatcher in your configuration:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-dispatcher-config
|
||||
.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#my-dispatcher-config
|
||||
|
||||
And here's another example that uses the "thread-pool-executor":
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-thread-pool-dispatcher-config
|
||||
.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#my-thread-pool-dispatcher-config
|
||||
|
||||
For more options, see the default-dispatcher section of the :ref:`configuration`.
|
||||
|
||||
|
|
@ -106,11 +106,11 @@ More dispatcher configuration examples
|
|||
|
||||
Configuring a ``PinnedDispatcher``:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-pinned-dispatcher-config
|
||||
.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#my-pinned-dispatcher-config
|
||||
|
||||
And then using it:
|
||||
|
||||
.. includecode:: ../java/code/akka/docs/dispatcher/DispatcherDocTestBase.java#defining-pinned-dispatcher
|
||||
.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTestBase.java#defining-pinned-dispatcher
|
||||
|
||||
Mailboxes
|
||||
---------
|
||||
|
|
@ -162,15 +162,15 @@ Mailbox configuration examples
|
|||
|
||||
How to create a PriorityMailbox:
|
||||
|
||||
.. includecode:: ../java/code/akka/docs/dispatcher/DispatcherDocTestBase.java#prio-mailbox
|
||||
.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTestBase.java#prio-mailbox
|
||||
|
||||
And then add it to the configuration:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config
|
||||
.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config
|
||||
|
||||
And then an example on how you would use it:
|
||||
|
||||
.. includecode:: ../java/code/akka/docs/dispatcher/DispatcherDocTestBase.java#prio-dispatcher
|
||||
.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTestBase.java#prio-dispatcher
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
|
|||
|
|
@ -158,12 +158,12 @@ Classification`_ which enables registering to related sets of channels (as is
|
|||
used for :class:`RemoteLifeCycleMessage`). The following example demonstrates
|
||||
how a simple subscription works. Given a simple actor:
|
||||
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java#imports-deadletter
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java#deadletter-actor
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java#imports-deadletter
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java#deadletter-actor
|
||||
|
||||
it can be subscribed like this:
|
||||
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java#deadletters
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java#deadletters
|
||||
|
||||
Default Handlers
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -25,22 +25,22 @@ So let's create a sample extension that just lets us count the number of times s
|
|||
|
||||
First, we define what our ``Extension`` should do:
|
||||
|
||||
.. includecode:: code/akka/docs/extension/ExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/ExtensionDocTestBase.java
|
||||
:include: imports,extension
|
||||
|
||||
Then we need to create an ``ExtensionId`` for our extension so we can grab ahold of it.
|
||||
|
||||
.. includecode:: code/akka/docs/extension/ExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/ExtensionDocTestBase.java
|
||||
:include: imports,extensionid
|
||||
|
||||
Wicked! Now all we need to do is to actually use it:
|
||||
|
||||
.. includecode:: code/akka/docs/extension/ExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/ExtensionDocTestBase.java
|
||||
:include: extension-usage
|
||||
|
||||
Or from inside of an Akka Actor:
|
||||
|
||||
.. includecode:: code/akka/docs/extension/ExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/ExtensionDocTestBase.java
|
||||
:include: extension-usage-actor
|
||||
|
||||
That's all there is to it!
|
||||
|
|
@ -72,17 +72,17 @@ The :ref:`configuration` can be used for application specific settings. A good p
|
|||
|
||||
Sample configuration:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/extension/SettingsExtensionDocSpec.scala
|
||||
.. includecode:: ../scala/code/docs/extension/SettingsExtensionDocSpec.scala
|
||||
:include: config
|
||||
|
||||
The ``Extension``:
|
||||
|
||||
.. includecode:: code/akka/docs/extension/SettingsExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/SettingsExtensionDocTestBase.java
|
||||
:include: imports,extension,extensionid
|
||||
|
||||
|
||||
Use it:
|
||||
|
||||
.. includecode:: code/akka/docs/extension/SettingsExtensionDocTestBase.java
|
||||
.. includecode:: code/docs/extension/SettingsExtensionDocTestBase.java
|
||||
:include: extension-usage-actor
|
||||
|
||||
|
|
|
|||
|
|
@ -49,5 +49,5 @@ Step Description
|
|||
Full Source Code of the Fault Tolerance Sample (Java)
|
||||
------------------------------------------------------
|
||||
|
||||
.. includecode:: code/akka/docs/actor/japi/FaultHandlingDocSample.java#all
|
||||
.. includecode:: code/docs/actor/japi/FaultHandlingDocSample.java#all
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ sample as it is easy to follow the log output to understand what is happening in
|
|||
|
||||
fault-tolerance-sample
|
||||
|
||||
.. includecode:: code/akka/docs/actor/japi/FaultHandlingDocSample.java#all
|
||||
.. includecode:: code/docs/actor/japi/FaultHandlingDocSample.java#all
|
||||
:exclude: imports,messages,dummydb
|
||||
|
||||
Creating a Supervisor Strategy
|
||||
|
|
@ -35,7 +35,7 @@ in more depth.
|
|||
|
||||
For the sake of demonstration let us consider the following strategy:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: strategy
|
||||
|
||||
I have chosen a few well-known exception types in order to demonstrate the
|
||||
|
|
@ -70,49 +70,49 @@ Test Application
|
|||
The following section shows the effects of the different directives in practice,
|
||||
wherefor a test setup is needed. First off, we need a suitable supervisor:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: supervisor
|
||||
|
||||
This supervisor will be used to create a child, with which we can experiment:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: child
|
||||
|
||||
The test is easier by using the utilities described in :ref:`akka-testkit`,
|
||||
where ``TestProbe`` provides an actor ref useful for receiving and inspecting replies.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: testkit
|
||||
|
||||
Let us create actors:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: create
|
||||
|
||||
The first test shall demonstrate the ``Resume`` directive, so we try it out by
|
||||
setting some non-initial state in the actor and have it fail:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: resume
|
||||
|
||||
As you can see the value 42 survives the fault handling directive. Now, if we
|
||||
change the failure to a more serious ``NullPointerException``, that will no
|
||||
longer be the case:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: restart
|
||||
|
||||
And finally in case of the fatal ``IllegalArgumentException`` the child will be
|
||||
terminated by the supervisor:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: stop
|
||||
|
||||
Up to now the supervisor was completely unaffected by the child’s failure,
|
||||
because the directives set did handle it. In case of an ``Exception``, this is not
|
||||
true anymore and the supervisor escalates the failure.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: escalate-kill
|
||||
|
||||
The supervisor itself is supervised by the top-level actor provided by the
|
||||
|
|
@ -125,12 +125,12 @@ child not to survive this failure.
|
|||
In case this is not desired (which depends on the use case), we need to use a
|
||||
different supervisor which overrides this behavior.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: supervisor2
|
||||
|
||||
With this parent, the child survives the escalated restart, as demonstrated in
|
||||
the last test:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FaultHandlingTestBase.java
|
||||
.. includecode:: code/docs/actor/FaultHandlingTestBase.java
|
||||
:include: escalate-restart
|
||||
|
||||
|
|
|
|||
|
|
@ -35,9 +35,9 @@ using a small well-defined set of methods. One way to achieve this is to
|
|||
assemble all mutable state in a superclass which keeps it private and offers
|
||||
protected methods for mutating it.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FSMDocTestBase.java#imports-data
|
||||
.. includecode:: code/docs/actor/FSMDocTestBase.java#imports-data
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FSMDocTestBase.java#base
|
||||
.. includecode:: code/docs/actor/FSMDocTestBase.java#base
|
||||
|
||||
The benefit of this approach is that state changes can be acted upon in one
|
||||
central place, which makes it impossible to forget inserting code for reacting
|
||||
|
|
@ -50,15 +50,15 @@ The base class shown above is designed to support a similar example as for the
|
|||
Scala FSM documentation: an actor which receives and queues messages, to be
|
||||
delivered in batches to a configurable target actor. The messages involved are:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FSMDocTestBase.java#data
|
||||
.. includecode:: code/docs/actor/FSMDocTestBase.java#data
|
||||
|
||||
This actor has only the two states ``IDLE`` and ``ACTIVE``, making their
|
||||
handling quite straight-forward in the concrete actor derived from the base
|
||||
class:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FSMDocTestBase.java#imports-actor
|
||||
.. includecode:: code/docs/actor/FSMDocTestBase.java#imports-actor
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FSMDocTestBase.java#actor
|
||||
.. includecode:: code/docs/actor/FSMDocTestBase.java#actor
|
||||
|
||||
The trick here is to factor out common functionality like :meth:`whenUnhandled`
|
||||
and :meth:`transition` in order to obtain a few well-defined points for
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ which is very similar to a ``java.util.concurrent.Executor``. if you have an ``A
|
|||
it will use its default dispatcher as the ``ExecutionContext``, or you can use the factory methods provided
|
||||
by the ``ExecutionContexts`` class to wrap ``Executors`` and ``ExecutorServices``, or even create your own.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports1,imports7,diy-execution-context
|
||||
|
||||
Use with Actors
|
||||
|
|
@ -30,7 +30,7 @@ which only works if the original sender was an ``UntypedActor``) and the second
|
|||
Using the ``ActorRef``\'s ``ask`` method to send a message will return a Future.
|
||||
To wait for and retrieve the actual result the simplest method is:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports1,ask-blocking
|
||||
|
||||
This will cause the current thread to block and wait for the ``UntypedActor`` to 'complete' the ``Future`` with it's reply.
|
||||
|
|
@ -47,7 +47,7 @@ A common use case within Akka is to have some computation performed concurrently
|
|||
the extra utility of an ``UntypedActor``. If you find yourself creating a pool of ``UntypedActor``\s for the sole reason
|
||||
of performing a calculation in parallel, there is an easier (and faster) way:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports2,future-eval
|
||||
|
||||
In the above code the block passed to ``future`` will be executed by the default ``Dispatcher``,
|
||||
|
|
@ -57,12 +57,12 @@ and we also avoid the overhead of managing an ``UntypedActor``.
|
|||
|
||||
You can also create already completed Futures using the ``Futures`` class, which can be either successes:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: successful
|
||||
|
||||
Or failures:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: failed
|
||||
|
||||
Functional Futures
|
||||
|
|
@ -78,7 +78,7 @@ The first method for working with ``Future`` functionally is ``map``. This metho
|
|||
some operation on the result of the ``Future``, and returning a new result.
|
||||
The return value of the ``map`` method is another ``Future`` that will contain the new result:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports2,map
|
||||
|
||||
In this example we are joining two strings together within a Future. Instead of waiting for f1 to complete,
|
||||
|
|
@ -92,7 +92,7 @@ Something to note when using these methods: if the ``Future`` is still being pro
|
|||
it will be the completing thread that actually does the work.
|
||||
If the ``Future`` is already complete though, it will be run in our current thread. For example:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: map2
|
||||
|
||||
The original ``Future`` will take at least 0.1 second to execute now, which means it is still being processed at
|
||||
|
|
@ -101,7 +101,7 @@ by the dispatcher when the result is ready.
|
|||
|
||||
If we do the opposite:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: map3
|
||||
|
||||
Our little string has been processed long before our 0.1 second sleep has finished. Because of this,
|
||||
|
|
@ -112,7 +112,7 @@ Normally this works quite well as it means there is very little overhead to runn
|
|||
If there is a possibility of the function taking a non-trivial amount of time to process it might be better
|
||||
to have this done concurrently, and for that we use ``flatMap``:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: flat-map
|
||||
|
||||
Now our second Future is executed concurrently as well. This technique can also be used to combine the results
|
||||
|
|
@ -120,7 +120,7 @@ of several Futures into a single calculation, which will be better explained in
|
|||
|
||||
If you need to do conditional propagation, you can use ``filter``:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: filter
|
||||
|
||||
Composing Futures
|
||||
|
|
@ -129,7 +129,7 @@ Composing Futures
|
|||
It is very often desirable to be able to combine different Futures with each other,
|
||||
below are some examples on how that can be done in a non-blocking fashion.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports3,sequence
|
||||
|
||||
To better explain what happened in the example, ``Future.sequence`` is taking the ``Iterable<Future<Integer>>``
|
||||
|
|
@ -139,7 +139,7 @@ and we aggregate the sum of the ``Iterable``.
|
|||
The ``traverse`` method is similar to ``sequence``, but it takes a sequence of ``A``s and applies a function from ``A`` to ``Future<B>``
|
||||
and returns a ``Future<Iterable<B>>``, enabling parallel ``map`` over the sequence, if you use ``Futures.future`` to create the ``Future``.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports4,traverse
|
||||
|
||||
It's as simple as that!
|
||||
|
|
@ -150,7 +150,7 @@ and the type of the futures and returns something with the same type as the star
|
|||
and then applies the function to all elements in the sequence of futures, non-blockingly,
|
||||
the execution will be started when the last of the Futures is completed.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports5,fold
|
||||
|
||||
That's all it takes!
|
||||
|
|
@ -160,7 +160,7 @@ If the sequence passed to ``fold`` is empty, it will return the start-value, in
|
|||
In some cases you don't have a start-value and you're able to use the value of the first completing Future
|
||||
in the sequence as the start-value, you can use ``reduce``, it works like this:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: imports6,reduce
|
||||
|
||||
Same as with ``fold``, the execution will be started when the last of the Futures is completed, you can also parallelize
|
||||
|
|
@ -174,13 +174,13 @@ Callbacks
|
|||
Sometimes you just want to listen to a ``Future`` being completed, and react to that not by creating a new Future, but by side-effecting.
|
||||
For this Akka supports ``onComplete``, ``onSuccess`` and ``onFailure``, of which the latter two are specializations of the first.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: onSuccess
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: onFailure
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: onComplete
|
||||
|
||||
Ordering
|
||||
|
|
@ -192,7 +192,7 @@ But there's a solution! And it's name is ``andThen``, and it creates a new Futur
|
|||
the specified callback, a Future that will have the same result as the Future it's called on,
|
||||
which allows for ordering like in the following sample:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: and-then
|
||||
|
||||
Auxiliary methods
|
||||
|
|
@ -201,13 +201,13 @@ Auxiliary methods
|
|||
``Future`` ``fallbackTo`` combines 2 Futures into a new ``Future``, and will hold the successful value of the second ``Future``
|
||||
if the first ``Future`` fails.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: fallback-to
|
||||
|
||||
You can also combine two Futures into a new ``Future`` that will hold a tuple of the two Futures successful results,
|
||||
using the ``zip`` operation.
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: zip
|
||||
|
||||
Exceptions
|
||||
|
|
@ -221,7 +221,7 @@ calling ``Await.result`` will cause it to be thrown again so it can be handled p
|
|||
It is also possible to handle an ``Exception`` by returning a different result.
|
||||
This is done with the ``recover`` method. For example:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: recover
|
||||
|
||||
In this example, if the actor replied with a ``akka.actor.Status.Failure`` containing the ``ArithmeticException``,
|
||||
|
|
@ -232,6 +232,6 @@ it will behave as if we hadn't used the ``recover`` method.
|
|||
You can also use the ``recoverWith`` method, which has the same relationship to ``recover`` as ``flatMap`` has to ``map``,
|
||||
and is use like this:
|
||||
|
||||
.. includecode:: code/akka/docs/future/FutureDocTestBase.java
|
||||
.. includecode:: code/docs/future/FutureDocTestBase.java
|
||||
:include: try-recover
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ How to Log
|
|||
Create a ``LoggingAdapter`` and use the ``error``, ``warning``, ``info``, or ``debug`` methods,
|
||||
as illustrated in this example:
|
||||
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java
|
||||
:include: imports,my-actor
|
||||
|
||||
The first parameter to ``Logging.getLogger`` could also be any
|
||||
|
|
@ -33,7 +33,7 @@ placeholders results in a warning being appended to the log statement (i.e. on
|
|||
the same line with the same severity). You may pass a Java array as the only
|
||||
substitution argument to have its elements be treated individually:
|
||||
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java#array
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java#array
|
||||
|
||||
The Java :class:`Class` of the log source is also included in the generated
|
||||
:class:`LogEvent`. In case of a simple string this is replaced with a “marker”
|
||||
|
|
@ -170,7 +170,7 @@ event handler available in the 'akka-slf4j' module.
|
|||
|
||||
Example of creating a listener:
|
||||
|
||||
.. includecode:: code/akka/docs/event/LoggingDocTestBase.java
|
||||
.. includecode:: code/docs/event/LoggingDocTestBase.java
|
||||
:include: imports,imports-listener,my-event-listener
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -82,11 +82,11 @@ The "app" in this case refers to the name of the ``ActorSystem`` (only showing d
|
|||
Logical path lookup is supported on the node you are on, i.e. to use the
|
||||
actor created above you would do the following:
|
||||
|
||||
.. includecode:: code/akka/docs/remoting/RemoteActorExample.java#localNodeActor
|
||||
.. includecode:: code/docs/remoting/RemoteActorExample.java#localNodeActor
|
||||
|
||||
This will obtain an ``ActorRef`` on a remote node:
|
||||
|
||||
.. includecode:: code/akka/docs/remoting/RemoteActorExample.java#remoteNodeActor
|
||||
.. includecode:: code/docs/remoting/RemoteActorExample.java#remoteNodeActor
|
||||
|
||||
As you can see from the example above the following pattern is used to find an ``ActorRef`` on a remote node::
|
||||
|
||||
|
|
@ -103,15 +103,15 @@ precedence.
|
|||
|
||||
With these imports:
|
||||
|
||||
.. includecode:: code/akka/docs/remoting/RemoteDeploymentDocTestBase.java#import
|
||||
.. includecode:: code/docs/remoting/RemoteDeploymentDocTestBase.java#import
|
||||
|
||||
and a remote address like this:
|
||||
|
||||
.. includecode:: code/akka/docs/remoting/RemoteDeploymentDocTestBase.java#make-address
|
||||
.. includecode:: code/docs/remoting/RemoteDeploymentDocTestBase.java#make-address
|
||||
|
||||
you can advise the system to create a child on that remote node like so:
|
||||
|
||||
.. includecode:: code/akka/docs/remoting/RemoteDeploymentDocTestBase.java#deploy
|
||||
.. includecode:: code/docs/remoting/RemoteDeploymentDocTestBase.java#deploy
|
||||
|
||||
Serialization
|
||||
^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -21,17 +21,17 @@ Routers In Action
|
|||
|
||||
This is an example of how to create a router that is defined in configuration:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/routing/RouterViaConfigExample.scala#config
|
||||
.. includecode:: ../scala/code/docs/routing/RouterViaConfigExample.scala#config
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaConfigExample.java#configurableRouting
|
||||
.. includecode:: code/docs/jrouting/RouterViaConfigExample.java#configurableRouting
|
||||
|
||||
This is an example of how to programmatically create a router and set the number of routees it should create:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingNrOfInstances
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingNrOfInstances
|
||||
|
||||
You can also give the router already created routees as in:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingRoutees
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingRoutees
|
||||
|
||||
It should be noted that no actor factory or class needs to be provided in this
|
||||
case, as the ``Router`` will not create any children on its own (which is not
|
||||
|
|
@ -65,7 +65,7 @@ configuration in a :class:`RemoteRouterConfig`, attaching the remote addresses o
|
|||
the nodes to deploy to. Naturally, this requires your to include the
|
||||
``akka-remote`` module on your classpath:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#remoteRoutees
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#remoteRoutees
|
||||
|
||||
How Routing is Designed within Akka
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -95,9 +95,9 @@ deterministic fashion. Since each actor knows its own external representation
|
|||
as well as that of its parent, the routees decide where replies should be sent
|
||||
when reacting to a message:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#reply-with-parent
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#reply-with-parent
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#reply-with-self
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#reply-with-self
|
||||
|
||||
It is apparent now why routing needs to be enabled in code rather than being
|
||||
possible to “bolt on” later: whether or not an actor is routed means a change
|
||||
|
|
@ -121,7 +121,7 @@ not have an effect on the number of actors in the pool.
|
|||
|
||||
Setting the strategy is easily done:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java
|
||||
:include: supervision
|
||||
|
||||
Another potentially useful approach is to give the router the same strategy as
|
||||
|
|
@ -140,18 +140,18 @@ Router usage
|
|||
In this section we will describe how to use the different router types.
|
||||
First we need to create some actors that will be used in the examples:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/PrintlnActor.java#printlnActor
|
||||
.. includecode:: code/docs/jrouting/PrintlnActor.java#printlnActor
|
||||
|
||||
and
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/FibonacciActor.java#fibonacciActor
|
||||
.. includecode:: code/docs/jrouting/FibonacciActor.java#fibonacciActor
|
||||
|
||||
RoundRobinRouter
|
||||
****************
|
||||
Routes in a `round-robin <http://en.wikipedia.org/wiki/Round-robin>`_ fashion to its routees.
|
||||
Code example:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/ParentActor.java#roundRobinRouter
|
||||
.. includecode:: code/docs/jrouting/ParentActor.java#roundRobinRouter
|
||||
|
||||
When run you should see a similar output to this:
|
||||
|
||||
|
|
@ -180,7 +180,7 @@ the message it receives to this routee.
|
|||
This procedure will happen each time it receives a message.
|
||||
Code example:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/ParentActor.java#randomRouter
|
||||
.. includecode:: code/docs/jrouting/ParentActor.java#randomRouter
|
||||
|
||||
When run you should see a similar output to this:
|
||||
|
||||
|
|
@ -213,14 +213,14 @@ The selection is done in this order:
|
|||
|
||||
Code example:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/ParentActor.java#smallestMailboxRouter
|
||||
.. includecode:: code/docs/jrouting/ParentActor.java#smallestMailboxRouter
|
||||
|
||||
BroadcastRouter
|
||||
***************
|
||||
A broadcast router forwards the message it receives to *all* its routees.
|
||||
Code example:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/ParentActor.java#broadcastRouter
|
||||
.. includecode:: code/docs/jrouting/ParentActor.java#broadcastRouter
|
||||
|
||||
When run you should see a similar output to this:
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ The ScatterGatherFirstCompletedRouter will send the message on to all its routee
|
|||
It then waits for first result it gets back. This result will be sent back to original sender.
|
||||
Code example:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/ParentActor.java#scatterGatherFirstCompletedRouter
|
||||
.. includecode:: code/docs/jrouting/ParentActor.java#scatterGatherFirstCompletedRouter
|
||||
|
||||
When run you should see this:
|
||||
|
||||
|
|
@ -272,16 +272,16 @@ of routees dynamically.
|
|||
|
||||
This is an example of how to create a resizable router that is defined in configuration:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/routing/RouterViaConfigExample.scala#config-resize
|
||||
.. includecode:: ../scala/code/docs/routing/RouterViaConfigExample.scala#config-resize
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaConfigExample.java#configurableRoutingWithResizer
|
||||
.. includecode:: code/docs/jrouting/RouterViaConfigExample.java#configurableRoutingWithResizer
|
||||
|
||||
Several more configuration options are available and described in ``akka.actor.deployment.default.resizer``
|
||||
section of the reference :ref:`configuration`.
|
||||
|
||||
This is an example of how to programmatically create a resizable router:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingWithResizer
|
||||
.. includecode:: code/docs/jrouting/RouterViaProgramExample.java#programmaticRoutingWithResizer
|
||||
|
||||
*It is also worth pointing out that if you define the ``router`` in the configuration file then this value
|
||||
will be used instead of any programmatically sent parameters.*
|
||||
|
|
@ -308,12 +308,12 @@ democrat related messages to the Democrat actor and all republican related messa
|
|||
|
||||
We begin with defining the class:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crRouter
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#crRouter
|
||||
:exclude: crRoute
|
||||
|
||||
The next step is to implement the ``createCustomRoute`` method in the class just defined:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crRoute
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#crRoute
|
||||
|
||||
As you can see above we start off by creating the routees and put them in a collection.
|
||||
|
||||
|
|
@ -322,12 +322,12 @@ It registers the routees internally and failing to call this method will
|
|||
cause a ``ActorInitializationException`` to be thrown when the router is used.
|
||||
Therefore always make sure to do the following in your custom router:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crRegisterRoutees
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#crRegisterRoutees
|
||||
|
||||
The routing logic is where your magic sauce is applied. In our example it inspects the message types
|
||||
and forwards to the correct routee based on this:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crRoutingLogic
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#crRoutingLogic
|
||||
|
||||
As you can see above what's returned in the ``CustomRoute`` function, which defines the mapping
|
||||
from incoming sender/message to a ``List`` of ``Destination(sender, routee)``.
|
||||
|
|
@ -338,11 +338,11 @@ For more information about how to alter the original sender we refer to the sour
|
|||
|
||||
All in all the custom router looks like this:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#CustomRouter
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#CustomRouter
|
||||
|
||||
If you are interested in how to use the VoteCountRouter it looks like this:
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crTest
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#crTest
|
||||
|
||||
.. caution::
|
||||
|
||||
|
|
@ -391,5 +391,5 @@ the actor system’s default dispatcher. All standard routers allow setting this
|
|||
property in their constructor or factory method, custom routers have to
|
||||
implement the method in a suitable way.
|
||||
|
||||
.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#dispatchers
|
||||
.. includecode:: code/docs/jrouting/CustomRouterDocTestBase.java#dispatchers
|
||||
|
||||
|
|
|
|||
|
|
@ -25,13 +25,13 @@ scheduled operation.
|
|||
Some examples
|
||||
-------------
|
||||
|
||||
.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
|
||||
.. includecode:: code/docs/actor/SchedulerDocTestBase.java
|
||||
:include: imports1,schedule-one-off-message
|
||||
|
||||
.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
|
||||
.. includecode:: code/docs/actor/SchedulerDocTestBase.java
|
||||
:include: schedule-one-off-thunk
|
||||
|
||||
.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
|
||||
.. includecode:: code/docs/actor/SchedulerDocTestBase.java
|
||||
:include: imports1,imports2,schedule-recurring
|
||||
|
||||
From ``akka.actor.ActorSystem``
|
||||
|
|
|
|||
|
|
@ -21,12 +21,12 @@ For Akka to know which ``Serializer`` to use for what, you need edit your :ref:`
|
|||
in the "akka.actor.serializers"-section you bind names to implementations of the ``akka.serialization.Serializer``
|
||||
you wish to use, like this:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/serialization/SerializationDocSpec.scala#serialize-serializers-config
|
||||
.. includecode:: ../scala/code/docs/serialization/SerializationDocSpec.scala#serialize-serializers-config
|
||||
|
||||
After you've bound names to different implementations of ``Serializer`` you need to wire which classes
|
||||
should be serialized using which ``Serializer``, this is done in the "akka.actor.serialization-bindings"-section:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/serialization/SerializationDocSpec.scala#serialization-bindings-config
|
||||
.. includecode:: ../scala/code/docs/serialization/SerializationDocSpec.scala#serialization-bindings-config
|
||||
|
||||
You only need to specify the name of an interface or abstract base class of the
|
||||
messages. In case of ambiguity, i.e. the message implements several of the
|
||||
|
|
@ -53,7 +53,7 @@ Verification
|
|||
|
||||
If you want to verify that your messages are serializable you can enable the following config option:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/serialization/SerializationDocSpec.scala#serialize-messages-config
|
||||
.. includecode:: ../scala/code/docs/serialization/SerializationDocSpec.scala#serialize-messages-config
|
||||
|
||||
.. warning::
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ If you want to verify that your messages are serializable you can enable the fol
|
|||
|
||||
If you want to verify that your ``Props`` are serializable you can enable the following config option:
|
||||
|
||||
.. includecode:: ../scala/code/akka/docs/serialization/SerializationDocSpec.scala#serialize-creators-config
|
||||
.. includecode:: ../scala/code/docs/serialization/SerializationDocSpec.scala#serialize-creators-config
|
||||
|
||||
.. warning::
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ Programmatic
|
|||
If you want to programmatically serialize/deserialize using Akka Serialization,
|
||||
here's some examples:
|
||||
|
||||
.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
|
||||
.. includecode:: code/docs/serialization/SerializationDocTestBase.java
|
||||
:include: imports,programmatic
|
||||
|
||||
For more information, have a look at the ``ScalaDoc`` for ``akka.serialization._``
|
||||
|
|
@ -93,7 +93,7 @@ Creating new Serializers
|
|||
First you need to create a class definition of your ``Serializer``,
|
||||
which is done by extending ``akka.serialization.JSerializer``, like this:
|
||||
|
||||
.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
|
||||
.. includecode:: code/docs/serialization/SerializationDocTestBase.java
|
||||
:include: imports,my-own-serializer
|
||||
:exclude: ...
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ Serializing ActorRefs
|
|||
All ActorRefs are serializable using JavaSerializer, but in case you are writing your own serializer,
|
||||
you might want to know how to serialize and deserialize them properly, here's the magic incantation:
|
||||
|
||||
.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
|
||||
.. includecode:: code/docs/serialization/SerializationDocTestBase.java
|
||||
:include: imports,actorref-serializer
|
||||
|
||||
.. note::
|
||||
|
|
@ -131,7 +131,7 @@ address which shall be the recipient of the serialized information. Use
|
|||
:meth:`ActorRefProvider.getExternalAddressFor(remoteAddr)` to query the system
|
||||
for the appropriate address to use when sending to ``remoteAddr``:
|
||||
|
||||
.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
|
||||
.. includecode:: code/docs/serialization/SerializationDocTestBase.java
|
||||
:include: external-address
|
||||
|
||||
This requires that you know at least which type of address will be supported by
|
||||
|
|
@ -144,7 +144,7 @@ There is a possible simplification available if you are just using the default
|
|||
:class:`NettyRemoteTransport` with the :meth:`RemoteActorRefProvider`, which is
|
||||
enabled by the fact that this combination has just a single remote address:
|
||||
|
||||
.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
|
||||
.. includecode:: code/docs/serialization/SerializationDocTestBase.java
|
||||
:include: external-address-default
|
||||
|
||||
This solution has to be adapted once other providers are used (like the planned
|
||||
|
|
|
|||
|
|
@ -63,22 +63,22 @@ Here is an example of coordinating two simple counter UntypedActors so that they
|
|||
both increment together in coordinated transactions. If one of them was to fail
|
||||
to increment, the other would also fail.
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/Increment.java#class
|
||||
.. includecode:: code/docs/transactor/Increment.java#class
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/CoordinatedCounter.java#class
|
||||
.. includecode:: code/docs/transactor/CoordinatedCounter.java#class
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/TransactorDocTest.java#imports
|
||||
.. includecode:: code/docs/transactor/TransactorDocTest.java#imports
|
||||
:language: java
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/TransactorDocTest.java#coordinated-example
|
||||
.. includecode:: code/docs/transactor/TransactorDocTest.java#coordinated-example
|
||||
:language: java
|
||||
|
||||
To start a new coordinated transaction that you will also participate in, create
|
||||
a ``Coordinated`` object, passing in a ``Timeout``:
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/TransactorDocTest.java#create-coordinated
|
||||
.. includecode:: code/docs/transactor/TransactorDocTest.java#create-coordinated
|
||||
:language: java
|
||||
|
||||
To start a coordinated transaction that you won't participate in yourself you
|
||||
|
|
@ -86,7 +86,7 @@ can create a ``Coordinated`` object with a message and send it directly to an
|
|||
actor. The recipient of the message will be the first member of the coordination
|
||||
set:
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/TransactorDocTest.java#send-coordinated
|
||||
.. includecode:: code/docs/transactor/TransactorDocTest.java#send-coordinated
|
||||
:language: java
|
||||
|
||||
To include another actor in the same coordinated transaction that you've created
|
||||
|
|
@ -94,13 +94,13 @@ or received, use the ``coordinate`` method on that object. This will increment
|
|||
the number of parties involved by one and create a new ``Coordinated`` object to
|
||||
be sent.
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/TransactorDocTest.java#include-coordinated
|
||||
.. includecode:: code/docs/transactor/TransactorDocTest.java#include-coordinated
|
||||
:language: java
|
||||
|
||||
To enter the coordinated transaction use the atomic method of the coordinated
|
||||
object, passing in a ``java.lang.Runnable``.
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/Coordinator.java#coordinated-atomic
|
||||
.. includecode:: code/docs/transactor/Coordinator.java#coordinated-atomic
|
||||
:language: java
|
||||
|
||||
The coordinated transaction will wait for the other transactions before
|
||||
|
|
@ -124,7 +124,7 @@ coordinating transactions, using the explicit coordination described above.
|
|||
Here's an example of a simple untyped transactor that will join a coordinated
|
||||
transaction:
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/Counter.java#class
|
||||
.. includecode:: code/docs/transactor/Counter.java#class
|
||||
:language: java
|
||||
|
||||
You could send this Counter transactor a ``Coordinated(Increment)`` message. If
|
||||
|
|
@ -140,7 +140,7 @@ to easily coordinate with other transactors.
|
|||
Here's an example of coordinating an increment, using an untyped transactor,
|
||||
similar to the explicitly coordinated example above.
|
||||
|
||||
.. includecode:: code/akka/docs/transactor/FriendlyCounter.java#class
|
||||
.. includecode:: code/docs/transactor/FriendlyCounter.java#class
|
||||
:language: java
|
||||
|
||||
To execute directly before or after the coordinated transaction, override the
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ The tools of the trade
|
|||
Before we create our first Typed Actor we should first go through the tools that we have at our disposal,
|
||||
it's located in ``akka.actor.TypedActor``.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-extension-tools
|
||||
|
||||
.. warning::
|
||||
|
|
@ -55,37 +55,37 @@ To create a Typed Actor you need to have one or more interfaces, and one impleme
|
|||
|
||||
Our example interface:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: imports,typed-actor-iface
|
||||
:exclude: typed-actor-iface-methods
|
||||
|
||||
Our example implementation of that interface:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: imports,typed-actor-impl
|
||||
:exclude: typed-actor-impl-methods
|
||||
|
||||
The most trivial way of creating a Typed Actor instance
|
||||
of our ``Squarer``:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-create1
|
||||
|
||||
First type is the type of the proxy, the second type is the type of the implementation.
|
||||
If you need to call a specific constructor you do it like this:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-create2
|
||||
|
||||
Since you supply a ``Props``, you can specify which dispatcher to use, what the default timeout should be used and more.
|
||||
Now, our ``Squarer`` doesn't have any methods, so we'd better add those.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: imports,typed-actor-iface
|
||||
|
||||
Alright, now we've got some methods we can call, but we need to implement those in ``SquarerImpl``.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: imports,typed-actor-impl
|
||||
|
||||
Excellent, now we have an interface and an implementation of that interface,
|
||||
|
|
@ -113,7 +113,7 @@ we *strongly* recommend that parameters passed are immutable.
|
|||
One-way message send
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-call-oneway
|
||||
|
||||
As simple as that! The method will be executed on another thread; asynchronously.
|
||||
|
|
@ -121,13 +121,13 @@ As simple as that! The method will be executed on another thread; asynchronously
|
|||
Request-reply message send
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-call-option
|
||||
|
||||
This will block for as long as the timeout that was set in the ``Props`` of the Typed Actor,
|
||||
if needed. It will return ``None`` if a timeout occurs.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-call-strict
|
||||
|
||||
This will block for as long as the timeout that was set in the ``Props` of the Typed Actor,
|
||||
|
|
@ -136,7 +136,7 @@ if needed. It will throw a ``java.util.concurrent.TimeoutException`` if a timeou
|
|||
Request-reply-with-future message send
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-call-future
|
||||
|
||||
This call is asynchronous, and the Future returned can be used for asynchronous composition.
|
||||
|
|
@ -146,12 +146,12 @@ Stopping Typed Actors
|
|||
|
||||
Since Akka's Typed Actors are backed by Akka Actors they must be stopped when they aren't needed anymore.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-stop
|
||||
|
||||
This asynchronously stops the Typed Actor associated with the specified proxy ASAP.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java
|
||||
:include: typed-actor-poisonpill
|
||||
|
||||
This asynchronously stops the Typed Actor associated with the specified proxy
|
||||
|
|
@ -204,4 +204,4 @@ Lookup & Remoting
|
|||
|
||||
Since ``TypedActors`` are backed by ``Akka Actors``, you can use ``actorFor`` together with ``typedActorOf`` to proxy ``ActorRefs`` potentially residing on remote nodes.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/TypedActorDocTestBase.java#typed-actor-remote
|
||||
.. includecode:: code/docs/actor/TypedActorDocTestBase.java#typed-actor-remote
|
||||
|
|
@ -36,7 +36,7 @@ Actor in Java are implemented by extending the ``UntypedActor`` class and implem
|
|||
|
||||
Here is an example:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/MyUntypedActor.java#my-untyped-actor
|
||||
.. includecode:: code/docs/actor/MyUntypedActor.java#my-untyped-actor
|
||||
|
||||
Props
|
||||
-----
|
||||
|
|
@ -44,7 +44,7 @@ Props
|
|||
``Props`` is a configuration class to specify options for the creation
|
||||
of actors. Here are some examples on how to create a ``Props`` instance.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-props-config
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#creating-props-config
|
||||
|
||||
|
||||
Creating Actors with Props
|
||||
|
|
@ -52,13 +52,13 @@ Creating Actors with Props
|
|||
|
||||
Actors are created by passing in a ``Props`` instance into the ``actorOf`` factory method.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-props
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#creating-props
|
||||
|
||||
|
||||
Creating Actors with default constructor
|
||||
----------------------------------------
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java
|
||||
:include: imports,system-actorOf
|
||||
|
||||
The call to :meth:`actorOf` returns an instance of ``ActorRef``. This is a handle to
|
||||
|
|
@ -75,7 +75,7 @@ how the supervisor hierarchy is arranged. When using the context the current act
|
|||
will be supervisor of the created child actor. When using the system it will be
|
||||
a top level actor, that is supervised by the system (internal guardian actor).
|
||||
|
||||
.. includecode:: code/akka/docs/actor/FirstUntypedActor.java#context-actorOf
|
||||
.. includecode:: code/docs/actor/FirstUntypedActor.java#context-actorOf
|
||||
|
||||
The name parameter is optional, but you should preferably name your actors, since
|
||||
that is used in log messages and for identifying actors. The name must not be empty
|
||||
|
|
@ -110,7 +110,7 @@ in which you can create the Actor in any way you like.
|
|||
|
||||
Here is an example:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-constructor
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#creating-constructor
|
||||
|
||||
This way of creating the Actor is also great for integrating with Dependency Injection
|
||||
(DI) frameworks like Guice or Spring.
|
||||
|
|
@ -144,7 +144,7 @@ In addition, it offers:
|
|||
The remaining visible methods are user-overridable life-cycle hooks which are
|
||||
described in the following:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#lifecycle-callbacks
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#lifecycle-callbacks
|
||||
|
||||
The implementations shown above are the defaults provided by the :class:`UntypedActor`
|
||||
class.
|
||||
|
|
@ -163,7 +163,7 @@ termination (see `Stopping Actors`_). This service is provided by the
|
|||
Registering a monitor is easy (see fourth line, the rest is for demonstrating
|
||||
the whole functionality):
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#watch
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#watch
|
||||
|
||||
It should be noted that the :class:`Terminated` message is generated
|
||||
independent of the order in which registration and termination occur.
|
||||
|
|
@ -279,7 +279,7 @@ convention.
|
|||
|
||||
Here is an example of an immutable message:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/ImmutableMessage.java#immutable-message
|
||||
.. includecode:: code/docs/actor/ImmutableMessage.java#immutable-message
|
||||
|
||||
|
||||
Send messages
|
||||
|
|
@ -332,9 +332,9 @@ Ask: Send-And-Receive-Future
|
|||
The ``ask`` pattern involves actors as well as futures, hence it is offered as
|
||||
a use pattern rather than a method on :class:`ActorRef`:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#import-askPipe
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#import-askPipe
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#ask-pipe
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#ask-pipe
|
||||
|
||||
This example demonstrates ``ask`` together with the ``pipe`` pattern on
|
||||
futures, because this is likely to be a common combination. Please note that
|
||||
|
|
@ -355,7 +355,7 @@ To complete the future with an exception you need send a Failure message to the
|
|||
This is *not done automatically* when an actor throws an exception while processing a
|
||||
message.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#reply-exception
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#reply-exception
|
||||
|
||||
If the actor does not complete the future, it will expire after the timeout period,
|
||||
specified as parameter to the ``ask`` method; this will complete the
|
||||
|
|
@ -399,7 +399,7 @@ an abstract method on the ``UntypedActor`` base class that needs to be defined.
|
|||
|
||||
Here is an example:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/MyUntypedActor.java#my-untyped-actor
|
||||
.. includecode:: code/docs/actor/MyUntypedActor.java#my-untyped-actor
|
||||
|
||||
An alternative to using if-instanceof checks is to use `Apache Commons MethodUtils
|
||||
<http://commons.apache.org/beanutils/api/org/apache/commons/beanutils/MethodUtils.html#invokeMethod(java.lang.Object,%20java.lang.String,%20java.lang.Object)>`_
|
||||
|
|
@ -432,7 +432,7 @@ received within a certain time. To receive this timeout you have to set the
|
|||
``receiveTimeout`` property and declare handing for the ReceiveTimeout
|
||||
message.
|
||||
|
||||
.. includecode:: code/akka/docs/actor/MyReceivedTimeoutUntypedActor.java#receive-timeout
|
||||
.. includecode:: code/docs/actor/MyReceivedTimeoutUntypedActor.java#receive-timeout
|
||||
|
||||
.. _stopping-actors-java:
|
||||
|
||||
|
|
@ -494,7 +494,7 @@ in the mailbox.
|
|||
|
||||
Use it like this:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java
|
||||
:include: import-actors,poison-pill
|
||||
|
||||
Graceful Stop
|
||||
|
|
@ -503,7 +503,7 @@ Graceful Stop
|
|||
:meth:`gracefulStop` is useful if you need to wait for termination or compose ordered
|
||||
termination of several actors:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java
|
||||
:include: import-gracefulStop,gracefulStop
|
||||
|
||||
When ``gracefulStop()`` returns successfully, the actor’s ``postStop()`` hook
|
||||
|
|
@ -537,7 +537,7 @@ The hotswapped code is kept in a Stack which can be pushed and popped.
|
|||
|
||||
To hotswap the Actor using ``getContext().become``:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java
|
||||
:include: import-procedure,hot-swap-actor
|
||||
|
||||
The ``become`` method is useful for many different things, such as to implement
|
||||
|
|
@ -545,7 +545,7 @@ a Finite State Machine (FSM).
|
|||
|
||||
Here is another little cute example of ``become`` and ``unbecome`` in action:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorSwapper.java#swapper
|
||||
.. includecode:: code/docs/actor/UntypedActorSwapper.java#swapper
|
||||
|
||||
Downgrade
|
||||
---------
|
||||
|
|
@ -567,7 +567,7 @@ through regular supervisor semantics.
|
|||
|
||||
Use it like this:
|
||||
|
||||
.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
|
||||
.. includecode:: code/docs/actor/UntypedActorDocTestBase.java
|
||||
:include: import-actors,kill
|
||||
|
||||
Actors and exceptions
|
||||
|
|
|
|||
|
|
@ -19,15 +19,15 @@ Connection
|
|||
ZeroMQ supports multiple connectivity patterns, each aimed to meet a different set of requirements. Currently, this module supports publisher-subscriber connections and connections based on dealers and routers. For connecting or accepting connections, a socket must be created.
|
||||
Sockets are always created using the ``akka.zeromq.ZeroMQExtension``, for example:
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#pub-socket
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#pub-socket
|
||||
|
||||
Above examples will create a ZeroMQ Publisher socket that is Bound to the port 1233 on localhost.
|
||||
|
||||
Similarly you can create a subscription socket, with a listener, that subscribes to all messages from the publisher using:
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#sub-socket
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#sub-socket
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#listener-actor
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#listener-actor
|
||||
|
||||
The following sub-sections describe the supported connection patterns and how they can be used in an Akka environment. However, for a comprehensive discussion of connection patterns, please refer to `ZeroMQ -- The Guide <http://zguide.zeromq.org/page:all>`_.
|
||||
|
||||
|
|
@ -43,18 +43,18 @@ When you're using zeromq pub/sub you should be aware that it needs multicast - c
|
|||
|
||||
An actor is subscribed to a topic as follows:
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#sub-topic-socket
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#sub-topic-socket
|
||||
|
||||
It is a prefix match so it is subscribed to all topics starting with ``foo.bar``. Note that if the given string is empty or
|
||||
``Subscribe.all()`` is used, the actor is subscribed to all topics.
|
||||
|
||||
To unsubscribe from a topic you do the following:
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#unsub-topic-socket
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#unsub-topic-socket
|
||||
|
||||
To publish messages to a topic you must use two Frames with the topic in the first frame.
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#pub-topic
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#pub-topic
|
||||
|
||||
Pub-Sub in Action
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -64,22 +64,22 @@ The following example illustrates one publisher with two subscribers.
|
|||
The publisher monitors current heap usage and system load and periodically publishes ``Heap`` events on the ``"health.heap"`` topic
|
||||
and ``Load`` events on the ``"health.load"`` topic.
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#health
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#health
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#health2
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#health2
|
||||
|
||||
Let's add one subscriber that logs the information. It subscribes to all topics starting with ``"health"``, i.e. both ``Heap`` and
|
||||
``Load`` events.
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#logger
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#logger
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#logger2
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#logger2
|
||||
|
||||
Another subscriber keep track of used heap and warns if too much heap is used. It only subscribes to ``Heap`` events.
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#alerter
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#alerter
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#alerter2
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#alerter2
|
||||
|
||||
Router-Dealer Connection
|
||||
------------------------
|
||||
|
|
@ -90,7 +90,7 @@ With those socket types you can build your own reliable pub sub broker that uses
|
|||
|
||||
To create a Router socket that has a high watermark configured, you would do:
|
||||
|
||||
.. includecode:: code/akka/docs/zeromq/ZeromqDocTestBase.java#high-watermark
|
||||
.. includecode:: code/docs/zeromq/ZeromqDocTestBase.java#high-watermark
|
||||
|
||||
The akka-zeromq module accepts most if not all the available configuration options for a zeromq socket.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue