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

!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

2
akka-docs/rst/scala/http/client-side/connection-level.rst
View file

@ -70,7 +70,7 @@ It should be noted that Akka Streams provide various timeout functionality so an
from the stream stages such as ``idleTimeout``, ``backpressureTimeout``, ``completionTimeout``, ``initialTimeout``
and ``throttle``. To learn more about these refer to their documentation in Akka Streams (and Scala Doc).
For more details about timeout support in Akka HTTP in general refer to :ref:`http-timeouts`.
For more details about timeout support in Akka HTTP in general refer to :ref:`http-timeouts-scala`.
.. _http-client-layer:

4
akka-docs/rst/scala/http/common/http-model.rst
View file

@ -77,7 +77,7 @@ as shown here the Akka HTTP model defines a number of subclasses of ``HttpEntity
stream of bytes.
.. _HttpEntity:
.. _HttpEntity-scala:
HttpEntity
----------
@ -257,7 +257,7 @@ Transfer-Encoding
response will not be rendered onto the wire and trigger a warning being logged instead!
Content-Length
The content length of a message is modelled via its :ref:`HttpEntity`. As such no ``Content-Length`` header will ever
The content length of a message is modelled via its :ref:`HttpEntity-scala`. As such no ``Content-Length`` header will ever
be part of a message's ``header`` sequence.
Similarly, a ``Content-Length`` header instance that is explicitly added to the ``headers`` of a request or
response will not be rendered onto the wire and trigger a warning being logged instead!

4
akka-docs/rst/scala/http/common/index.rst
View file

@ -1,4 +1,4 @@
.. _http-scala-common:
.. _http-scala-common-scala:
Common Abstractions (Client- and Server-Side)
=============================================
@ -19,4 +19,4 @@ which are specific to one side only.
de-coding
json-support
xml-support
timeouts
timeouts

6
akka-docs/rst/scala/http/common/timeouts.rst
View file

@ -1,4 +1,4 @@
.. _http-timeouts:
.. _http-timeouts-scala:
Akka HTTP Timeouts
==================
@ -32,7 +32,7 @@ independently for each of those using the following keys::
Server timeouts
---------------
.. _request-timeout:
.. _request-timeout-scala:
Request timeout
^^^^^^^^^^^^^^^
@ -73,4 +73,4 @@ The connecting timeout is the time period within which the TCP connecting proces
Tweaking it should rarely be required, but it allows erroring out the connection in case a connection
is unable to be established for a given amount of time.
it can be configured using the ``akka.http.client.connecting-timeout`` setting.
it can be configured using the ``akka.http.client.connecting-timeout`` setting.

2
akka-docs/rst/scala/http/common/xml-support.rst
View file

@ -28,4 +28,4 @@ Once you have done this (un)marshalling between XML and ``NodeSeq`` instances sh
.. _Scala XML: https://github.com/scala/scala-xml
.. _ScalaXmlSupport: @github@/akka-http-marshallers-scala/akka-http-xml/src/main/scala/akka/http/scaladsl/marshallers/xml/ScalaXmlSupport.scala
.. _ScalaXmlSupport: @github@/akka-http-marshallers-scala/akka-http-xml/src/main/scala/akka/http/scaladsl/marshallers/xml/ScalaXmlSupport.scala

1
akka-docs/rst/scala/http/index.rst
View file

@ -14,3 +14,4 @@ Akka HTTP
client-side/index
server-side-https-support
migration-from-spray
migration-from-old-http-javadsl

2
akka-docs/rst/scala/http/low-level-server-side-api.rst
View file

@ -118,7 +118,7 @@ Streaming Request/Response Entities
Streaming of HTTP message entities is supported through subclasses of ``HttpEntity``. The application needs to be able
to deal with streamed entities when receiving a request as well as, in many cases, when constructing responses.
See :ref:`HttpEntity` for a description of the alternatives.
See :ref:`HttpEntity-scala` for a description of the alternatives.
If you rely on the :ref:`http-marshalling-scala` and/or :ref:`http-unmarshalling-scala` facilities provided by
Akka HTTP then the conversion of custom types to and from streamed entities can be quite convenient.

63
akka-docs/rst/scala/http/migration-from-old-http-javadsl.rst Normal file
View file

@ -0,0 +1,63 @@
.. _http-javadsl-migration-guide:
Migration Guide from "old" HTTP JavaDSL
=======================================
The so-called "old" JavaDSL for Akka HTTP was initially developed during the project's experimental phase,
and thanks to multiple user comments and contributions we were able to come up with a more Java 8 "feel",
which at the same time is also closer to the existing ScalaDSL.
The previous DSL has been entirely removed and replaced with the the so-called "new" one.
Upgrading to the new DSL is **highly encouraged** since the old one not only was rather hard to work with,
it actually was not possible to express many typical use-cases using it.
The most major changes include:
HttpApp is gone
---------------
``HttpApp`` (a helper class containing a ``main()`` implementation) is gone, as we would like to encourage understanding
how the various elements of the API fit together.
Instead developers should start applications "manually", by converting a ``Route`` to a ``Flow<HttpRequest, HttpResponse, ?>``
using the ``Route.flow`` method. For examples of full apps refer to :ref:`http-testkit-java`.
``RequestVal`` is gone
----------------------
The old API heavily relied on the concept of "request values" which could be used to extract a value from a request context.
Based on community feedback and our own experience we found them too hard to work with in more complex settings.
The concept of a request value has been completely removed, and replaced with proper "directives", exacly like in the ScalaDSL.
**Previously**::
RequestVal<Host> host = Headers.byClass(Host.class).instance();
final Route route =
route(
handleWith1(host, (ctx, h) ->
ctx.complete(String.format("Host header was: %s", h.host()))
)
);
**Now**::
final Route route =
headerValueByType(Host.class, host -> complete("Host was: " + host));
All of ScalaDSL routing has corresponding JavaDSL
-------------------------------------------------
Both ``Route``, ``RouteResult`` and other important core concepts such as ``Rejections`` are now modeled 1:1 with Scala,
making is much simpler to understand one API based on the other one – tremendously useful when learning about some nice
pattern from blogs which used Scala, yet need to apply it in Java and the other way around.
It is now possible to implement marshallers using Java. Refer to :ref:`marshalling-java` for details.
Migration help
--------------
As always, feel free to reach out via the `akka-user <https://groups.google.com/forum/#!searchin/akka-user/>`_ mailing list or gitter channels,
to seek help or guidance when migrating from the old APIs.
For Lightbend subscription owners it is possible to reach out to the core team for help in the migration by asking specific
questions via the `Lightbend customer portal <https://portal.lightbend.com/>`_.

2
akka-docs/rst/scala/http/routing-dsl/case-class-extraction.rst
View file

@ -10,7 +10,7 @@ Consider this example:
.. includecode2:: ../../code/docs/http/scaladsl/server/CaseClassExtractionExamplesSpec.scala
:snippet: example-1
Here the :ref:`-parameters-` directives is employed to extract three ``Int`` values, which are then used to construct an
Here the :ref:`-parameters-scala-` directives is employed to extract three ``Int`` values, which are then used to construct an
instance of the ``Color`` case class. So far so good. However, if the model classes we'd like to work with have more
than just a few parameters the overhead introduced by capturing the arguments as extractions only to feed them into the
model class constructor directly afterwards can somewhat clutter up your route definitions.

8
akka-docs/rst/scala/http/routing-dsl/directives/alphabetically.rst
View file

@ -64,7 +64,7 @@ Directive Description
:ref:`-failWith-` Bubbles the given error up the response chain where it is dealt with by the
closest :ref:`-handleExceptions-` directive and its ``ExceptionHandler``
:ref:`-fileUpload-` Provides a stream of an uploaded file from a multipart request
:ref:`-formField-` Extracts an HTTP form field from the request
:ref:`-formField-scala-` Extracts an HTTP form field from the request
:ref:`-formFieldMap-` Extracts a number of HTTP form field from the request as
a ``Map[String, String]``
:ref:`-formFieldMultiMap-` Extracts a number of HTTP form field from the request as
@ -150,7 +150,7 @@ Directive Description
:ref:`-parameter-` Extracts a query parameter value from the request
:ref:`-parameterMap-` Extracts the request's query parameters as a ``Map[String, String]``
:ref:`-parameterMultiMap-` Extracts the request's query parameters as a ``Map[String, List[String]]``
:ref:`-parameters-` Extracts a number of query parameter values from the request
:ref:`-parameters-scala-` Extracts a number of query parameter values from the request
:ref:`-parameterSeq-` Extracts the request's query parameters as a ``Seq[(String, String)]``
:ref:`-pass-` Always simply passes the request on to its inner route, i.e. doesn't do
anything, neither with the request nor the response
@ -211,13 +211,13 @@ Directive Description
:ref:`-tprovide-` Injects a given tuple of values into a directive
:ref:`-uploadedFile-` Streams one uploaded file from a multipart request to a file on disk
:ref:`-validate-` Checks a given condition before running its inner route
:ref:`-withoutRequestTimeout-` Disables :ref:`request timeouts <request-timeout>` for a given route.
:ref:`-withoutRequestTimeout-` Disables :ref:`request timeouts <request-timeout-scala>` for a given route.
:ref:`-withExecutionContext-` Runs its inner route with the given alternative ``ExecutionContext``
:ref:`-withMaterializer-` Runs its inner route with the given alternative ``Materializer``
:ref:`-withLog-` Runs its inner route with the given alternative ``LoggingAdapter``
:ref:`-withRangeSupport-` Adds ``Accept-Ranges: bytes`` to responses to GET requests, produces partial
responses if the initial request contained a valid ``Range`` header
:ref:`-withRequestTimeout-` Configures the :ref:`request timeouts <request-timeout>` for a given route.
:ref:`-withRequestTimeout-` Configures the :ref:`request timeouts <request-timeout-scala>` for a given route.
:ref:`-withRequestTimeoutResponse-` Prepares the ``HttpResponse`` that is emitted if a request timeout is triggered.
``RequestContext => RequestContext`` function
:ref:`-withSettings-` Runs its inner route with the given alternative ``RoutingSettings``

2
akka-docs/rst/scala/http/routing-dsl/directives/form-field-directives/formField.rst
View file

@ -1,4 +1,4 @@
.. _-formField-:
.. _-formField-scala-:
formField
=========

4
akka-docs/rst/scala/http/routing-dsl/directives/form-field-directives/formFields.rst
View file

@ -52,9 +52,9 @@ instance.
Requests missing a required field or field value will be rejected with an appropriate rejection.
There's also a singular version, :ref:`-formField-`.
There's also a singular version, :ref:`-formField-scala-`.
Query parameters can be handled in a similar way, see :ref:`-parameters-`.
Query parameters can be handled in a similar way, see :ref:`-parameters-scala-`.
Unmarshalling
-------------

20
akka-docs/rst/scala/http/routing-dsl/directives/parameter-directives/index.rst
View file

@ -17,19 +17,19 @@ ParameterDirectives
When to use which parameter directive?
--------------------------------------
Usually, you want to use the high-level :ref:`-parameters-` directive. When you need
Usually, you want to use the high-level :ref:`-parameters-scala-` directive. When you need
more low-level access you can use the table below to decide which directive
to use which shows properties of different parameter directives.
========================== ====== ======== =====
directive level ordering multi
========================== ====== ======== =====
:ref:`-parameter-` high no no
:ref:`-parameters-` high no yes
:ref:`-parameterMap-` low no no
:ref:`-parameterMultiMap-` low no yes
:ref:`-parameterSeq-` low yes yes
========================== ====== ======== =====
================================ ====== ======== =====
directive level ordering multi
================================ ====== ======== =====
:ref:`-parameter-` high no no
:ref:`-parameters-scala-` high no yes
:ref:`-parameterMap-` low no no
:ref:`-parameterMultiMap-` low no yes
:ref:`-parameterSeq-` low yes yes
================================ ====== ======== =====
level
high-level parameter directives extract subset of all parameters by name and allow conversions

2
akka-docs/rst/scala/http/routing-dsl/directives/parameter-directives/parameter.rst
View file

@ -13,7 +13,7 @@ Description
-----------
Extracts a *query* parameter value from the request.
See :ref:`-parameters-` for a detailed description of this directive.
See :ref:`-parameters-scala-` for a detailed description of this directive.
See :ref:`which-parameter-directive` to understand when to use which directive.

2
akka-docs/rst/scala/http/routing-dsl/directives/parameter-directives/parameters.rst
View file

@ -1,4 +1,4 @@
.. _-parameters-:
.. _-parameters-scala-:
parameters
==========

4
akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.rst
View file

@ -12,7 +12,7 @@ Signature
Description
-----------
This directive enables "late" (during request processing) control over the :ref:`request-timeout` feature in Akka HTTP.
This directive enables "late" (during request processing) control over the :ref:`request-timeout-scala` feature in Akka HTTP.
The timeout can be either loosened or made more tight using this directive, however one should be aware that it is
inherently racy (which may especially show with very tight timeouts) since a timeout may already have been triggered
@ -35,7 +35,7 @@ See also :ref:`-withRequestTimeoutResponse-` if only looking to customise the ti
It is recommended to use a larger statically configured timeout (think of it as a "safety net" against programming errors
or malicious attackers) and if needed tighten it using the directives – not the other way around.
For more information about various timeouts in Akka HTTP see :ref:`http-timeouts`.
For more information about various timeouts in Akka HTTP see :ref:`http-timeouts-scala`.
Example
-------

4
akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.rst
View file

@ -12,7 +12,7 @@ Signature
Description
-----------
Allows customising the ``HttpResponse`` that will be sent to clients in case of a :ref:`request-timeout`.
Allows customising the ``HttpResponse`` that will be sent to clients in case of a :ref:`request-timeout-scala`.
See also :ref:`-withRequestTimeout-` or :ref:`-withoutRequestTimeout-` if interested in dynamically changing the timeout
for a given route instead.
@ -25,7 +25,7 @@ for a given route instead.
In practice this can only be a problem with very tight timeouts, so with default settings
of request timeouts being measured in seconds it shouldn't be a problem in reality (though certainly a possibility still).
To learn more about various timeouts in Akka HTTP and how to configure them see :ref:`http-timeouts`.
To learn more about various timeouts in Akka HTTP and how to configure them see :ref:`http-timeouts-scala`.
Example
-------

4
akka-docs/rst/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.rst
View file

@ -12,7 +12,7 @@ Signature
Description
-----------
This directive enables "late" (during request processing) control over the :ref:`request-timeout` feature in Akka HTTP.
This directive enables "late" (during request processing) control over the :ref:`request-timeout-scala` feature in Akka HTTP.
It is not recommended to turn off request timeouts using this method as it is inherently racy and disabling request timeouts
basically turns off the safety net against programming mistakes that it provides.
@ -22,7 +22,7 @@ basically turns off the safety net against programming mistakes that it provides
we're measuring the timeout" is already in the past (the moment we started handling the request), so if the existing
timeout already was triggered before your directive had the chance to change it, an timeout may still be logged.
For more information about various timeouts in Akka HTTP see :ref:`http-timeouts`.
For more information about various timeouts in Akka HTTP see :ref:`http-timeouts-scala`.
Example
-------