9bc01ae265
The idea is to filter the sources, replacing @<var>@ occurrences with the mapping for <var> (which is currently hard-coded). @@ -> @. In order to make this work, I had to move the doc sources one directory down (into akka-docs/rst) so that the filtered result could be in a sibling directory so that relative links (to _sphinx plugins or real code) would continue to work. While I was at it I also changed it so that WARNINGs and ERRORs are not swallowed into the debug dump anymore but printed at [warn] level (minimum). One piece of fallout is that the (online) html build is now run after the normal one, not in parallel.
89 lines
2.8 KiB
ReStructuredText
89 lines
2.8 KiB
ReStructuredText
.. _extending-akka-scala:
|
|
|
|
#########################
|
|
Akka Extensions (Scala)
|
|
#########################
|
|
|
|
|
|
If you want to add features to Akka, there is a very elegant, but powerful mechanism for doing so.
|
|
It's called Akka Extensions and is comprised of 2 basic components: an ``Extension`` and an ``ExtensionId``.
|
|
|
|
Extensions will only be loaded once per ``ActorSystem``, which will be managed by Akka.
|
|
You can choose to have your Extension loaded on-demand or at ``ActorSystem`` creation time through the Akka configuration.
|
|
Details on how to make that happens are below, in the "Loading from Configuration" section.
|
|
|
|
.. warning::
|
|
|
|
Since an extension is a way to hook into Akka itself, the implementor of the extension needs to
|
|
ensure the thread safety of his/her extension.
|
|
|
|
Building an Extension
|
|
=====================
|
|
|
|
So let's create a sample extension that just lets us count the number of times something has happened.
|
|
|
|
First, we define what our ``Extension`` should do:
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: extension
|
|
|
|
Then we need to create an ``ExtensionId`` for our extension so we can grab ahold of it.
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: extensionid
|
|
|
|
Wicked! Now all we need to do is to actually use it:
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: extension-usage
|
|
|
|
Or from inside of an Akka Actor:
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: extension-usage-actor
|
|
|
|
You can also hide extension behind traits:
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: extension-usage-actor-trait
|
|
|
|
That's all there is to it!
|
|
|
|
Loading from Configuration
|
|
==========================
|
|
|
|
To be able to load extensions from your Akka configuration you must add FQCNs of implementations of either ``ExtensionId`` or ``ExtensionIdProvider``
|
|
in the ``akka.extensions`` section of the config you provide to your ``ActorSystem``.
|
|
|
|
.. includecode:: code/docs/extension/ExtensionDocSpec.scala
|
|
:include: config
|
|
|
|
Applicability
|
|
=============
|
|
|
|
The sky is the limit!
|
|
By the way, did you know that Akka's ``Typed Actors``, ``Serialization`` and other features are implemented as Akka Extensions?
|
|
|
|
.. _extending-akka-scala.settings:
|
|
|
|
Application specific settings
|
|
-----------------------------
|
|
|
|
The :ref:`configuration` can be used for application specific settings. A good practice is to place those settings in an Extension.
|
|
|
|
Sample configuration:
|
|
|
|
.. includecode:: code/docs/extension/SettingsExtensionDocSpec.scala
|
|
:include: config
|
|
|
|
The ``Extension``:
|
|
|
|
.. includecode:: code/docs/extension/SettingsExtensionDocSpec.scala
|
|
:include: imports,extension,extensionid
|
|
|
|
|
|
Use it:
|
|
|
|
.. includecode:: code/docs/extension/SettingsExtensionDocSpec.scala
|
|
:include: extension-usage-actor
|
|
|