+htp #20198 onCompleteWithBreaker directive (#20402)

akka-docs/rst/java/http/routing-dsl/directives/alphabetically.rst

@@ -89,6 +89,7 @@ Directive                                        Description
 :ref:`-mapUnmatchedPath-java-`                   Transforms the ``unmatchedPath`` of the ``RequestContext`` using a ``Uri.Path ⇒ Uri.Path`` function
 :ref:`-method-java-`                             Rejects all requests whose HTTP method does not match the given one
 :ref:`-onComplete-java-`                         "Unwraps" a ``CompletionStage<T>`` and runs the inner route after future completion with the future's value as an extraction of type ``Try<T>``
+:ref:`-onCompleteWithBreaker-java-`              "Unwraps" a ``CompletionStage<T>`` inside a ``CircuitBreaker`` and runs the inner route after future completion with the future's value as an extraction of type ``Try<T>``
 :ref:`-onSuccess-java-`                          "Unwraps" a ``CompletionStage<T>`` and runs the inner route after future completion with the future's value as an extraction of type ``T``
 :ref:`-optionalCookie-java-`                     Extracts the ``HttpCookiePair`` with the given name as an ``Option<HttpCookiePair>``
 :ref:`-optionalHeaderValue-java-`                Extracts an optional HTTP header value using a given ``HttpHeader ⇒ Option<T>`` function

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

@@ -9,6 +9,7 @@ Future directives can be used to run inner routes once the provided ``Future[T]`
    :maxdepth: 1
 
    onComplete
+   onCompleteWithBreaker
    onSuccess
    completeOrRecoverWith
 

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

@@ -0,0 +1,19 @@
+.. _-onCompleteWithBreaker-java-:
+
+onCompleteWithBreaker
+=====================
+
+Description
+-----------
+Evaluates its parameter of type ``CompletionStage<T>`` protecting it with the specified ``CircuitBreaker``.
+Refer to :ref:`Akka Circuit Breaker<circuit-breaker>` for a detailed description of this pattern.
+
+If the ``CircuitBreaker`` is open, the request is rejected with a ``CircuitBreakerOpenRejection``.
+Note that in this case the request's entity databytes stream is cancelled, and the connection is closed
+as a consequence.
+
+Otherwise, the same behaviour provided by :ref:`-onComplete-java-` is to be expected.
+
+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>`_.