29029be31d
* !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
81 lines
No EOL
4.1 KiB
ReStructuredText
81 lines
No EOL
4.1 KiB
ReStructuredText
.. _connection-level-api-java:
|
|
|
|
Connection-Level Client-Side API
|
|
================================
|
|
|
|
The connection-level API is the lowest-level client-side API Akka HTTP provides. It gives you full control over when
|
|
HTTP connections are opened and closed and how requests are to be send across which connection. As such it offers the
|
|
highest flexibility at the cost of providing the least convenience.
|
|
|
|
|
|
Opening HTTP Connections
|
|
------------------------
|
|
With the connection-level API you open a new HTTP connection to a target endpoint by materializing a ``Flow``
|
|
returned by the ``Http.get(system).outgoingConnection(...)`` method. Here is an example:
|
|
|
|
.. includecode:: ../../code/docs/http/javadsl/HttpClientExampleDocTest.java#outgoing-connection-example
|
|
|
|
Apart from the host name and port the ``Http.get(system).outgoingConnection(...)`` method also allows you to specify socket options
|
|
and a number of configuration settings for the connection.
|
|
|
|
Note that no connection is attempted until the returned flow is actually materialized! If the flow is materialized
|
|
several times then several independent connections will be opened (one per materialization).
|
|
If the connection attempt fails, for whatever reason, the materialized flow will be immediately terminated with a
|
|
respective exception.
|
|
|
|
|
|
Request-Response Cycle
|
|
----------------------
|
|
|
|
Once the connection flow has been materialized it is ready to consume ``HttpRequest`` instances from the source it is
|
|
attached to. Each request is sent across the connection and incoming responses dispatched to the downstream pipeline.
|
|
Of course and as always, back-pressure is adequately maintained across all parts of the
|
|
connection. This means that, if the downstream pipeline consuming the HTTP responses is slow, the request source will
|
|
eventually be slowed down in sending requests.
|
|
|
|
Any errors occurring on the underlying connection are surfaced as exceptions terminating the response stream (and
|
|
canceling the request source).
|
|
|
|
Note that, if the source produces subsequent requests before the prior responses have arrived, these requests will be
|
|
pipelined__ across the connection, which is something that is not supported by all HTTP servers.
|
|
Also, if the server closes the connection before responses to all requests have been received this will result in the
|
|
response stream being terminated with a truncation error.
|
|
|
|
__ http://en.wikipedia.org/wiki/HTTP_pipelining
|
|
|
|
|
|
Closing Connections
|
|
-------------------
|
|
|
|
Akka HTTP actively closes an established connection upon reception of a response containing ``Connection: close`` header.
|
|
The connection can also be closed by the server.
|
|
|
|
An application can actively trigger the closing of the connection by completing the request stream. In this case the
|
|
underlying TCP connection will be closed when the last pending response has been received.
|
|
|
|
The connection will also be closed if the response entity is cancelled (e.g. by attaching it to ``Sink.cancelled()``)
|
|
or consumed only partially (e.g. by using ``take`` combinator). In order to prevent this behaviour the entity should be
|
|
explicitly drained by attaching it to ``Sink.ignore()``.
|
|
|
|
|
|
Timeouts
|
|
--------
|
|
|
|
Timeouts are configured in the same way for Scala and Akka. See :ref:`http-timeouts-java` .
|
|
|
|
.. _http-client-layer-java:
|
|
|
|
Stand-Alone HTTP Layer Usage
|
|
----------------------------
|
|
|
|
Due to its Reactive-Streams-based nature the Akka HTTP layer is fully detachable from the underlying TCP
|
|
interface. While in most applications this "feature" will not be crucial it can be useful in certain cases to be able
|
|
to "run" the HTTP layer (and, potentially, higher-layers) against data that do not come from the network but rather
|
|
some other source. Potential scenarios where this might be useful include tests, debugging or low-level event-sourcing
|
|
(e.g by replaying network traffic).
|
|
|
|
On the client-side the stand-alone HTTP layer forms a ``BidiFlow<HttpRequest, SslTlsOutbound, SslTlsInbound, HttpResponse, NotUsed>``,
|
|
that is a stage that "upgrades" a potentially encrypted raw connection to the HTTP level.
|
|
|
|
You create an instance of the layer by calling one of the two overloads of the ``Http.get(system).clientLayer`` method,
|
|
which also allows for varying degrees of configuration. |