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

!htp #18919 #19519 New JavaDSL for Akka HTTP (#20518)

Browse source 
* !htt #18919 #19519 Align Java HTTP server DSL with Scala

This commits replaces the Java HTTP server DSL with a Java-8 centric one
which exposes all scala DSL concepts to be usable from Java, including
custom directives, (un)marshallers, rejections, headers, and type safety
for path and query parameters.

* Add RequestContext and RouteResult to Java DSL
fix websockets
WIP bring java docs up to date.
This applies some updates to the root-level documentation

* [htp] Fix java documentation to correctly mention timeouts

Timeouts are configured the same in Java and Scala. Hence, linking to the
scala docs for timeouts from Java.

* =htc fix optionalHeaderValueByType in Java

* =htt #20200 fix java testkit always using NoLogging instead logger

* +htt actually run new javadsl tests, allow overriding config

* =htt improve javadsl test infra with more details when fails

* =htt fix bug in wrong path matcher exposed

* +htp add missing remaining path matcher

* =htp Java DSL cookie tests fixed

* =htt Java DSL ParameterDirectivesTest fixed

Protect the tweets from scalariform

Incorrect response expectations in cache condition directives spec fixed

* =htt Path directives for Java DSL

* +!htt PathMatchers rewritten, made uniform and tests passing

* Bugfix in java reject and a little test-boyscouting

* Revert "Incorrect response expectations in cache condition directives spec fixed"

This reverts commit cd50e89d45db010309f8249b090ea654ebb11c7a.

* +htc HttpAPIsTest is compile time only, not for running
Also, moved from the client package since not strictly a client test.

SecurityDirectives passing

Two faulty tests and two actual bugs.

Fix for cache condition spec not working

* Not sending in Unit instad of the implicit magnet in the test
* HeaderMagnet now works as expected
* Java API added for - and + on DateTime

PetStore example and test fixed

* Annotations to make marshalling work without default constructor
* Made model class immutable

Incorrect tests fixed

Some scaladoc boyscouting as bonus

* =htt RequestValTest sprinkled out across multiple directive tests

Client ip extraction test with incorrect header name fixed.

* =htt Incorrect CodingDirectivesTest fixed.

* =htt Bugfix for Java Unmarshaller.firstOf and fixes to JavaRouteTest

* =htt MarshallerTest fixed

* Missing seal signature added to JavaDSL
* More consistent (with Scala) test kit setup for Java
* missing Javadocs added
* Thread.sleep in default exception handler removed

* =htt copy directive docs, prepare for finishing it up

* +htt SecurityDirectives.authorize variants and test coverage added

* +htt Custom headers in Java DSL

* =htt WIP on java docs

* +htp add missing parameterOrDefault directive
Fixed a lot of doc warnings

* =htc intense progress on javadsl docs

* =htc #20470 Link to issue about docs and fix compile error
compile, migration guide
don't mima check http-experimental

* =htt Java DSL doc warnings fixed.
Only `Could not lex literal_block` ones left now

* =htc fix mima settings

* =doc fix MethodDirectives doc test with custom method

* =htc fix coding directives spec after bad merge

* =htc fix concat being corresponding to route() in javadsl

* =htt Disable consistency check for route/concat as it fails only on ci server

* !htt Minor fixes to PathMatchers
This commit is contained in:
Johan Andrén 2016-05-16 10:38:40 +02:00 • committed by Konrad Malawski
parent 094c8974ed
commit 29029be31d
381 changed files with 12616 additions and 6630 deletions
Download patch file Download diff file Expand all files Collapse all files

148
akka-docs/rst/java/http/routing-dsl/directives/alphabetically.rst Normal file
View file

@ -0,0 +1,148 @@
.. _Predefined Directives-java:
Predefined Directives (alphabetically)
======================================
================================================ ============================================================================
Directive Description
================================================ ============================================================================
:ref:`-authenticateBasic-java-` Wraps the inner route with Http Basic authentication support using a given ``Authenticator<T>``
:ref:`-authenticateBasicAsync-java-` Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticator<T>``
:ref:`-authenticateBasicPF-java-` Wraps the inner route with Http Basic authentication support using a given ``AuthenticatorPF<T>``
:ref:`-authenticateBasicPFAsync-java-` Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticatorPF<T>``
:ref:`-authenticateOAuth2-java-` Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF<T>``
:ref:`-authenticateOAuth2Async-java-` Wraps the inner route with OAuth Bearer Token authentication support using a given ``AsyncAuthenticator<T>``
:ref:`-authenticateOAuth2PF-java-` Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF<T>``
:ref:`-authenticateOAuth2PFAsync-java-` Wraps the inner route with OAuth Bearer Token authentication support using a given ``AsyncAuthenticatorPF<T>``
:ref:`-authenticateOrRejectWithChallenge-java-` Lifts an authenticator function into a directive
:ref:`-authorize-java-` Applies the given authorization check to the request
:ref:`-authorizeAsync-java-` Applies the given asynchronous authorization check to the request
:ref:`-cancelRejection-java-` Adds a ``TransformationRejection`` cancelling all rejections equal to the given one to the rejections potentially coming back from the inner route.
:ref:`-cancelRejections-java-` Adds a ``TransformationRejection`` cancelling all matching rejections to the rejections potentially coming back from the inner route
:ref:`-complete-java-` Completes the request using the given arguments
:ref:`-completeOrRecoverWith-java-` "Unwraps" a ``CompletionStage<T>`` and runs the inner route when the future has failed with the error as an extraction of type ``Throwable``
:ref:`-completeWith-java-` Uses the marshaller for a given type to extract a completion function
:ref:`-conditional-java-` Wraps its inner route with support for conditional requests as defined by http://tools.ietf.org/html/rfc7232
:ref:`-cookie-java-` Extracts the ``HttpCookie`` with the given name
:ref:`-decodeRequest-java-` Decompresses the request if it is ``gzip`` or ``deflate`` compressed
:ref:`-decodeRequestWith-java-` Decodes the incoming request using one of the given decoders
:ref:`-delete-java-` Rejects all non-DELETE requests
:ref:`-deleteCookie-java-` Adds a ``Set-Cookie`` response header expiring the given cookies
:ref:`-encodeResponse-java-` Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` header (``NoCoding``, ``Gzip`` and ``Deflate``)
:ref:`-encodeResponseWith-java-` Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` header (from a user-defined set)
:ref:`-entity-java-` Extracts the request entity unmarshalled to a given type
:ref:`-extract-java-` Extracts a single value using a ``RequestContext ⇒ T`` function
:ref:`-extractClientIP-java-` Extracts the client's IP from either the ``X-Forwarded-``, ``Remote-Address`` or ``X-Real-IP`` header
:ref:`-extractCredentials-java-` Extracts the potentially present ``HttpCredentials`` provided with the request's ``Authorization`` header
:ref:`-extractExecutionContext-java-` Extracts the ``ExecutionContext`` from the ``RequestContext``
:ref:`-extractMaterializer-java-` Extracts the ``Materializer`` from the ``RequestContext``
:ref:`-extractHost-java-` Extracts the hostname part of the Host request header value
:ref:`-extractLog-java-` Extracts the ``LoggingAdapter`` from the ``RequestContext``
:ref:`-extractMethod-java-` Extracts the request method
:ref:`-extractRequest-java-` Extracts the current ``HttpRequest`` instance
:ref:`-extractRequestContext-java-` Extracts the ``RequestContext`` itself
:ref:`-extractScheme-java-` Extracts the URI scheme from the request
:ref:`-extractSettings-java-` Extracts the ``RoutingSettings`` from the ``RequestContext``
:ref:`-extractUnmatchedPath-java-` Extracts the yet unmatched path from the ``RequestContext``
:ref:`-extractUri-java-` Extracts the complete request URI
:ref:`-failWith-java-` Bubbles the given error up the response chain where it is dealt with by the closest :ref:`-handleExceptions-java-` directive and its ``ExceptionHandler``
:ref:`-fileUpload-java-` Provides a stream of an uploaded file from a multipart request
:ref:`-formField-java-` Extracts an HTTP form field from the request
:ref:`-formFieldMap-java-` Extracts a number of HTTP form field from the request as a ``Map<String, String>``
:ref:`-formFieldMultiMap-java-` Extracts a number of HTTP form field from the request as a ``Map<String, List<String>``
:ref:`-formFieldList-java-` Extracts a number of HTTP form field from the request as a ``List<Pair<String, String>>``
:ref:`-get-java-` Rejects all non-GET requests
:ref:`-getFromBrowseableDirectories-java-` Serves the content of the given directories as a file-system browser, i.e. files are sent and directories served as browseable listings
:ref:`-getFromBrowseableDirectory-java-` Serves the content of the given directory as a file-system browser, i.e. files are sent and directories served as browseable listings
:ref:`-getFromDirectory-java-` Completes GET requests with the content of a file underneath a given file-system directory
:ref:`-getFromFile-java-` Completes GET requests with the content of a given file
:ref:`-getFromResource-java-` Completes GET requests with the content of a given class-path resource
:ref:`-getFromResourceDirectory-java-` Completes GET requests with the content of a file underneath a given "class-path resource directory"
:ref:`-handleExceptions-java-` Transforms exceptions thrown during evaluation of the inner route using the given ``ExceptionHandler``
:ref:`-handleRejections-java-` Transforms rejections produced by the inner route using the given ``RejectionHandler``
:ref:`-handleWebSocketMessages-java-` Handles websocket requests with the given handler and rejects other requests with an ``ExpectedWebSocketRequestRejection``
:ref:`-handleWebSocketMessagesForProtocol-java-` Handles websocket requests with the given handler if the subprotocol matches and rejects other requests with an ``ExpectedWebSocketRequestRejection`` or an ``UnsupportedWebSocketSubprotocolRejection``.
:ref:`-handleWith-java-` Completes the request using a given function
:ref:`-head-java-` Rejects all non-HEAD requests
:ref:`-headerValue-java-` Extracts an HTTP header value using a given ``HttpHeader ⇒ Option<T>`` function
:ref:`-headerValueByName-java-` Extracts the value of the first HTTP request header with a given name
:ref:`-headerValueByType-java-` Extracts the first HTTP request header of the given type
:ref:`-headerValuePF-java-` Extracts an HTTP header value using a given ``PartialFunction<HttpHeader, T>``
:ref:`-host-java-` Rejects all requests with a non-matching host name
:ref:`-listDirectoryContents-java-` Completes GET requests with a unified listing of the contents of all given file-system directories
:ref:`-logRequest-java-` Produces a log entry for every incoming request
:ref:`-logRequestResult-java-` Produces a log entry for every incoming request and ``RouteResult``
:ref:`-logResult-java-` Produces a log entry for every ``RouteResult``
:ref:`-mapInnerRoute-java-` Transforms its inner ``Route`` with a ``Route => Route`` function
:ref:`-mapRejections-java-` Transforms rejections from a previous route with an ``List<Rejection] ⇒ List<Rejection>`` function
:ref:`-mapRequest-java-` Transforms the request with an ``HttpRequest => HttpRequest`` function
:ref:`-mapRequestContext-java-` Transforms the ``RequestContext`` with a ``RequestContext => RequestContext`` function
:ref:`-mapResponse-java-` Transforms the response with an ``HttpResponse => HttpResponse`` function
:ref:`-mapResponseEntity-java-` Transforms the response entity with an ``ResponseEntity ⇒ ResponseEntity`` function
:ref:`-mapResponseHeaders-java-` Transforms the response headers with an ``List<HttpHeader] ⇒ List<HttpHeader>`` function
:ref:`-mapRouteResult-java-` Transforms the ``RouteResult`` with a ``RouteResult ⇒ RouteResult`` function
:ref:`-mapRouteResultFuture-java-` Transforms the ``RouteResult`` future with a ``CompletionStage<RouteResult] ⇒ CompletionStage<RouteResult>`` function
:ref:`-mapRouteResultPF-java-` Transforms the ``RouteResult`` with a ``PartialFunction<RouteResult, RouteResult>``
:ref:`-mapRouteResultWith-java-` Transforms the ``RouteResult`` with a ``RouteResult ⇒ CompletionStage<RouteResult>`` function
:ref:`-mapRouteResultWithPF-java-` Transforms the ``RouteResult`` with a ``PartialFunction<RouteResult, CompletionStage<RouteResult]>``
:ref:`-mapSettings-java-` Transforms the ``RoutingSettings`` with a ``RoutingSettings ⇒ RoutingSettings`` function
: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:`-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
:ref:`-optionalHeaderValueByName-java-` Extracts the value of the first optional HTTP request header with a given name
:ref:`-optionalHeaderValueByType-java-` Extracts the first optional HTTP request header of the given type
:ref:`-optionalHeaderValuePF-java-` Extracts an optional HTTP header value using a given ``PartialFunction<HttpHeader, T>``
:ref:`-options-java-` Rejects all non-OPTIONS requests
:ref:`-overrideMethodWithParameter-java-` Changes the request method to the value of the specified query parameter
:ref:`-parameter-java-` Extracts a query parameter value from the request
:ref:`-parameterMap-java-` Extracts the request's query parameters as a ``Map<String, String>``
:ref:`-parameterMultiMap-java-` Extracts the request's query parameters as a ``Map<String, List<String>>``
:ref:`-parameterList-java-` Extracts the request's query parameters as a ``Seq<Pair<String, String>>``
:ref:`-pass-java-` Always simply passes the request on to its inner route, i.e. doesn't do anything, neither with the request nor the response
:ref:`-patch-java-` Rejects all non-PATCH requests
:ref:`-path-java-` Applies the given ``PathMatcher`` to the remaining unmatched path after consuming a leading slash
:ref:`-pathEnd-java-` Only passes on the request to its inner route if the request path has been matched completely
:ref:`-pathEndOrSingleSlash-java-` Only passes on the request to its inner route if the request path has been matched completely or only consists of exactly one remaining slash
:ref:`-pathPrefix-java-` Applies the given ``PathMatcher`` to a prefix of the remaining unmatched path after consuming a leading slash
:ref:`-pathPrefixTest-java-` Checks whether the unmatchedPath has a prefix matched by the given ``PathMatcher`` after implicitly consuming a leading slash
:ref:`-pathSingleSlash-java-` Only passes on the request to its inner route if the request path consists of exactly one remaining slash
:ref:`-pathSuffix-java-` Applies the given ``PathMatcher`` to a suffix of the remaining unmatched path (Caution: check java!)
:ref:`-pathSuffixTest-java-` Checks whether the unmatched path has a suffix matched by the given ``PathMatcher`` (Caution: check java!)
:ref:`-post-java-` Rejects all non-POST requests
:ref:`-provide-java-` Injects a given value into a directive
:ref:`-put-java-` Rejects all non-PUT requests
:ref:`-rawPathPrefix-java-` Applies the given matcher directly to a prefix of the unmatched path of the ``RequestContext``, without implicitly consuming a leading slash
:ref:`-rawPathPrefixTest-java-` Checks whether the unmatchedPath has a prefix matched by the given ``PathMatcher``
:ref:`-recoverRejections-java-` Transforms rejections from the inner route with an ``List<Rejection] ⇒ RouteResult`` function
:ref:`-recoverRejectionsWith-java-` Transforms rejections from the inner route with an ``List<Rejection] ⇒ CompletionStage<RouteResult>`` function
:ref:`-redirect-java-` Completes the request with redirection response of the given type to the given URI
:ref:`-redirectToNoTrailingSlashIfPresent-java-` If the request path ends with a slash, redirects to the same uri without trailing slash in the path
:ref:`-redirectToTrailingSlashIfMissing-java-` If the request path doesn't end with a slash, redirects to the same uri with trailing slash in the path
:ref:`-reject-java-` Rejects the request with the given rejections
:ref:`-rejectEmptyResponse-java-` Converts responses with an empty entity into (empty) rejections
:ref:`-requestEncodedWith-java-` Rejects the request with an ``UnsupportedRequestEncodingRejection`` if its encoding doesn't match the given one
:ref:`-requestEntityEmpty-java-` Rejects if the request entity is non-empty
:ref:`-requestEntityPresent-java-` Rejects with a ``RequestEntityExpectedRejection`` if the request entity is empty
:ref:`-respondWithDefaultHeader-java-` Adds a given response header if the response doesn't already contain a header with the same name
:ref:`-respondWithDefaultHeaders-java-` Adds the subset of the given headers to the response which doesn't already have a header with the respective name present in the response
:ref:`-respondWithHeader-java-` Unconditionally adds a given header to the outgoing response
:ref:`-respondWithHeaders-java-` Unconditionally adds the given headers to the outgoing response
:ref:`-responseEncodingAccepted-java-` Rejects the request with an ``UnacceptedResponseEncodingRejection`` if the given response encoding is not accepted by the client
:ref:`-scheme-java-` Rejects all requests whose URI scheme doesn't match the given one
:ref:`-selectPreferredLanguage-java-` Inspects the request's ``Accept-Language`` header and determines, which of a given set of language alternatives is preferred by the client
:ref:`-setCookie-java-` Adds a ``Set-Cookie`` response header with the given cookies
:ref:`-uploadedFile-java-` Streams one uploaded file from a multipart request to a file on disk
:ref:`-validate-java-` Checks a given condition before running its inner route
:ref:`-withoutRequestTimeout-java-` Disables :ref:`request timeouts <request-timeout-java>` for a given route.
:ref:`-withExecutionContext-java-` Runs its inner route with the given alternative ``ExecutionContext``
:ref:`-withMaterializer-java-` Runs its inner route with the given alternative ``Materializer``
:ref:`-withLog-java-` Runs its inner route with the given alternative ``LoggingAdapter``
:ref:`-withRangeSupport-java-` Adds ``Accept-Ranges: bytes`` to responses to GET requests, produces partial responses if the initial request contained a valid ``Range`` header
:ref:`-withRequestTimeout-java-` Configures the :ref:`request timeouts <request-timeout-java>` for a given route.
:ref:`-withRequestTimeoutResponse-java-` Prepares the ``HttpResponse`` that is emitted if a request timeout is triggered. ``RequestContext => RequestContext`` function
:ref:`-withSettings-java-` Runs its inner route with the given alternative ``RoutingSettings``
================================================ ============================================================================

19
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/cancelRejection.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-cancelRejection-java-:
cancelRejection
===============
Description
-----------
Adds a ``TransformationRejection`` cancelling all rejections equal to the
given one to the rejections potentially coming back from the inner route.
Read :ref:`rejections-java` to learn more about rejections.
For more advanced handling of rejections refer to the :ref:`-handleRejections-java-` directive
which provides a nicer DSL for building rejection handlers.
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>`_.

21
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/cancelRejections.rst Normal file
View file

@ -0,0 +1,21 @@
.. _-cancelRejections-java-:
cancelRejections
================
Description
-----------
Adds a ``TransformationRejection`` cancelling all rejections created by the inner route for which
the condition argument function returns ``true``.
See also :ref:`-cancelRejection-java-`, for canceling a specific rejection.
Read :ref:`rejections-java` to learn more about rejections.
For more advanced handling of rejections refer to the :ref:`-handleRejections-java-` directive
which provides a nicer DSL for building rejection handlers.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extract.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-extract-java-:
extract
=======
Description
-----------
The ``extract`` directive is used as a building block for :ref:`Custom Directives-java` to extract data from the
``RequestContext`` and provide it to the inner route.
See :ref:`ProvideDirectives-java` for an overview of similar directives.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractExecutionContext.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-extractExecutionContext-java-:
extractExecutionContext
=======================
Description
-----------
Extracts the ``ExecutionContext`` from the ``RequestContext``.
See :ref:`-withExecutionContext-java-` to see how to customise the execution context provided for an inner route.
See :ref:`-extract-java-` to learn more about how extractions work.
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>`_.

18
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractLog.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-extractLog-java-:
extractLog
==========
Description
-----------
Extracts a :class:`LoggingAdapter` from the request context which can be used for logging inside the route.
The ``extractLog`` directive is used for providing logging to routes, such that they don't have to depend on
closing over a logger provided in the class body.
See :ref:`-extract-java-` and :ref:`ProvideDirectives-java` for an overview of similar directives.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractMaterializer.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-extractMaterializer-java-:
extractMaterializer
===================
Description
-----------
Extracts the ``Materializer`` from the ``RequestContext``, which can be useful when you want to run an
Akka Stream directly in your route.
See also :ref:`-withMaterializer-java-` to see how to customise the used materializer for specific inner routes.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractRequest.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-extractRequest-java-:
extractRequest
==============
Description
-----------
Extracts the complete ``HttpRequest`` instance.
Use ``extractRequest`` to extract just the complete URI of the request. Usually there's little use of
extracting the complete request because extracting of most of the aspects of HttpRequests is handled by specialized
directives. See :ref:`Request Directives-java`.
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractRequestContext.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-extractRequestContext-java-:
extractRequestContext
=====================
Description
-----------
Extracts the request's underlying :class:`RequestContext`.
This directive is used as a building block for most of the other directives,
which extract the context and by inspecting some of it's values can decide
what to do with the request - for example provide a value, or reject the request.
See also :ref:`-extractRequest-java-` if only interested in the :class:`HttpRequest` instance itself.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractSettings.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-extractSettings-java-:
extractSettings
===============
Description
-----------
Extracts the :class:`RoutingSettings` from the :class:`RequestContext`.
By default the settings of the ``Http()`` extension running the route will be returned.
It is possible to override the settings for specific sub-routes by using the :ref:`-withSettings-java-` directive.
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>`_.

18
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractUnmatchedPath.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-extractUnmatchedPath-java-:
extractUnmatchedPath
====================
Description
-----------
Extracts the unmatched path from the request context.
The ``extractUnmatchedPath`` directive extracts the remaining path that was not yet matched by any of the :ref:`PathDirectives-java`
(or any custom ones that change the unmatched path field of the request context). You can use it for building directives
that handle complete suffixes of paths (like the ``getFromDirectory`` directives and similar ones).
Use ``mapUnmatchedPath`` to change the value of the unmatched path.
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>`_.

15
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/extractUri.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-extractUri-java-:
extractUri
==========
Description
-----------
Access the full URI of the request.
Use :ref:`SchemeDirectives-java`, :ref:`HostDirectives-java`, :ref:`PathDirectives-java`, and :ref:`ParameterDirectives-java` for more
targeted access to parts of the URI.
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>`_.

123
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/index.rst Normal file
View file

@ -0,0 +1,123 @@
.. _BasicDirectives-java:
BasicDirectives
===============
Basic directives are building blocks for building :ref:`Custom Directives`. As such they
usually aren't used in a route directly but rather in the definition of new directives.
.. _ProvideDirectives-java:
Providing Values to Inner Routes
--------------------------------
These directives provide values to the inner routes with extractions. They can be distinguished
on two axes: a) provide a constant value or extract a value from the ``RequestContext`` b) provide
a single value or a tuple of values.
* :ref:`-extract-java-`
* :ref:`-extractExecutionContext-java-`
* :ref:`-extractMaterializer-java-`
* :ref:`-extractLog-java-`
* :ref:`-extractRequest-java-`
* :ref:`-extractRequestContext-java-`
* :ref:`-extractSettings-java-`
* :ref:`-extractUnmatchedPath-java-`
* :ref:`-extractUri-java-`
* :ref:`-provide-java-`
.. _Request Transforming Directives-java:
Transforming the Request(Context)
---------------------------------
* :ref:`-mapRequest-java-`
* :ref:`-mapRequestContext-java-`
* :ref:`-mapSettings-java-`
* :ref:`-mapUnmatchedPath-java-`
* :ref:`-withExecutionContext-java-`
* :ref:`-withMaterializer-java-`
* :ref:`-withLog-java-`
* :ref:`-withSettings-java-`
.. _Response Transforming Directives-java:
Transforming the Response
-------------------------
These directives allow to hook into the response path and transform the complete response or
the parts of a response or the list of rejections:
* :ref:`-mapResponse-java-`
* :ref:`-mapResponseEntity-java-`
* :ref:`-mapResponseHeaders-java-`
.. _Result Transformation Directives-java:
Transforming the RouteResult
----------------------------
These directives allow to transform the RouteResult of the inner route.
* :ref:`-cancelRejection-java-`
* :ref:`-cancelRejections-java-`
* :ref:`-mapRejections-java-`
* :ref:`-mapRouteResult-java-`
* :ref:`-mapRouteResultFuture-java-`
* :ref:`-mapRouteResultPF-java-`
* :ref:`-mapRouteResultWith-java-`
* :ref:`-mapRouteResultWithPF-java-`
* :ref:`-recoverRejections-java-`
* :ref:`-recoverRejectionsWith-java-`
Other
-----
* :ref:`-mapInnerRoute-java-`
* :ref:`-pass-java-`
Alphabetically
--------------
.. toctree::
:maxdepth: 1
cancelRejection
cancelRejections
extract
extractExecutionContext
extractMaterializer
extractLog
extractRequest
extractRequestContext
extractSettings
extractUnmatchedPath
extractUri
mapInnerRoute
mapRejections
mapRequest
mapRequestContext
mapResponse
mapResponseEntity
mapResponseHeaders
mapRouteResult
mapRouteResultFuture
mapRouteResultPF
mapRouteResultWith
mapRouteResultWithPF
mapSettings
mapUnmatchedPath
pass
provide
recoverRejections
recoverRejectionsWith
withExecutionContext
withMaterializer
withLog
withSettings

15
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapInnerRoute.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-mapInnerRoute-java-:
mapInnerRoute
=============
Description
-----------
Changes the execution model of the inner route by wrapping it with arbitrary logic.
The ``mapInnerRoute`` directive is used as a building block for :ref:`Custom Directives-java` to replace the inner route
with any other route. Usually, the returned route wraps the original one with custom execution logic.
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRejections.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-mapRejections-java-:
mapRejections
=============
Description
-----------
**Low level directive** – unless you're sure you need to be working on this low-level you might instead
want to try the :ref:`-handleRejections-java-` directive which provides a nicer DSL for building rejection handlers.
The ``mapRejections`` directive is used as a building block for :ref:`Custom Directives-java` to transform a list
of rejections from the inner route to a new list of rejections.
See :ref:`Response Transforming Directives-java` for similar directives.
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRequest.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-mapRequest-java-:
mapRequest
==========
Description
-----------
Transforms the request before it is handled by the inner route.
The ``mapRequest`` directive is used as a building block for :ref:`Custom Directives-java` to transform a request before it
is handled by the inner route. Changing the ``request.uri`` parameter has no effect on path matching in the inner route
because the unmatched path is a separate field of the ``RequestContext`` value which is passed into routes. To change
the unmatched path or other fields of the ``RequestContext`` use the :ref:`-mapRequestContext-java-` directive.
See :ref:`Request Transforming Directives-java` for an overview of similar directives.
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>`_.

18
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRequestContext.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-mapRequestContext-java-:
mapRequestContext
=================
Description
-----------
Transforms the ``RequestContext`` before it is passed to the inner route.
The ``mapRequestContext`` directive is used as a building block for :ref:`Custom Directives-java` to transform
the request context before it is passed to the inner route. To change only the request value itself the
:ref:`-mapRequest-java-` directive can be used instead.
See :ref:`Request Transforming Directives-java` for an overview of similar directives.
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>`_.

21
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapResponse.rst Normal file
View file

@ -0,0 +1,21 @@
.. _-mapResponse-java-:
mapResponse
===========
Description
-----------
The ``mapResponse`` directive is used as a building block for :ref:`Custom Directives-java` to transform a response that
was generated by the inner route. This directive transforms complete responses.
See also :ref:`-mapResponseHeaders-java-` or :ref:`-mapResponseEntity-java-` for more specialized variants and
:ref:`Response Transforming Directives-java` for similar directives.
Example: Override status
------------------------
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>`_.
Example: Default to empty JSON response on errors
-------------------------------------------------
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapResponseEntity.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-mapResponseEntity-java-:
mapResponseEntity
=================
Description
-----------
The ``mapResponseEntity`` directive is used as a building block for :ref:`Custom Directives-java` to transform a
response entity that was generated by the inner route.
See :ref:`Response Transforming Directives-java` for similar directives.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapResponseHeaders.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-mapResponseHeaders-java-:
mapResponseHeaders
==================
Description
-----------
Changes the list of response headers that was generated by the inner route.
The ``mapResponseHeaders`` directive is used as a building block for :ref:`Custom Directives-java` to transform the list of
response headers that was generated by the inner route.
See :ref:`Response Transforming Directives-java` for similar directives.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRouteResult.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-mapRouteResult-java-:
mapRouteResult
==============
Description
-----------
Changes the message the inner route sends to the responder.
The ``mapRouteResult`` directive is used as a building block for :ref:`Custom Directives-java` to transform the
:class:`RouteResult` coming back from the inner route.
See :ref:`Result Transformation Directives-java` for similar directives.
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>`_.

20
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRouteResultFuture.rst Normal file
View file

@ -0,0 +1,20 @@
.. _-mapRouteResultFuture-java-:
mapRouteResultFuture
====================
Description
-----------
Asynchronous version of :ref:`-mapRouteResult-java-`.
It's similar to :ref:`-mapRouteResultWith-java-`, however it's
``Function<CompletionStage<RouteResult>, CompletionStage<RouteResult>>``
instead of ``Function<RouteResult, CompletionStage<RouteResult>>`` which may be useful when
combining multiple transformations and / or wanting to ``recover`` from a failed route result.
See :ref:`Result Transformation Directives-java` for similar directives.
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>`_.

20
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRouteResultPF.rst Normal file
View file

@ -0,0 +1,20 @@
.. _-mapRouteResultPF-java-:
mapRouteResultPF
================
Description
-----------
*Partial Function* version of :ref:`-mapRouteResult-java-`.
Changes the message the inner route sends to the responder.
The ``mapRouteResult`` directive is used as a building block for :ref:`Custom Directives-java` to transform the
:class:`RouteResult` coming back from the inner route. It's similar to the :ref:`-mapRouteResult-java-` directive but allows to
specify a partial function that doesn't have to handle all potential ``RouteResult`` instances.
See :ref:`Result Transformation Directives-java` for similar directives.
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRouteResultWith.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-mapRouteResultWith-java-:
mapRouteResultWith
==================
Description
-----------
Changes the message the inner route sends to the responder.
The ``mapRouteResult`` directive is used as a building block for :ref:`Custom Directives-java` to transform the
:class:`RouteResult` coming back from the inner route. It's similar to the :ref:`-mapRouteResult-java-` directive but
returning a ``CompletionStage`` instead of a result immediately, which may be useful for longer running transformations.
See :ref:`Result Transformation Directives-java` for similar directives.
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>`_.

20
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapRouteResultWithPF.rst Normal file
View file

@ -0,0 +1,20 @@
.. _-mapRouteResultWithPF-java-:
mapRouteResultWithPF
====================
Description
-----------
Asynchronous variant of :ref:`-mapRouteResultPF-java-`.
Changes the message the inner route sends to the responder.
The ``mapRouteResult`` directive is used as a building block for :ref:`Custom Directives-java` to transform the
:class:`RouteResult` coming back from the inner route.
See :ref:`Result Transformation Directives-java` for similar directives.
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>`_.

15
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapSettings.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-mapSettings-java-:
mapSettings
===========
Description
-----------
Transforms the ``RoutingSettings`` with a ``Function<RoutingSettings, RoutingSettings>``.
See also :ref:`-withSettings-java-` or :ref:`-extractSettings-java-`.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/mapUnmatchedPath.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-mapUnmatchedPath-java-:
mapUnmatchedPath
================
Description
-----------
Transforms the unmatchedPath field of the request context for inner routes.
The ``mapUnmatchedPath`` directive is used as a building block for writing :ref:`Custom Directives-java`. You can use it
for implementing custom path matching directives.
Use ``extractUnmatchedPath`` for extracting the current value of the unmatched path.
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>`_.

14
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/pass.rst Normal file
View file

@ -0,0 +1,14 @@
.. _-pass-java-:
pass
====
Description
-----------
A directive that passes the request unchanged to its inner route.
It is usually used as a "neutral element" when combining directives generically.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/provide.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-provide-java-:
provide
=======
Description
-----------
Provides a constant value to the inner route.
The `provide` directive is used as a building block for :ref:`Custom Directives-java` to provide a single value to the
inner route.
See :ref:`ProvideDirectives-java` for an overview of similar directives.
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>`_.

20
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/recoverRejections.rst Normal file
View file

@ -0,0 +1,20 @@
.. _-recoverRejections-java-:
recoverRejections
=================
Description
-----------
**Low level directive** – unless you're sure you need to be working on this low-level you might instead
want to try the :ref:`-handleRejections-java-` directive which provides a nicer DSL for building rejection handlers.
Transforms rejections from the inner route with a ``Function<Iterable<Rejection>, RouteResult>``.
A ``RouteResult`` is either a ``Complete`` containing the ``HttpResponse`` or a ``Rejected`` containing the
rejections.
.. note::
To learn more about how and why rejections work read the :ref:`rejections-java` section of the documentation.
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>`_.

23
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst Normal file
View file

@ -0,0 +1,23 @@
.. _-recoverRejectionsWith-java-:
recoverRejectionsWith
=====================
Description
-----------
**Low level directive** – unless you're sure you need to be working on this low-level you might instead
want to try the :ref:`-handleRejections-java-` directive which provides a nicer DSL for building rejection handlers.
Transforms rejections from the inner route with a ``Function<Iterable<Rejection>, CompletionStage<RouteResult>>``.
Asynchronous version of :ref:`-recoverRejections-java-`.
See :ref:`-recoverRejections-java-` (the synchronous equivalent of this directive) for a detailed description.
.. note::
To learn more about how and why rejections work read the :ref:`rejections-java` section of the documentation.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/withExecutionContext.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-withExecutionContext-java-:
withExecutionContext
====================
Description
-----------
Allows running an inner route using an alternative ``ExecutionContextExecutor`` in place of the default one.
The execution context can be extracted in an inner route using :ref:`-extractExecutionContext-java-` directly,
or used by directives which internally extract the materializer without sufracing this fact in the API.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/withLog.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-withLog-java-:
withLog
=======
Description
-----------
Allows running an inner route using an alternative :class:`LoggingAdapter` in place of the default one.
The logging adapter can be extracted in an inner route using :ref:`-extractLog-java-` directly,
or used by directives which internally extract the materializer without surfacing this fact in the API.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/withMaterializer.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-withMaterializer-java-:
withMaterializer
================
Description
-----------
Allows running an inner route using an alternative ``Materializer`` in place of the default one.
The materializer can be extracted in an inner route using :ref:`-extractMaterializer-java-` directly,
or used by directives which internally extract the materializer without sufracing this fact in the API
(e.g. responding with a Chunked entity).
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/basic-directives/withSettings.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-withSettings-java-:
withSettings
============
Description
-----------
Allows running an inner route using an alternative :class:`RoutingSettings` in place of the default one.
The execution context can be extracted in an inner route using :ref:`-extractSettings-java-` directly,
or used by directives which internally extract the materializer without sufracing this fact in the API.
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>`_.

110
akka-docs/rst/java/http/routing-dsl/directives/by-trait.rst Normal file
View file

@ -0,0 +1,110 @@
Predefined Directives (by trait)
================================
All predefined directives are organized into traits that form one part of the overarching ``Directives`` trait.
.. _Request Directives-java:
Directives filtering or extracting from the request
---------------------------------------------------
:ref:`MethodDirectives-java`
Filter and extract based on the request method.
:ref:`HeaderDirectives-java`
Filter and extract based on request headers.
:ref:`PathDirectives-java`
Filter and extract from the request URI path.
:ref:`HostDirectives-java`
Filter and extract based on the target host.
:ref:`ParameterDirectives-java`, :ref:`FormFieldDirectives-java`
Filter and extract based on query parameters or form fields.
:ref:`CodingDirectives-java`
Filter and decode compressed request content.
:ref:`MarshallingDirectives-java`
Extract the request entity.
:ref:`SchemeDirectives-java`
Filter and extract based on the request scheme.
:ref:`SecurityDirectives-java`
Handle authentication data from the request.
:ref:`CookieDirectives-java`
Filter and extract cookies.
:ref:`BasicDirectives-java` and :ref:`MiscDirectives-java`
Directives handling request properties.
:ref:`FileUploadDirectives-java`
Handle file uploads.
.. _Response Directives-java:
Directives creating or transforming the response
------------------------------------------------
:ref:`CacheConditionDirectives-java`
Support for conditional requests (``304 Not Modified`` responses).
:ref:`CookieDirectives-java`
Set, modify, or delete cookies.
:ref:`CodingDirectives-java`
Compress responses.
:ref:`FileAndResourceDirectives-java`
Deliver responses from files and resources.
:ref:`RangeDirectives-java`
Support for range requests (``206 Partial Content`` responses).
:ref:`RespondWithDirectives-java`
Change response properties.
:ref:`RouteDirectives-java`
Complete or reject a request with a response.
:ref:`BasicDirectives-java` and :ref:`MiscDirectives-java`
Directives handling or transforming response properties.
:ref:`TimeoutDirectives-java`
Configure request timeouts and automatic timeout responses.
List of predefined directives by trait
--------------------------------------
.. toctree::
:maxdepth: 1
basic-directives/index
cache-condition-directives/index
coding-directives/index
cookie-directives/index
debugging-directives/index
execution-directives/index
file-and-resource-directives/index
file-upload-directives/index
form-field-directives/index
future-directives/index
header-directives/index
host-directives/index
marshalling-directives/index
method-directives/index
misc-directives/index
parameter-directives/index
path-directives/index
range-directives/index
respond-with-directives/index
route-directives/index
scheme-directives/index
security-directives/index
websocket-directives/index
timeout-directives/index

33
akka-docs/rst/java/http/routing-dsl/directives/cache-condition-directives/conditional.rst Normal file
View file

@ -0,0 +1,33 @@
.. _-conditional-java-:
conditional
===========
Description
-----------
Wraps its inner route with support for Conditional Requests as defined
by http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26.
Depending on the given ``eTag`` and ``lastModified`` values this directive immediately responds with
``304 Not Modified`` or ``412 Precondition Failed`` (without calling its inner route) if the request comes with the
respective conditional headers. Otherwise the request is simply passed on to its inner route.
The algorithm implemented by this directive closely follows what is defined in `this section`__ of the
`HTTPbis spec`__.
All responses (the ones produces by this directive itself as well as the ones coming back from the inner route) are
augmented with respective ``ETag`` and ``Last-Modified`` response headers.
Since this directive requires the ``EntityTag`` and ``lastModified`` time stamp for the resource as concrete arguments
it is usually used quite deep down in the route structure (i.e. close to the leaf-level), where the exact resource
targeted by the request has already been established and the respective ETag/Last-Modified values can be determined.
The :ref:`FileAndResourceDirectives-java` internally use the ``conditional`` directive for ETag and Last-Modified support
(if the ``akka.http.routing.file-get-conditional`` setting is enabled).
__ http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26#section-6
__ https://datatracker.ietf.org/wg/httpbis/

9
akka-docs/rst/java/http/routing-dsl/directives/cache-condition-directives/index.rst Normal file
View file

@ -0,0 +1,9 @@
.. _CacheConditionDirectives-java:
CacheConditionDirectives
========================
.. toctree::
:maxdepth: 1
conditional

13
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/decodeRequest.rst Normal file
View file

@ -0,0 +1,13 @@
.. _-decodeRequest-java-:
decodeRequest
=============
Description
-----------
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
-------
..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>`_.

13
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/decodeRequestWith.rst Normal file
View file

@ -0,0 +1,13 @@
.. _-decodeRequestWith-java-:
decodeRequestWith
=================
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
-------
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/encodeResponse.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-encodeResponse-java-:
encodeResponse
==============
Description
-----------
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 response encoding is determined by the rules specified in RFC7231_.
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
-------
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>`_.
.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

22
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst Normal file
View file

@ -0,0 +1,22 @@
.. _-encodeResponseWith-java-:
encodeResponseWith
==================
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
-------
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>`_.
.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

14
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/index.rst Normal file
View file

@ -0,0 +1,14 @@
.. _CodingDirectives-java:
CodingDirectives
================
.. toctree::
:maxdepth: 1
decodeRequest
decodeRequestWith
encodeResponse
encodeResponseWith
requestEncodedWith
responseEncodingAccepted

15
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/requestEncodedWith.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-requestEncodedWith-java-:
requestEncodedWith
==================
Description
-----------
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.
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>`_.

13
akka-docs/rst/java/http/routing-dsl/directives/coding-directives/responseEncodingAccepted.rst Normal file
View file

@ -0,0 +1,13 @@
.. _-responseEncodingAccepted-java-:
responseEncodingAccepted
========================
Description
-----------
Passes the request to the inner route if the request accepts the argument encoding. Otherwise, rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/cookie-directives/cookie.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-cookie-java-:
cookie
======
Description
-----------
Extracts a cookie with a given name from a request or otherwise rejects the request with a ``MissingCookieRejection`` if
the cookie is missing.
Use the :ref:`-optionalCookie-java-` directive instead if you want to support missing cookies in your inner route.
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>`_.

14
akka-docs/rst/java/http/routing-dsl/directives/cookie-directives/deleteCookie.rst Normal file
View file

@ -0,0 +1,14 @@
.. _-deleteCookie-java-:
deleteCookie
============
Description
-----------
Adds a header to the response to request the removal of the cookie with the given name on the client.
Use the :ref:`-setCookie-java-` directive to update a cookie.
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>`_.

12
akka-docs/rst/java/http/routing-dsl/directives/cookie-directives/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. _CookieDirectives-java:
CookieDirectives
================
.. toctree::
:maxdepth: 1
cookie
deleteCookie
optionalCookie
setCookie

15
akka-docs/rst/java/http/routing-dsl/directives/cookie-directives/optionalCookie.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-optionalCookie-java-:
optionalCookie
==============
Description
-----------
Extracts an optional cookie with a given name from a request.
Use the :ref:`-cookie-java-` directive instead if the inner route does not handle a missing cookie.
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>`_.

15
akka-docs/rst/java/http/routing-dsl/directives/cookie-directives/setCookie.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-setCookie-java-:
setCookie
=========
Description
-----------
Adds a header to the response to request the update of the cookie with the given name on the client.
Use the :ref:`-deleteCookie-java-` directive to delete a cookie.
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>`_.

35
akka-docs/rst/java/http/routing-dsl/directives/custom-directives.rst Normal file
View file

@ -0,0 +1,35 @@
.. _Custom Directives-java:
Custom Directives
=================
Part of the power of akka-http directives comes from the ease with which it’s possible to define
custom directives at differing levels of abstraction.
There are essentially three ways of creating custom directives:
1. By introducing new “labels” for configurations of existing directives
2. By transforming existing directives
3. By writing a directive “from scratch”
Configuration Labeling
______________________
The easiest way to create a custom directive is to simply assign a new name for a certain configuration
of one or more existing directives. In fact, most of the predefined akka-http directives can be considered
named configurations of more low-level directives.
The basic technique is explained in the chapter about Composing Directives, where, for example, a new directive
``getOrPut`` is defined like this:
.. includecode2:: ../../../code/docs/http/javadsl/server/directives/CustomDirectivesExamplesTest.java
:snippet: labeling
Multiple directives can be nested to produce a single directive out of multiple like this:
.. includecode2:: ../../../code/docs/http/javadsl/server/directives/CustomDirectivesExamplesTest.java
:snippet: composition
Another example is the :ref:`MethodDirectives-java` which are simply instances of a preconfigured :ref:`-method-java-` directive.
The low-level directives that most often form the basis of higher-level “named configuration” directives are grouped
together in the :ref:`BasicDirectives-java` trait.

11
akka-docs/rst/java/http/routing-dsl/directives/debugging-directives/index.rst Normal file
View file

@ -0,0 +1,11 @@
.. _DebuggingDirectives-java:
DebuggingDirectives
===================
.. toctree::
:maxdepth: 1
logRequest
logRequestResult
logResult

19
akka-docs/rst/java/http/routing-dsl/directives/debugging-directives/logRequest.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-logRequest-java-:
logRequest
==========
Description
-----------
Logs the request. The directive is available with the following parameters:
* A marker to prefix each log message with.
* A log level.
* A function that creates a :class:``LogEntry`` from the :class:``HttpRequest``
Use ``logResult`` for logging the response, or ``logRequestResult`` for logging both.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/debugging-directives/logRequestResult.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-logRequestResult-java-:
logRequestResult
================
Description
-----------
Logs both, the request and the response.
This directive is a combination of :ref:`-logRequest-java-` and :ref:`-logResult-java-`.
See :ref:`-logRequest-java-` for the general description how these directives work.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/debugging-directives/logResult.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-logResult-java-:
logResult
=========
Description
-----------
Logs the response.
See :ref:`-logRequest-java-` for the general description how these directives work.
Use ``logRequest`` for logging the request, or ``logRequestResult`` for logging both.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/execution-directives/handleExceptions.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-handleExceptions-java-:
handleExceptions
================
Description
-----------
Catches exceptions thrown by the inner route and handles them using the specified ``ExceptionHandler``.
Using this directive is an alternative to using a global implicitly defined ``ExceptionHandler`` that
applies to the complete route.
See :ref:`exception-handling-java` for general information about options for handling exceptions.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/execution-directives/handleRejections.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-handleRejections-java-:
handleRejections
================
Description
-----------
Using this directive is an alternative to using a global implicitly defined ``RejectionHandler`` that
applies to the complete route.
See :ref:`rejections-java` for general information about options for handling rejections.
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>`_.

10
akka-docs/rst/java/http/routing-dsl/directives/execution-directives/index.rst Normal file
View file

@ -0,0 +1,10 @@
.. _ExecutionDirectives-java:
ExecutionDirectives
===================
.. toctree::
:maxdepth: 1
handleExceptions
handleRejections

22
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst Normal file
View file

@ -0,0 +1,22 @@
.. _-getFromBrowseableDirectories-java-:
getFromBrowseableDirectories
============================
Description
-----------
The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories
(like ``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``.
Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests.
Use ``getFromBrowseableDirectory`` to serve only one directory.
Use ``getFromDirectory`` if directory browsing isn't required.
For more details refer to :ref:`-getFromBrowseableDirectory-java-`.
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>`_.

43
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst Normal file
View file

@ -0,0 +1,43 @@
.. _-getFromBrowseableDirectory-java-:
getFromBrowseableDirectory
==========================
Description
-----------
The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories (like
``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``.
Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests.
Use ``getFromBrowseableDirectory`` to serve only one directory.
Use ``getFromDirectory`` if directory browsing isn't required.
For more details refer to :ref:`-getFromBrowseableDirectory-java-`.
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>`_.
Default file listing page example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Directives which list directories (e.g. ``getFromBrowsableDirectory``) use an implicit ``DirectoryRenderer``
instance to perfm the actual rendering of the file listing. This rendered can be easily overriden by simply
providing one in-scope for the directives to use, so you can build your custom directory listings.
The default renderer is ``akka.http.scaladsl.server.directives.FileAndResourceDirectives.defaultDirectoryRenderer``,
and renders a listing which looks like this:
.. figure:: ../../../../../images/akka-http-file-listing.png
:scale: 75%
:align: center
Example page rendered by the ``defaultDirectoryRenderer``.
It's possible to turn off rendering the footer stating which version of Akka HTTP is rendering this page by configuring
the ``akka.http.routing.render-vanity-footer`` configuration option to ``off``.

30
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst Normal file
View file

@ -0,0 +1,30 @@
.. _-getFromDirectory-java-:
getFromDirectory
================
Description
-----------
Allows exposing a directory's files for GET requests for its contents.
The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-java-`) of the ``RequestContext`` is first transformed by
the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name.
To serve a single file use :ref:`-getFromFile-java-`.
To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-java-`.
To serve files from a classpath directory use :ref:`-getFromResourceDirectory-java-` instead.
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
.. note::
The file's contents will be read using an Akka Streams `Source` which *automatically uses
a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream.
Note also that thanks to using Akka Streams internally, the file will be served at the highest speed reachable by
the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to
the client.
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>`_.

30
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst Normal file
View file

@ -0,0 +1,30 @@
.. _-getFromFile-java-:
getFromFile
===========
Description
-----------
Allows exposing a file to be streamed to the client issuing the request.
The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-java-`) of the ``RequestContext`` is first transformed by
the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name.
To files from a given directory use :ref:`-getFromDirectory-java-`.
To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-java-`.
To serve files from a classpath directory use :ref:`-getFromResourceDirectory-java-` instead.
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
.. note::
The file's contents will be read using an Akka Streams `Source` which *automatically uses
a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream.
Note also that thanks to using Akka Streams internally, the file will be served at the highest speed reachable by
the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to
the client.
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>`_.

18
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-getFromResource-java-:
getFromResource
===============
Description
-----------
Completes ``GET`` requests with the content of the given classpath resource.
For details refer to :ref:`-getFromFile-java-` which works the same way but obtaining the file from the filesystem
instead of the applications classpath.
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
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>`_.

18
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-getFromResourceDirectory-java-:
getFromResourceDirectory
========================
Description
-----------
Completes ``GET`` requests with the content of the given classpath resource directory.
For details refer to :ref:`-getFromDirectory-java-` which works the same way but obtaining the file from the filesystem
instead of the applications classpath.
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
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>`_.

24
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/index.rst Normal file
View file

@ -0,0 +1,24 @@
.. _FileAndResourceDirectives-java:
FileAndResourceDirectives
=========================
Like the :ref:`RouteDirectives-java` the ``FileAndResourceDirectives`` are somewhat special in akka-http's routing DSL.
Contrary to all other directives they do not produce instances of type ``Directive[L <: HList]`` but rather "plain"
routes of type ``Route``.
The reason is that they are not meant for wrapping an inner route (like most other directives, as intermediate-level
elements of a route structure, do) but rather form the actual route structure **leaves**.
So in most cases the inner-most element of a route structure branch is one of the :ref:`RouteDirectives-java` or
``FileAndResourceDirectives``.
.. toctree::
:maxdepth: 1
getFromBrowseableDirectories
getFromBrowseableDirectory
getFromDirectory
getFromFile
getFromResource
getFromResourceDirectory
listDirectoryContents

23
akka-docs/rst/java/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst Normal file
View file

@ -0,0 +1,23 @@
.. _-listDirectoryContents-java-:
listDirectoryContents
=====================
Description
-----------
Completes GET requests with a unified listing of the contents of all given directories. The actual rendering of the
directory contents is performed by the in-scope ``Marshaller[DirectoryListing]``.
To just serve files use :ref:`-getFromDirectory-java-`.
To serve files and provide a browseable directory listing use :ref:`-getFromBrowseableDirectories-java-` instead.
The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``, you can read more about it in
:ref:`-getFromDirectory-java-` 's documentation.
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
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>`_.

21
akka-docs/rst/java/http/routing-dsl/directives/file-upload-directives/fileUpload.rst Normal file
View file

@ -0,0 +1,21 @@
.. _-fileUpload-java-:
fileUpload
==========
Description
-----------
Simple access to the stream of bytes for a file uploaded as a multipart form together with metadata
about the upload as extracted value.
If there is no field with the given name the request will be rejected, if there are multiple file parts
with the same name, the first one will be used and the subsequent ones ignored.
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>`_.
::
curl --form "csv=@uploadFile.txt" http://<host>:<port>

10
akka-docs/rst/java/http/routing-dsl/directives/file-upload-directives/index.rst Normal file
View file

@ -0,0 +1,10 @@
.. _FileUploadDirectives-java:
FileUploadDirectives
====================
.. toctree::
:maxdepth: 1
uploadedFile
fileUpload

23
akka-docs/rst/java/http/routing-dsl/directives/file-upload-directives/uploadedFile.rst Normal file
View file

@ -0,0 +1,23 @@
.. _-uploadedFile-java-:
uploadedFile
============
Description
-----------
Streams the contents of a file uploaded as a multipart form into a temporary file on disk and provides the file and
metadata about the upload as extracted value.
If there is an error writing to disk the request will be failed with the thrown exception, if there is no field
with the given name the request will be rejected, if there are multiple file parts with the same name, the first
one will be used and the subsequent ones ignored.
.. note::
This directive will stream contents of the request into a file, however one can not start processing these
until the file has been written completely. For streaming APIs it is preferred to use the :ref:`-fileUpload-java-`
directive, as it allows for streaming handling of the incoming data bytes.
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>`_.

11
akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formField.rst Normal file
View file

@ -0,0 +1,11 @@
.. _-formField-java-:
formField
=========
-----------
Allows extracting a single Form field sent in the request.
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>`_.

20
akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldList.rst Normal file
View file

@ -0,0 +1,20 @@
.. _-formFieldList-java-:
formFieldList
=============
Description
-----------
Extracts all HTTP form fields at once in the original order as (name, value) tuples of type ``Map.Entry<String, String>``.
This directive can be used if the exact order of form fields is important or if parameters can occur several times.
Warning
-------
The directive reads all incoming HTT form fields without any configured upper bound.
It means, that requests with form fields holding significant amount of data (ie. during a file upload)
can cause performance issues or even an ``OutOfMemoryError`` s.
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldMap.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-formFieldMap-java-:
formFieldMap
============
Description
-----------
Extracts all HTTP form fields at once as a ``Map<String, String>`` mapping form field names to form field values.
If form data contain a field value several times, the map will contain the last one.
Warning
-------
Use of this directive can result in performance degradation or even in ``OutOfMemoryError`` s.
See :ref:`-formFieldList-java-` for details.
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>`_.

22
akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldMultiMap.rst Normal file
View file

@ -0,0 +1,22 @@
.. _-formFieldMultiMap-java-:
formFieldMultiMap
=================
Description
-----------
Extracts all HTTP form fields at once as a multi-map of type ``Map<String, <List<String>>`` mapping
a form name to a list of all its values.
This directive can be used if form fields can occur several times.
The order of values is *not* specified.
Warning
-------
Use of this directive can result in performance degradation or even in ``OutOfMemoryError`` s.
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>`_.

12
akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. _FormFieldDirectives-java:
FormFieldDirectives
===================
.. toctree::
:maxdepth: 1
formField
formFieldList
formFieldMap
formFieldMultiMap

18
akka-docs/rst/java/http/routing-dsl/directives/future-directives/completeOrRecoverWith.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-completeOrRecoverWith-java-:
completeOrRecoverWith
=====================
Description
-----------
"Unwraps" a ``CompletionStage<T>`` and runs the inner route when the stage has failed
with the stage's failure exception as an extraction of type ``Throwable``.
If the completion stage succeeds the request is completed using the values marshaller
(This directive therefore requires a marshaller for the completion stage value type to be
provided.)
To handle the successful case manually as well, use the :ref:`-onComplete-java-` directive, instead.
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>`_.

14
akka-docs/rst/java/http/routing-dsl/directives/future-directives/index.rst Normal file
View file

@ -0,0 +1,14 @@
.. _FutureDirectives-java:
FuturesDirectives
=================
Future directives can be used to run inner routes once the provided ``Future[T]`` has been completed.
.. toctree::
:maxdepth: 1
onComplete
onSuccess
completeOrRecoverWith

18
akka-docs/rst/java/http/routing-dsl/directives/future-directives/onComplete.rst Normal file
View file

@ -0,0 +1,18 @@
.. _-onComplete-java-:
onComplete
==========
Description
-----------
Evaluates its parameter of type ``CompletionStage<T>``, and once it has been completed, extracts its
result as a value of type ``Try<T>`` and passes it to the inner route. A ``Try<T>`` can either be a ``Success`` containing
the ``T`` value or a ``Failure`` containing the ``Throwable``.
To handle the ``Failure`` case automatically and only work with the result value, use :ref:`-onSuccess-java-`.
To complete with a successful result automatically and just handle the failure result, use :ref:`-completeOrRecoverWith-java-`, instead.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/future-directives/onSuccess.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-onSuccess-java-:
onSuccess
=========
Description
-----------
Evaluates its parameter of type ``CompletionStage<T>``, and once it has been completed successfully,
extracts its result as a value of type ``T`` and passes it to the inner route.
If the future fails its failure throwable is bubbled up to the nearest ``ExceptionHandler``.
To handle the ``Failure`` case manually as well, use :ref:`-onComplete-java-`, instead.
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>`_.

22
akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValue.rst Normal file
View file

@ -0,0 +1,22 @@
.. _-headerValue-java-:
headerValue
===========
Description
-----------
Traverses the list of request headers with the specified function and extracts the first value the function returns as
``Optional[value]``.
The :ref:`-headerValue-java-` directive is a mixture of ``map`` and ``find`` on the list of request headers. The specified function
is called once for each header until the function returns ``Optional(value)``. This value is extracted and presented to the
inner route. If the function throws an exception the request is rejected with a ``MalformedHeaderRejection``. If the
function returns ``Optional.empty`` for every header the request is rejected as "NotFound".
This directive is the basis for building other request header related directives.
See also :ref:`-headerValuePF-java-` for a nicer syntactic alternative.
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>`_.

17
akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValueByName.rst Normal file
View file

@ -0,0 +1,17 @@
.. _-headerValueByName-java-:
headerValueByName
=================
Description
-----------
Extracts the value of the HTTP request header with the given name.
If no header with a matching name is found the request is rejected with a ``MissingHeaderRejection``.
If the header is expected to be missing in some cases or to customize
handling when the header is missing use the :ref:`-optionalHeaderValueByName-java-` directive instead.
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>`_.

22
akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValueByType.rst Normal file
View file

@ -0,0 +1,22 @@
.. _-headerValueByType-java-:
headerValueByType
=================
Description
-----------
Traverses the list of request headers and extracts the first header of the given type.
The ``headerValueByType`` directive finds a header of the given type in the list of request header. If no header of
the given type is found the request is rejected with a ``MissingHeaderRejection``.
If the header is expected to be missing in some cases or to customize handling when the header
is missing use the :ref:`-optionalHeaderValueByType-java-` directive instead.
.. note::
Custom headers will only be matched by this directive if they extend ``ModeledCustomHeader``
from the Scala DSL and there is currently no API for the Java DSL (Ticket #20415)
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValuePF.rst Normal file
View file

@ -0,0 +1,19 @@
.. _-headerValuePF-java-:
headerValuePF
=============
Description
-----------
Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
result of calling the function.
The ``headerValuePF`` directive is an alternative syntax version of :ref:`-headerValue-java-`.
If the function throws an exception the request is rejected with a ``MalformedHeaderRejection``.
If the function is not defined for any header the request is rejected as "NotFound".
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>`_.

19
akka-docs/rst/java/http/routing-dsl/directives/header-directives/index.rst Normal file
View file

@ -0,0 +1,19 @@
.. _HeaderDirectives-java:
HeaderDirectives
================
Header directives can be used to extract header values from the request. To change
response headers use one of the :ref:`RespondWithDirectives-java`.
.. toctree::
:maxdepth: 1
headerValue
headerValueByName
headerValueByType
headerValuePF
optionalHeaderValue
optionalHeaderValueByName
optionalHeaderValueByType
optionalHeaderValuePF

16
akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-optionalHeaderValue-java-:
optionalHeaderValue
===================
Description
-----------
Traverses the list of request headers with the specified function and extracts the first value the function returns as
``Optional[value]``.
The ``optionalHeaderValue`` directive is similar to the :ref:`-headerValue-java-` directive but always extracts an ``Option``
value instead of rejecting the request if no matching header could be found.
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>`_.

15
akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst Normal file
View file

@ -0,0 +1,15 @@
.. _-optionalHeaderValueByName-java-:
optionalHeaderValueByName
=========================
Description
-----------
Optionally extracts the value of the HTTP request header with the given name.
The ``optionalHeaderValueByName`` directive is similar to the :ref:`-headerValueByName-java-` directive but always extracts
an ``Optional`` value instead of rejecting the request if no matching header could be found.
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>`_.

21
akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst Normal file
View file

@ -0,0 +1,21 @@
.. _-optionalHeaderValueByType-java-:
optionalHeaderValueByType
=========================
Description
-----------
Optionally extracts the value of the HTTP request header of the given type.
The ``optionalHeaderValueByType`` directive is similar to the :ref:`-headerValueByType-java-` directive but always extracts
an ``Optional`` value instead of rejecting the request if no matching header could be found.
.. note::
Custom headers will only be matched by this directive if they extend ``ModeledCustomHeader``
from the Scala DSL and there is currently no API for the Java DSL (Ticket #20415)
To learn more about defining custom headers, read: :ref:`custom-headers-scala`.
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>`_.

16
akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst Normal file
View file

@ -0,0 +1,16 @@
.. _-optionalHeaderValuePF-java-:
optionalHeaderValuePF
=====================
Description
-----------
Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
result of calling the function.
The ``optionalHeaderValuePF`` directive is similar to the :ref:`-headerValuePF-java-` directive but always extracts an ``Optional``
value instead of rejecting the request if no matching header could be found.
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>`_.

4
akka-docs/rst/java/http/routing-dsl/directives/host-directives/extractHost.rst → akka-docs/rst/java/http/routing-dsl/directives/host-directives/extractHostName.rst
View file

@ -1,7 +1,7 @@
.. _-extractHost-java-:
RequestVals.host
================
extractHostName
===============
Extract the hostname part of the ``Host`` request header and expose it as a ``String`` extraction
to its inner route.

2
akka-docs/rst/java/http/routing-dsl/directives/host-directives/index.rst
View file

@ -10,6 +10,6 @@ contained in incoming requests as well as extracting its value for usage in inne
:maxdepth: 1
host
extractHost
extractHostName

140
akka-docs/rst/java/http/routing-dsl/directives/index.rst
View file

@ -3,68 +3,86 @@
Directives
==========
A directive is a wrapper for a route or a list of alternative routes that adds one or more of the following
functionality to its nested route(s):
* it filters the request and lets only matching requests pass (e.g. the `get` directive lets only GET-requests pass)
* it modifies the request or the ``RequestContext`` (e.g. the `path` directives filters on the unmatched path and then
passes an updated ``RequestContext`` unmatched path)
* it modifies the response coming out of the nested route
akka-http provides a set of predefined directives for various tasks. You can access them by either extending from
``akka.http.javadsl.server.AllDirectives`` or by importing them statically with
``import static akka.http.javadsl.server.Directives.*;``.
These classes of directives are currently defined:
BasicDirectives
Contains methods to create routes that complete with a static values or allow specifying :ref:`handlers-java` to
process a request.
CacheConditionDirectives
Contains a single directive ``conditional`` that wraps its inner route with support for Conditional Requests as defined
by `RFC 7234`_.
CodingDirectives
Contains directives to decode compressed requests and encode responses.
CookieDirectives
Contains a single directive ``setCookie`` to aid adding a cookie to a response.
ExecutionDirectives
Contains directives to deal with exceptions that occurred during routing.
FileAndResourceDirectives
Contains directives to serve resources from files on the file system or from the classpath.
HostDirectives
Contains directives to filter on the ``Host`` header of the incoming request.
MethodDirectives
Contains directives to filter on the HTTP method of the incoming request.
MiscDirectives
Contains directives that validate a request by user-defined logic.
:ref:`path-directives-java`
Contains directives to match and filter on the URI path of the incoming request.
RangeDirectives
Contains a single directive ``withRangeSupport`` that adds support for retrieving partial responses.
SchemeDirectives
Contains a single directive ``scheme`` to filter requests based on the URI scheme (http vs. https).
WebSocketDirectives
Contains directives to support answering WebSocket requests.
TODO this page should be rewritten as the corresponding Scala page
A "Directive" is a small building block used for creating arbitrarily complex :ref:`route structures <Routes>`.
Akka HTTP already pre-defines a large number of directives and you can easily construct your own:
.. toctree::
:maxdepth: 1
:maxdepth: 1
path-directives
method-directives/index
host-directives/index
alphabetically
by-trait
custom-directives
.. _`RFC 7234`: http://tools.ietf.org/html/rfc7234
Basics
------
:ref:`Routes-java` effectively are simply highly specialised functions that take a ``RequestContext`` and eventually ``complete`` it,
which could (and often should) happen asynchronously.
With the :ref:`-complete-java-` directive this becomes even shorter::
Route route = complete("yeah");
Writing multiple routes that are tried as alternatives (in-order of definition), is as simple as using the ``route(route1, route2)``,
method::
Route routes = route(
pathSingleSlash(() ->
getFromResource("web/calculator.html")
),
path("hello", () -> complete("World!))
);
You could also simply define a "catch all" completion by providing it as the last route to attempt to match.
In the example below we use the ``get()`` (one of the :ref:`MethodDirectives-java`) to match all incoming ``GET``
requests for that route, and all other requests will be routed towards the other "catch all" route, that completes the route::
Route route =
get(
() -> complete("Received GET")
).orElse(
() -> complete("Received something else")
)
If no route matches a given request, a default ``404 Not Found`` response will be returned as response.
Structure
---------
The general anatomy of a directive is as follows::
directiveName(arguments [, ...], (extractions [, ...]) -> {
... // inner route
})
It has a name, zero or more arguments and optionally an inner route (The :ref:`RouteDirectives-java` are special in that they
are always used at the leaf-level and as such cannot have inner routes).
Additionally directives can "extract" a number of values and make them available to their inner routes as function
arguments. When seen "from the outside" a directive with its inner route form an expression of type ``Route``.
What Directives do
------------------
A directive can do one or more of the following:
.. rst-class:: wide
* Transform the incoming ``RequestContext`` before passing it on to its inner route (i.e. modify the request)
* Filter the ``RequestContext`` according to some logic, i.e. only pass on certain requests and reject others
* Extract values from the ``RequestContext`` and make them available to its inner route as "extractions"
* Chain some logic into the :class:`RouteResult` future transformation chain (i.e. modify the response or rejection)
* Complete the request
This means a ``Directive`` completely wraps the functionality of its inner route and can apply arbitrarily complex
transformations, both (or either) on the request and on the response side.
Composing Directives
--------------------
TODO rewrite for Java API

34
akka-docs/rst/java/http/routing-dsl/directives/marshalling-directives/completeWith.rst Normal file
View file

@ -0,0 +1,34 @@
.. _-completeWith-java-:
completeWith
============
Description
-----------
Uses the marshaller for a given type to produce a completion function that is passed to its
inner route. You can use it to decouple marshaller resolution from request completion.
The ``completeWith`` directive works in conjuction with ``instanceOf`` and ``spray.httpx.marshalling``
to convert higher-level (object) structure into some lower-level serialized "wire format".
:ref:`The marshalling documentation <http-marshalling-java>` explains this process in detail.
This directive simplifies exposing types to clients via a route while providing some
form of access to the current context.
``completeWith`` is similar to ``handleWith``. The main difference is with ``completeWith`` you must eventually call
the completion function generated by ``completeWith``. ``handleWith`` will automatically call ``complete`` when the
``handleWith`` function returns.
Examples
--------
The following example uses ``spray-json`` to marshall a simple ``Person`` class to a json
response. It utilizes ``SprayJsonSupport`` via the ``PersonJsonSupport`` object as the in-scope
unmarshaller.
TODO: Add example snippets
The ``findPerson`` takes an argument of type ``Person => Unit`` which is generated by the ``completeWith``
call. We can handle any logic we want in ``findPerson`` and call our completion function to
complete the request.
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>`_.

43
akka-docs/rst/java/http/routing-dsl/directives/marshalling-directives/entity.rst Normal file
View file

@ -0,0 +1,43 @@
.. _-entity-java-:
entity
======
Description
-----------
Unmarshalls the request entity to the given type and passes it to its inner Route. An unmarshaller
returns an ``Either`` with ``Right(value)`` if successful or ``Left(exception)`` for a failure.
The ``entity`` method will either pass the ``value`` to the inner route or map the ``exception`` to a
:class:``akka.http.javadsl.server.Rejection``.
The ``entity`` directive works in conjuction with ``as`` and ``akka.http.scaladsl.unmarshalling`` to
convert some serialized "wire format" value into a higher-level object structure.
:ref:`The unmarshalling documentation <http-unmarshalling-java>` explains this process in detail.
This directive simplifies extraction and error handling to the specified type from the request.
An unmarshaller will return a ``Left(exception)`` in the case of an error. This is converted to a
``akka.http.scaladsl.server.Rejection`` within the ``entity`` directive. The following table lists how exceptions
are mapped to rejections:
========================== ============
Left(exception) Rejection
-------------------------- ------------
``ContentExpected`` ``RequestEntityExpectedRejection``
``UnsupportedContentType`` ``UnsupportedRequestContentTypeRejection``, which lists the supported types
``MaformedContent`` ``MalformedRequestContentRejection``, with an error message and cause
========================== ============
Examples
--------
The following example uses ``spray-json`` to unmarshall a json request into a simple ``Person``
class. It utilizes ``SprayJsonSupport`` via the ``PersonJsonSupport`` object as the in-scope unmarshaller.
TODO: Add example snippets.
It is also possible to use the ``entity`` directive to obtain raw ``JsValue`` ( spray-json_ ) objects, by simply using
``as[JsValue]``, or any other JSON type for which you have marshallers in-scope.
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>`_.
.. _spray-json: https://github.com/spray/spray-json

37
akka-docs/rst/java/http/routing-dsl/directives/marshalling-directives/handleWith.rst Normal file
View file

@ -0,0 +1,37 @@
.. _-handleWith-java-:
handleWith
==========
Description
-----------
Completes the request using the given function. The input to the function is produced with
the in-scope entity unmarshaller and the result value of the function is marshalled with
the in-scope marshaller. ``handleWith`` can be a convenient method combining ``entity`` with
``complete``.
The ``handleWith`` directive is used when you want to handle a route with a given function of
type A ⇒ B. ``handleWith`` will use both an in-scope unmarshaller to convert a request into
type A and an in-scope marshaller to convert type B into a response. This is helpful when your
core business logic resides in some other class or you want your business logic to be independent
of the REST interface written with akka-http. You can use ``handleWith`` to "hand off" processing
to a given function without requiring any akka-http-specific functionality.
``handleWith`` is similar to ``produce``. The main difference is ``handleWith`` automatically
calls ``complete`` when the function passed to ``handleWith`` returns. Using ``produce`` you
must explicity call the completion function passed from the ``produce`` function.
See :ref:`marshalling <http-marshalling-java>` and :ref:`unmarshalling <http-unmarshalling-java>` for guidance
on marshalling entities with akka-http.
Examples
--------
The following example uses an ``updatePerson`` function with a ``Person`` case class as an input and output. We plug this function into our route using ``handleWith``.
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>`_.
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>`_.
The PersonJsonSupport object handles both marshalling and unmarshalling of the Person case class.
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>`_.

34
akka-docs/rst/java/http/routing-dsl/directives/marshalling-directives/index.rst Normal file
View file

@ -0,0 +1,34 @@
.. _MarshallingDirectives-java:
Marshalling Directives
======================
Marshalling directives work in conjunction with ``akka.http.scaladsl.marshalling`` and ``akka.http.scaladsl.unmarshalling`` to convert
a request entity to a specific type or a type to a response.
See :ref:`marshalling <http-marshalling-java>` and :ref:`unmarshalling <http-unmarshalling-java>` for specific
serialization (also known as pickling) guidance.
Marshalling directives usually rely on an in-scope implicit marshaller to handle conversion.
.. toctree::
:maxdepth: 1
completeWith
entity
handleWith
Understanding Specific Marshalling Directives
---------------------------------------------
======================================= =======================================
directive behavior
======================================= =======================================
:ref:`-completeWith-java-` Uses a marshaller for a given type to produce a completion function for an inner route. Used in conjuction with *instanceOf* to format responses.
:ref:`-entity-java-` Unmarshalls the request entity to the given type and passes it to its inner route. Used in conjection with *as* to convert requests to objects.
:ref:`-handleWith-java-` Completes a request with a given function, using an in-scope unmarshaller for an input and in-scope marshaller for the output.
======================================= =======================================

4
akka-docs/rst/java/http/routing-dsl/directives/method-directives/delete.rst
View file

@ -2,9 +2,11 @@
delete
======
Matches requests with HTTP method ``DELETE``.
Description
-----------
This directive filters an incoming request by its HTTP method. Only requests with
method ``DELETE`` are passed on to the inner route. All others are rejected with a
``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response

3
akka-docs/rst/java/http/routing-dsl/directives/method-directives/extractMethod.rst
View file

@ -3,6 +3,9 @@
extractMethod
=============
Description
-----------
Extracts the :class:`HttpMethod` from the request context and provides it for use for other directives explicitly.
Example

4
akka-docs/rst/java/http/routing-dsl/directives/method-directives/get.rst
View file

@ -2,9 +2,11 @@
get
===
Matches requests with HTTP method ``GET``.
Description
-----------
This directive filters the incoming request by its HTTP method. Only requests with
method ``GET`` are passed on to the inner route. All others are rejected with a
``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response

6
akka-docs/rst/java/http/routing-dsl/directives/method-directives/head.rst
View file

@ -2,9 +2,11 @@
head
====
Matches requests with HTTP method ``HEAD``.
Description
-----------
This directive filters the incoming request by its HTTP method. Only requests with
method ``HEAD`` are passed on to the inner route. All others are rejected with a
``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
@ -17,4 +19,4 @@ by the default ``RejectionHandler``.
Example
-------
.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#head
.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#head

2
akka-docs/rst/java/http/routing-dsl/directives/method-directives/index.rst
View file

@ -1,4 +1,4 @@
.. _method-directives-java:
.. _MethodDirectives-java:
MethodDirectives
================

4
akka-docs/rst/java/http/routing-dsl/directives/method-directives/options.rst
View file

@ -2,9 +2,11 @@
options
=======
Matches requests with HTTP method ``OPTIONS``.
Description
-----------
This directive filters the incoming request by its HTTP method. Only requests with
method ``OPTIONS`` are passed on to the inner route. All others are rejected with a
``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response

Some files were not shown because too many files have changed in this diff Show more