diff --git a/akka-docs-dev/rst/java/http/client-side/host-level.rst b/akka-docs-dev/rst/java/http/client-side/host-level.rst index d647ed4ab6..51fe6d3e12 100644 --- a/akka-docs-dev/rst/java/http/client-side/host-level.rst +++ b/akka-docs-dev/rst/java/http/client-side/host-level.rst @@ -80,6 +80,10 @@ response with its respective request. The way that this is done is by allowing t This context object of type ``T`` is completely opaque to Akka HTTP, i.e. you can pick whatever works best for your particular application scenario. +.. note:: + A consequence of using a pool is that long-running requests block a connection while running and may starve other + requests. Make sure not to use a connection pool for long-running requests like long-polling GET requests. + Use the :ref:`connection-level-api-java` instead. Connection Allocation Logic --------------------------- diff --git a/akka-docs-dev/rst/java/http/client-side/request-level.rst b/akka-docs-dev/rst/java/http/client-side/request-level.rst index 3c54a2a0b6..9c00c71d7b 100644 --- a/akka-docs-dev/rst/java/http/client-side/request-level.rst +++ b/akka-docs-dev/rst/java/http/client-side/request-level.rst @@ -7,6 +7,10 @@ The request-level API is the most convenient way of using Akka HTTP's client-sid :ref:`host-level-api-java` to provide you with a simple and easy-to-use way of retrieving HTTP responses from remote servers. Depending on your preference you can pick the flow-based or the future-based variant. +.. note:: + The request-level API is implemented on top of a connection pool that is shared inside the ActorSystem. A consequence of + using a pool is that long-running requests block a connection while running and starve other requests. Make sure not to use + the request-level API for long-running requests like long-polling GET requests. Use the :ref:`connection-level-api-java` instead. Flow-Based Variant ------------------ diff --git a/akka-docs-dev/rst/java/http/http-model.rst b/akka-docs-dev/rst/java/http/http-model.rst index 07dca91e1f..ce52320bfb 100644 --- a/akka-docs-dev/rst/java/http/http-model.rst +++ b/akka-docs-dev/rst/java/http/http-model.rst @@ -159,6 +159,29 @@ entity regardless of its concrete subtype. Therefore you must make sure that you always consume the entity data, even in the case that you are not actually interested in it! +Special processing for HEAD requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`RFC 7230`_ defines very clear rules for the entity length of HTTP messages. + +Especially this rule requires special treatment in Akka HTTP: + + Any response to a HEAD request and any response with a 1xx + (Informational), 204 (No Content), or 304 (Not Modified) status + code is always terminated by the first empty line after the + header fields, regardless of the header fields present in the + message, and thus cannot contain a message body. + +Responses to HEAD requests introduce the complexity that `Content-Length` or `Transfer-Encoding` headers +can be present but the entity is empty. This is modeled by allowing `HttpEntityDefault` and `HttpEntityChunked` +to be used for HEAD responses with an empty data stream. + +Also, when a HEAD response has an `HttpEntityCloseDelimited` entity the Akka HTTP implementation will *not* close the +connection after the response has been sent. This allows the sending of HEAD responses without `Content-Length` +header across persistent HTTP connections. + +.. _RFC 7230: http://tools.ietf.org/html/rfc7230#section-3.3.3 + Header Model ------------ diff --git a/akka-docs-dev/rst/java/http/routing-dsl/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/index.rst index 430cf5469e..311915951b 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/index.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/index.rst @@ -15,4 +15,4 @@ To use the high-level API you need to add a dependency to the ``akka-http-experi handlers marshalling testkit - json-jackson-support \ No newline at end of file + json-support \ No newline at end of file diff --git a/akka-docs-dev/rst/java/http/routing-dsl/json-jackson-support.rst b/akka-docs-dev/rst/java/http/routing-dsl/json-support.rst similarity index 59% rename from akka-docs-dev/rst/java/http/routing-dsl/json-jackson-support.rst rename to akka-docs-dev/rst/java/http/routing-dsl/json-support.rst index 13bde7fb36..6052d3d58f 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/json-jackson-support.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/json-support.rst @@ -1,10 +1,22 @@ +.. _json-support-java: + +Json Support +============ + +akka-http provides support to convert application-domain objects from and to JSON using jackson_ in an +extra artifact. + +Integration with other JSON libraries may be supported by the community. +See `the list of current community extensions for Akka HTTP`_. + +.. _`the list of current community extensions for Akka HTTP`: http://akka.io/community/#extensions-to-akka-http + .. _json-jackson-support-java: Json Support via Jackson -======================== +------------------------ -akka-http provides support to convert application-domain objects from and to JSON using jackson_. To make use -of the support module, you need to add a dependency on `akka-http-jackson-experimental`. +To make use of the support module, you need to add a dependency on `akka-http-jackson-experimental`. Use ``akka.http.javadsl.marshallers.jackson.Jackson.jsonAs[T]`` to create a ``RequestVal`` which expects the request body to be of type ``application/json`` and converts it to ``T`` using Jackson. 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 242b2ebca9..01675807b9 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 @@ -79,6 +79,10 @@ response with its respective request. The way that this is done is by allowing t This context object of type ``T`` is completely opaque to Akka HTTP, i.e. you can pick whatever works best for your particular application scenario. +.. note:: + A consequence of using a pool is that long-running requests block a connection while running and may starve other + requests. Make sure not to use a connection pool for long-running requests like long-polling GET requests. + Use the :ref:`connection-level-api` instead. Connection Allocation Logic --------------------------- 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 1f4c62ea11..c862b6fc82 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 @@ -7,6 +7,10 @@ The request-level API is the most convenient way of using Akka HTTP's client-sid :ref:`host-level-api` to provide you with a simple and easy-to-use way of retrieving HTTP responses from remote servers. Depending on your preference you can pick the flow-based or the future-based variant. +.. note:: + The request-level API is implemented on top of a connection pool that is shared inside the ActorSystem. A consequence of + using a pool is that long-running requests block a connection while running and starve other requests. Make sure not to use + the request-level API for long-running requests like long-polling GET requests. Use the :ref:`connection-level-api` instead. Flow-Based Variant ------------------ diff --git a/akka-docs-dev/rst/scala/http/common/http-model.rst b/akka-docs-dev/rst/scala/http/common/http-model.rst index 4679c7ffac..39dbd13d79 100644 --- a/akka-docs-dev/rst/scala/http/common/http-model.rst +++ b/akka-docs-dev/rst/scala/http/common/http-model.rst @@ -156,6 +156,28 @@ concrete subtype. Therefore you must make sure that you always consume the entity data, even in the case that you are not actually interested in it! +Special processing for HEAD requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`RFC 7230`_ defines very clear rules for the entity length of HTTP messages. + +Especially this rule requires special treatment in Akka HTTP: + + Any response to a HEAD request and any response with a 1xx + (Informational), 204 (No Content), or 304 (Not Modified) status + code is always terminated by the first empty line after the + header fields, regardless of the header fields present in the + message, and thus cannot contain a message body. + +Responses to HEAD requests introduce the complexity that `Content-Length` or `Transfer-Encoding` headers +can be present but the entity is empty. This is modeled by allowing `HttpEntity.Default` and `HttpEntity.Chunked` +to be used for HEAD responses with an empty data stream. + +Also, when a HEAD response has an `HttpEntity.CloseDelimited` entity the Akka HTTP implementation will *not* close the +connection after the response has been sent. This allows the sending of HEAD responses without `Content-Length` +header across persistent HTTP connections. + +.. _RFC 7230: http://tools.ietf.org/html/rfc7230#section-3.3.3 Header Model ------------ diff --git a/akka-docs-dev/rst/scala/http/common/json-support.rst b/akka-docs-dev/rst/scala/http/common/json-support.rst index cdfc292333..697005c0f3 100644 --- a/akka-docs-dev/rst/scala/http/common/json-support.rst +++ b/akka-docs-dev/rst/scala/http/common/json-support.rst @@ -8,6 +8,10 @@ XML or even binary encodings. For JSON Akka HTTP currently provides support for `spray-json`_ right out of the box through it's ``akka-http-spray-json`` module. +Other JSON libraries are supported by the community. +See `the list of current community extensions for Akka HTTP`_. + +.. _`the list of current community extensions for Akka HTTP`: http://akka.io/community/#extensions-to-akka-http spray-json Support ------------------ @@ -29,4 +33,4 @@ Once you have done this (un)marshalling between JSON and your type ``T`` should .. _spray-json: https://github.com/spray/spray-json -.. _SprayJsonSupport: @github@/akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala \ No newline at end of file +.. _SprayJsonSupport: @github@/akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala diff --git a/akka-docs-dev/rst/scala/http/index.rst b/akka-docs-dev/rst/scala/http/index.rst index 154f89b34c..c3488266a9 100644 --- a/akka-docs-dev/rst/scala/http/index.rst +++ b/akka-docs-dev/rst/scala/http/index.rst @@ -8,8 +8,8 @@ Akka HTTP introduction configuration - client-side/index + common/index low-level-server-side-api routing-dsl/index - common/index + client-side/index migration-from-spray