raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Merge pull request #18727 from 2m/wip-coding-directives

Browse source 
=doc #18496 add scala docs for coding directives
This commit is contained in:
Konrad Malawski 2015-10-14 16:54:35 +02:00
commit 99158f515c
7 changed files with 42 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

13
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/decodeRequest.rst
View file

@ -3,9 +3,6 @@
decodeRequest
=============
Tries to decode the request with the specified ``Decoder`` or rejects the request with an
``UnacceptedRequestEncodingRejection(supportedEncoding)``.
Signature
---------
@ -15,16 +12,10 @@ Signature
Description
-----------
The ``decodeRequest`` directive is the building block for the ``decompressRequest`` directive.
``decodeRequest`` and ``decompressRequest`` are related like this::
decompressRequest(Gzip) = decodeRequest(Gzip)
decompressRequest(a, b, c) = decodeRequest(a) | decodeRequest(b) | decodeRequest(c)
decompressRequest() = decodeRequest(Gzip) | decodeRequest(Deflate) | decodeRequest(NoEncoding)
Decompresses the incoming request if it is ``gzip`` or ``deflate`` compressed. Uncompressed requests are passed through untouched. If the request encoded with another encoding the request is rejected with an ``UnsupportedRequestEncodingRejection``.
Example
-------
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
:snippet: decodeRequest
:snippet: "decodeRequest"

6
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/decodeRequestWith.rst
View file

@ -3,8 +3,6 @@
decodeRequestWith
=================
...
Signature
---------
@ -14,10 +12,10 @@ Signature
Description
-----------
...
Decodes the incoming request if it is encoded with one of the given encoders. If the request encoding doesn't match one of the given encoders the request is rejected with an ``UnsupportedRequestEncodingRejection``. If no decoders are given the default encoders (``Gzip``, ``Deflate``, ``NoCoding``) are used.
Example
-------
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
:snippet: 0decodeRequestWith
:snippet: decodeRequestWith

23
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponse.rst
View file

@ -3,9 +3,6 @@
encodeResponse
==============
Tries to encode the response with the specified ``Encoder`` or rejects the request with an
``UnacceptedResponseEncodingRejection(supportedEncodings)``.
Signature
---------
@ -15,24 +12,16 @@ Signature
Description
-----------
The directive automatically applies the ``autoChunkFileBytes`` directive as well to avoid having to load
an entire file into JVM heap.
Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` header or rejects the request with an ``UnacceptedResponseEncodingRejection(supportedEncodings)``.
The parameter to the directive is either just an ``Encoder`` or all of an ``Encoder``, a threshold, and a
chunk size to configure the automatically applied ``autoChunkFileBytes`` directive.
The response encoding is determined by the rules specified in RFC7231_.
The ``encodeResponse`` directive is the building block for the ``compressResponse`` and
``compressResponseIfRequested`` directives.
``encodeResponse``, ``compressResponse``, and ``compressResponseIfRequested`` are related like this::
compressResponse(Gzip) = encodeResponse(Gzip)
compressResponse(a, b, c) = encodeResponse(a) | encodeResponse(b) | encodeResponse(c)
compressResponse() = encodeResponse(Gzip) | encodeResponse(Deflate) | encodeResponse(NoEncoding)
compressResponseIfRequested() = encodeResponse(NoEncoding) | encodeResponse(Gzip) | encodeResponse(Deflate)
If the ``Accept-Encoding`` header is missing or empty or specifies an encoding other than identity, gzip or deflate then no encoding is used.
Example
-------
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
:snippet: encodeResponse
:snippet: "encodeResponse"
.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

13
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst
View file

@ -3,8 +3,6 @@
encodeResponseWith
==================
...
Signature
---------
@ -14,10 +12,19 @@ Signature
Description
-----------
...
Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` if it is among the provided encoders or rejects the request with an ``UnacceptedResponseEncodingRejection(supportedEncodings)``.
The response encoding is determined by the rules specified in RFC7231_.
If the ``Accept-Encoding`` header is missing then the response is encoded using the ``first`` encoder.
If the ``Accept-Encoding`` header is empty and ``NoCoding`` is part of the encoders then no
response encoding is used. Otherwise the request is rejected.
Example
-------
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
:snippet: encodeResponseWith
.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

9
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/requestEncodedWith.rst
View file

@ -3,9 +3,6 @@
requestEncodedWith
==================
Passes the request to the inner route if the request is encoded with the argument encoding. Otherwise,
rejects the request with an ``UnacceptedRequestEncodingRejection(encoding)``.
Signature
---------
@ -15,4 +12,8 @@ Signature
Description
-----------
This directive is the building block for ``decodeRequest`` to reject unsupported encodings.
Passes the request to the inner route if the request is encoded with the argument encoding. Otherwise, rejects the request with an ``UnacceptedRequestEncodingRejection(encoding)``.
This directive is the `building block`_ for ``decodeRequest`` to reject unsupported encodings.
.. _`building block`: @github@/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala

11
akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/responseEncodingAccepted.rst
View file

@ -3,9 +3,6 @@
responseEncodingAccepted
========================
Passes the request to the inner route if the request accepts the argument encoding. Otherwise,
rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
Signature
---------
@ -15,4 +12,10 @@ Signature
Description
-----------
This directive is the building block for ``encodeResponse`` to reject unsupported encodings.
Passes the request to the inner route if the request accepts the argument encoding. Otherwise, rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
Example
-------
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
:snippet: responseEncodingAccepted