Merge pull request #18047 from spray/w/documentation

More documentation bits

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
 ---------------------------

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
 ------------------

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
 ------------

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
+   json-support

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<T>`` which expects the request
 body to be of type ``application/json`` and converts it to ``T`` using Jackson.

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
 ---------------------------

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
 ------------------

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
 ------------

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
+.. _SprayJsonSupport: @github@/akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala

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