add extractActorSystem directive (#21097)

akka-docs/rst/java/code/docs/http/javadsl/server/directives/BasicDirectivesExamplesTest.java

@@ -877,4 +877,17 @@ public class BasicDirectivesExamplesTest extends JUnitRouteTest {
     //#toStrictEntity
   }
 
+  @Test
+  public void testExtractActorSystem() {
+    //#extractActorSystem
+    final Route route = extractActorSystem(actorSystem ->
+      complete("Actor System extracted, hash=" + actorSystem.hashCode())
+    );
+
+    // tests:
+    testRoute(route).run(HttpRequest.GET("/"))
+      .assertEntity("Actor System extracted, hash=" + system().hashCode());
+    //#extractActorSystem
+  }
+
 }

akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractActorSystem.rst

@@ -0,0 +1,19 @@
+.. _-extractActorSystem-java-:
+
+extractActorSystem
+==================
+
+Description
+-----------
+
+Extracts the ``ActorSystem`` from the ``RequestContext``, which can be useful when the external API
+in your route needs one.
+
+.. warning::
+
+  This is only supported when the available Materializer is an ActorMaterializer.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/BasicDirectivesExamplesTest.java#extractActorSystem

akka-docs/rst/java/http/routing-dsl/directives/basic-directives/index.rst

@@ -17,6 +17,7 @@ on two axes: a) provide a constant value or extract a value from the ``RequestCo
 a single value or a tuple of values.
 
   * :ref:`-extract-java-`
+  * :ref:`-extractActorSystem-java-`
   * :ref:`-extractDataBytes-java-`
   * :ref:`-extractExecutionContext-java-`
   * :ref:`-extractMaterializer-java-`
@@ -95,6 +96,7 @@ Alphabetically
    cancelRejection
    cancelRejections
    extract
+   extractActorSystem
    extractDataBytes
    extractExecutionContext
    extractMaterializer