Merge paradox/scala/extending-akka.md and java/extending-akka.md (#23156)

akka-docs/src/main/paradox/java/extending-akka.md

@@ -1,96 +0,0 @@
-# Akka Extensions
-
-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:
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #imports }
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extension }
-
-Then we need to create an `ExtensionId` for our extension so we can grab a hold of it.
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #imports }
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extensionid }
-
-Wicked! Now all we need to do is to actually use it:
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extension-usage }
-
-Or from inside of an Akka Actor:
-
-@@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extension-usage-actor }
-
-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`.
-
-```
-akka {
-  extensions = ["docs.extension.ExtensionDocTest.CountExtension"]
-}
-```
-
-## 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?
-
-<a id="extending-akka-settings"></a>
-### Application specific settings
-
-The @ref:[configuration](general/configuration.md) can be used for application specific settings. A good practice is to place those settings in an Extension.
-
-Sample configuration:
-
-@@snip [SettingsExtensionDocSpec.scala]($code$/scala/docs/extension/SettingsExtensionDocSpec.scala) { #config }
-
-The `Extension`:
-
-@@snip [SettingsExtensionDocTest.java]($code$/java/jdocs/extension/SettingsExtensionDocTest.java) { #imports }
-
-@@snip [SettingsExtensionDocTest.java]($code$/java/jdocs/extension/SettingsExtensionDocTest.java) { #extension #extensionid }
-
-Use it:
-
-@@snip [SettingsExtensionDocTest.java]($code$/java/jdocs/extension/SettingsExtensionDocTest.java) { #extension-usage-actor }
-
-## Library extensions
-
-A third part library may register it's extension for auto-loading on actor system startup by appending it to
-`akka.library-extensions` in its `reference.conf`.
-
-```
-akka.library-extensions += "docs.extension.ExampleExtension"
-```
-
-As there is no way to selectively remove such extensions, it should be used with care and only when there is no case
-where the user would ever want it disabled or have specific support for disabling such sub-features. One example where
-this could be important is in tests.
-
-@@@ warning
-
-The``akka.library-extensions`` must never be assigned (`= ["Extension"]`) instead of appending as this will break
-the library-extension mechanism and make behavior depend on class path ordering.
-
-@@@

akka-docs/src/main/paradox/java/extending-akka.md

@@ -0,0 +1 @@
+../scala/extending-akka.md

akka-docs/src/main/paradox/scala/extending-akka.md

@@ -20,24 +20,44 @@ 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:
 
-@@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension }
+Scala
+:  @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension }
+
+Java
+:  @@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #imports #extension }
 
 Then we need to create an `ExtensionId` for our extension so we can grab a hold of it.
 
-@@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extensionid }
+Scala
+:  @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extensionid }
+
+Java
+:  @@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #imports #extensionid }
 
 Wicked! Now all we need to do is to actually use it:
 
-@@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension-usage }
+Scala
+:  @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension-usage }
+
+Java
+:  @@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extension-usage }
 
 Or from inside of an Akka Actor:
 
-@@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension-usage-actor }
+Scala
+:  @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension-usage-actor }
+
+Java
+:  @@snip [ExtensionDocTest.java]($code$/java/jdocs/extension/ExtensionDocTest.java) { #extension-usage-actor }
+
+@@@ div { .group-scala }
 
 You can also hide extension behind traits:
 
 @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #extension-usage-actor-trait }
 
+@@@
+
 That's all there is to it!
 
 ## Loading from Configuration
@@ -45,7 +65,17 @@ That's all there is to it!
 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`.
 
-@@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #config }
+Scala
+:  @@snip [ExtensionDocSpec.scala]($code$/scala/docs/extension/ExtensionDocSpec.scala) { #config }
+
+Java
+:   @@@vars
+    ```
+    akka {
+      extensions = ["docs.extension.ExtensionDocTest.CountExtension"]
+    }
+    ```
+    @@@
 
 ## Applicability
 
@@ -63,11 +93,19 @@ Sample configuration:
 
 The `Extension`:
 
-@@snip [SettingsExtensionDocSpec.scala]($code$/scala/docs/extension/SettingsExtensionDocSpec.scala) { #imports #extension #extensionid }
+Scala
+:  @@snip [SettingsExtensionDocSpec.scala]($code$/scala/docs/extension/SettingsExtensionDocSpec.scala) { #imports #extension #extensionid }
+
+Java
+:  @@snip [SettingsExtensionDocTest.java]($code$/java/jdocs/extension/SettingsExtensionDocTest.java) { #imports #extension #extensionid }
 
 Use it:
 
-@@snip [SettingsExtensionDocSpec.scala]($code$/scala/docs/extension/SettingsExtensionDocSpec.scala) { #extension-usage-actor }
+Scala
+:  @@snip [SettingsExtensionDocSpec.scala]($code$/scala/docs/extension/SettingsExtensionDocSpec.scala) { #extension-usage-actor }
+
+Java
+:  @@snip [SettingsExtensionDocTest.java]($code$/java/jdocs/extension/SettingsExtensionDocTest.java) { #extension-usage-actor }
 
 ## Library extensions