+doc add java example for onCompleteWithBreaker (#20675)

* +doc #20198 add java example for onCompleteWithBreaker

* =doc fix sphinx warnings

akka-docs/rst/additional/books.rst

@@ -10,6 +10,6 @@ Books
 * `Akka Essentials <https://www.packtpub.com/application-development/akka-essentials>`_, by Munish K. Gupta, PACKT Publishing, ISBN: 1849518289, October 2012
 
 Videos
-=====
+======
 
-* `Learning Akka <https://www.packtpub.com/application-development/learning-akka-video>`_, by Salma Khater, PACKT Publishing, ISBN: 9781784391836, January 2016
+* `Learning Akka Videos <https://www.packtpub.com/application-development/learning-akka-video>`_, by Salma Khater, PACKT Publishing, ISBN: 9781784391836, January 2016

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

@@ -5,13 +5,17 @@
 package docs.http.javadsl.server.directives;
 
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
 import akka.http.javadsl.model.HttpRequest;
 import akka.http.javadsl.server.Marshaller;
 import akka.http.javadsl.server.Route;
 import akka.http.javadsl.testkit.JUnitRouteTest;
 import akka.http.scaladsl.model.StatusCodes;
 import akka.japi.pf.PFBuilder;
+import akka.pattern.CircuitBreaker;
 import org.junit.Test;
+import scala.concurrent.duration.FiniteDuration;
 
 import static akka.http.javadsl.server.PathMatchers.*;
 import static scala.compat.java8.JFunction.func;
@@ -96,5 +100,51 @@ public class FutureDirectivesExamplesTest extends JUnitRouteTest {
       .assertEntity("There was an internal server error.");
     //#completeOrRecoverWith
   }
+  
+  @Test
+  public void testOnCompleteWithBreaker() throws InterruptedException {
+    //#onCompleteWithBreaker
+    // import static scala.compat.java8.JFunction.func;
+    // import static akka.http.javadsl.server.PathMatchers.*;
+
+    final int maxFailures = 1;
+    final FiniteDuration callTimeout = FiniteDuration.create(5, TimeUnit.SECONDS);
+    final FiniteDuration resetTimeout = FiniteDuration.create(1, TimeUnit.SECONDS);
+    final CircuitBreaker breaker = CircuitBreaker.create(system().scheduler(), maxFailures, callTimeout, resetTimeout);
+    
+    final Route route = path(segment("divide").slash(integerSegment()).slash(integerSegment()),
+      (a, b) -> onCompleteWithBreaker(breaker,
+        () ->  CompletableFuture.supplyAsync(() -> a / b),
+        maybeResult -> maybeResult
+          .map(func(result -> complete("The result was " + result)))
+          .recover(new PFBuilder<Throwable, Route>()
+            .matchAny(ex -> complete(StatusCodes.InternalServerError(),
+              "An error occurred: " + ex.getMessage())
+            )
+            .build())
+          .get()
+      )
+    );
+
+    testRoute(route).run(HttpRequest.GET("/divide/10/2"))
+      .assertEntity("The result was 5");
+
+    testRoute(route).run(HttpRequest.GET("/divide/10/0"))
+      .assertStatusCode(StatusCodes.InternalServerError())
+      .assertEntity("An error occurred: / by zero");
+    // opened the circuit-breaker 
+    
+    testRoute(route).run(HttpRequest.GET("/divide/10/0"))
+          .assertStatusCode(StatusCodes.ServiceUnavailable())
+          .assertEntity("The server is currently unavailable (because it is overloaded or down for maintenance).");
+
+    Thread.sleep(resetTimeout.toMillis() + 300);
+    // circuit breaker resets after this time
+    
+    testRoute(route).run(HttpRequest.GET("/divide/8/2"))
+      .assertEntity("The result was 4");
+    
+    //#onCompleteWithBreaker
+  }
 
 }

akka-docs/rst/java/http/routing-dsl/directives/future-directives/onCompleteWithBreaker.rst

@@ -16,4 +16,4 @@ Otherwise, the same behaviour provided by :ref:`-onComplete-java-` is to be expe
 
 Example
 -------
-TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/FutureDirectivesExamplesTest.java#onCompleteWithBreaker

akka-docs/rst/scala/code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala

@@ -10,8 +10,8 @@ import docs.http.scaladsl.server.RoutingSpec
 
 import scala.concurrent.Future
 import scala.concurrent.duration._
-import scala.util.{Failure, Success}
-import akka.http.scaladsl.server.{CircuitBreakerOpenRejection, ExceptionHandler, Route}
+import scala.util.{ Failure, Success }
+import akka.http.scaladsl.server.{ CircuitBreakerOpenRejection, ExceptionHandler, Route }
 import akka.util.Timeout
 import akka.http.scaladsl.model._
 import StatusCodes._