diff --git a/akka-docs-dev/rst/scala/http/client-side/connection-level.rst b/akka-docs-dev/rst/scala/http/client-side/connection-level.rst index 9fa26f47e8..73312901af 100644 --- a/akka-docs-dev/rst/scala/http/client-side/connection-level.rst +++ b/akka-docs-dev/rst/scala/http/client-side/connection-level.rst @@ -12,13 +12,13 @@ Opening HTTP Connections ------------------------ With the connection-level API you open a new HTTP connection by materializing a ``Flow`` returned by the -``Http.outgoingConnection(...)`` method. The target endpoint to which a connection is to be opened needs to be -specified as an argument to ``Http.outgoingConnection(...)``. Here is an example: +``Http().outgoingConnection(...)`` method. The target endpoint to which a connection is to be opened needs to be +specified as an argument to ``Http().outgoingConnection(...)``. Here is an example: .. includecode:: ../../code/docs/http/scaladsl/HttpClientExampleSpec.scala :include: outgoing-connection-example -Apart from the host name and port the ``Http.outgoingConnection(...)`` method also allows you to specify socket options +Apart from the host name and port the ``Http().outgoingConnection(...)`` method also allows you to specify socket options and a number of configuration settings for the connection. Note that no connection is attempted until the returned flow is actually materialized! If the flow is materialized diff --git a/akka-docs-dev/rst/scala/http/client-side/host-level.rst b/akka-docs-dev/rst/scala/http/client-side/host-level.rst index 0720c155b9..68230acffa 100644 --- a/akka-docs-dev/rst/scala/http/client-side/host-level.rst +++ b/akka-docs-dev/rst/scala/http/client-side/host-level.rst @@ -11,7 +11,7 @@ host/port combination). Requesting a Host Connection Pool --------------------------------- -The best way to get a hold of a connection pool to a given target endpoint is the ``Http.cachedHostConnectionPool(...)`` +The best way to get a hold of a connection pool to a given target endpoint is the ``Http().cachedHostConnectionPool(...)`` method, which returns a ``Flow`` that can be "baked" into an application-level stream setup. This flow is also called a "pool client flow". @@ -22,7 +22,7 @@ Also, the HTTP layer transparently manages idle shutdown and restarting of conne The client flow instances therefore remain valid throughout the lifetime of the application, i.e. they can be materialized as often as required and the time between individual materialization is of no importance. -When you request a pool client flow with ``Http.cachedHostConnectionPool(...)`` Akka HTTP will immediately start +When you request a pool client flow with ``Http().cachedHostConnectionPool(...)`` Akka HTTP will immediately start the pool, even before the first client flow materialization. However, this running pool will not actually open the first connection to the target endpoint until the first request has arrived. @@ -41,7 +41,7 @@ of the individual pool's ``max-connections`` settings allow! There is one setting that likely deserves a bit deeper explanation: ``max-open-requests``. This setting limits the maximum number of requests that can be open at any time for a single connection pool. -If an application calls ``Http.cachedHostConnectionPool(...)`` 3 times (with the same endpoint and settings) it will get +If an application calls ``Http().cachedHostConnectionPool(...)`` 3 times (with the same endpoint and settings) it will get back 3 different client flow instances for the same pool. If each of these client flows is then materialized 4 times (concurrently) the application will have 12 concurrently running client flow materializations. All of these share the resources of the single pool. @@ -59,7 +59,7 @@ the same pooled connections. Using a Host Connection Pool ---------------------------- -The "pool client flow" returned by ``Http.cachedHostConnectionPool(...)`` has the following type:: +The "pool client flow" returned by ``Http().cachedHostConnectionPool(...)`` has the following type:: Flow[(HttpRequest, T), (Try[HttpResponse], T), HostConnectionPool] @@ -127,16 +127,16 @@ Completing a pool client flow will simply detach the flow from the pool. The con as it may be serving other client flows concurrently or in the future. Only after the configured ``idle-timeout`` for the pool has expired will Akka HTTP automatically terminate the pool and free all its resources. -If a new client flow is requested with ``Http.cachedHostConnectionPool(...)`` or if an already existing client flow is +If a new client flow is requested with ``Http().cachedHostConnectionPool(...)`` or if an already existing client flow is re-materialized the respective pool is automatically and transparently restarted. In addition to the automatic shutdown via the configured idle timeouts it's also possible to trigger the immediate -shutdown of specific pool by calling ``shutdown()`` on the ``Http.HostConnectionPool`` instance that a pool client +shutdown of specific pool by calling ``shutdown()`` on the ``Http().HostConnectionPool`` instance that a pool client flow materializes into. This ``shutdown()`` call produces a ``Future[Unit]`` which is fulfilled when the pool termination has been completed. It's also possible to trigger the immediate termination of *all* connection pools in the ``ActorSystem`` at the same -time by calling ``Http.shutdownAllConnectionPools()``. This call too produces a ``Future[Unit]`` which is fulfilled when +time by calling ``Http().shutdownAllConnectionPools()``. This call too produces a ``Future[Unit]`` which is fulfilled when all pools have terminated. diff --git a/akka-docs-dev/rst/scala/http/client-side/request-level.rst b/akka-docs-dev/rst/scala/http/client-side/request-level.rst index 96f4abfa46..25f3e93e52 100644 --- a/akka-docs-dev/rst/scala/http/client-side/request-level.rst +++ b/akka-docs-dev/rst/scala/http/client-side/request-level.rst @@ -11,11 +11,11 @@ Depending on your preference you can pick the flow-based or the future-based var Flow-Based Variant ------------------ -The flow-based variant of the request-level client-side API is presented by the ``Http.superPool(...)`` method. +The flow-based variant of the request-level client-side API is presented by the ``Http().superPool(...)`` method. It creates a new "super connection pool flow", which routes incoming requests to a (cached) host connection pool depending on their respective effective URI. -The ``Flow`` returned by ``Http.superPool(...)`` is very similar to the one from the :ref:`HostLevelApi`, so the +The ``Flow`` returned by ``Http().superPool(...)`` is very similar to the one from the :ref:`HostLevelApi`, so the :ref:`using-a-host-connection-pool` section also applies here. However, there is one notable difference between a "host connection pool client flow" for the host-level API and a @@ -33,7 +33,7 @@ Future-Based Variant Sometimes your HTTP client needs are very basic. You simply need the HTTP response for a certain request and don't want to bother with setting up a full-blown streaming infrastructure. -For these cases Akka HTTP offers the ``Http.singleRequest(...)`` method, which simply turns an ``HttpRequest`` instance +For these cases Akka HTTP offers the ``Http().singleRequest(...)`` method, which simply turns an ``HttpRequest`` instance into ``Future[HttpResponse]``. Internally the request is dispatched across the (cached) host connection pool for the request's effective URI. diff --git a/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst b/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst index 054a22d397..ffde88505e 100644 --- a/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst +++ b/akka-docs-dev/rst/scala/http/low-level-server-side-api.rst @@ -65,7 +65,7 @@ extension: .. includecode2:: ../code/docs/http/scaladsl/HttpServerExampleSpec.scala :snippet: binding-example -Arguments to the ``Http.bind`` method specify the interface and port to bind to and register interest in handling +Arguments to the ``Http().bind`` method specify the interface and port to bind to and register interest in handling incoming HTTP connections. Additionally, the method also allows for the definition of socket options as well as a larger number of settings for configuring the server according to your needs.