!htc,doc,htp #19508 fix casing of WebSocket (as per spec)
This commit is contained in:
parent
0dd889aa17
commit
1b47fbeac7
72 changed files with 698 additions and 501 deletions
|
|
@ -30,15 +30,15 @@ import akka.http.javadsl.model.HttpRequest;
|
|||
import akka.http.javadsl.model.HttpResponse;
|
||||
import akka.http.javadsl.model.ws.Message;
|
||||
import akka.http.javadsl.model.ws.TextMessage;
|
||||
import akka.http.javadsl.model.ws.Websocket;
|
||||
import akka.http.javadsl.model.ws.WebSocket;
|
||||
|
||||
public class WebsocketCoreExample {
|
||||
public class WebSocketCoreExample {
|
||||
//#websocket-handling
|
||||
public static HttpResponse handleRequest(HttpRequest request) {
|
||||
System.out.println("Handling request to " + request.getUri());
|
||||
|
||||
if (request.getUri().path().equals("/greeter"))
|
||||
return Websocket.handleWebsocketRequestWith(request, greeter());
|
||||
return WebSocket.handleWebSocketRequestWith(request, greeter());
|
||||
else
|
||||
return HttpResponse.create().withStatus(404);
|
||||
}
|
||||
|
|
@ -16,13 +16,13 @@ import akka.http.javadsl.model.ws.TextMessage;
|
|||
|
||||
import akka.http.javadsl.server.HttpApp;
|
||||
|
||||
public class WebsocketRoutingExample extends HttpApp {
|
||||
public class WebSocketRoutingExample extends HttpApp {
|
||||
//#websocket-route
|
||||
@Override
|
||||
public Route createRoute() {
|
||||
return
|
||||
path("greeter").route(
|
||||
handleWebsocketMessages(greeter())
|
||||
handleWebSocketMessages(greeter())
|
||||
);
|
||||
}
|
||||
//#websocket-route
|
||||
|
|
@ -55,8 +55,8 @@ RangeDirectives
|
|||
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.
|
||||
WebSocketDirectives
|
||||
Contains directives to support answering WebSocket requests.
|
||||
|
||||
TODO this page should be rewritten as the corresponding Scala page
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ It sports the following features:
|
|||
- Full support for `HTTP pipelining`_
|
||||
- Full support for asynchronous HTTP streaming including "chunked" transfer encoding accessible through an idiomatic API
|
||||
- Optional SSL/TLS encryption
|
||||
- Websocket support
|
||||
- WebSocket support
|
||||
|
||||
.. _HTTP persistent connections: http://en.wikipedia.org/wiki/HTTP_persistent_connection
|
||||
.. _HTTP pipelining: http://en.wikipedia.org/wiki/HTTP_pipelining
|
||||
|
|
|
|||
|
|
@ -52,20 +52,20 @@ a streaming message from an Akka Stream source.
|
|||
Server API
|
||||
----------
|
||||
|
||||
The entrypoint for the Websocket API is the synthetic ``UpgradeToWebsocket`` header which is added to a request
|
||||
if Akka HTTP encounters a Websocket upgrade request.
|
||||
The entrypoint for the WebSocket API is the synthetic ``UpgradeToWebSocket`` header which is added to a request
|
||||
if Akka HTTP encounters a WebSocket upgrade request.
|
||||
|
||||
The Websocket specification mandates that details of the Websocket connection are negotiated by placing special-purpose
|
||||
The WebSocket specification mandates that details of the WebSocket connection are negotiated by placing special-purpose
|
||||
HTTP-headers into request and response of the HTTP upgrade. In Akka HTTP these HTTP-level details of the WebSocket
|
||||
handshake are hidden from the application and don't need to be managed manually.
|
||||
|
||||
Instead, the synthetic ``UpgradeToWebsocket`` represents a valid Websocket upgrade request. An application can detect
|
||||
a Websocket upgrade request by looking for the ``UpgradeToWebsocket`` header. It can choose to accept the upgrade and
|
||||
start a Websocket connection by responding to that request with an ``HttpResponse`` generated by one of the
|
||||
``UpgradeToWebsocket.handleMessagesWith`` methods. In its most general form this method expects two arguments:
|
||||
first, a handler ``Flow<Message, Message, ?>`` that will be used to handle Websocket messages on this connection.
|
||||
Instead, the synthetic ``UpgradeToWebSocket`` represents a valid WebSocket upgrade request. An application can detect
|
||||
a WebSocket upgrade request by looking for the ``UpgradeToWebSocket`` header. It can choose to accept the upgrade and
|
||||
start a WebSocket connection by responding to that request with an ``HttpResponse`` generated by one of the
|
||||
``UpgradeToWebSocket.handleMessagesWith`` methods. In its most general form this method expects two arguments:
|
||||
first, a handler ``Flow<Message, Message, ?>`` that will be used to handle WebSocket messages on this connection.
|
||||
Second, the application can optionally choose one of the proposed application-level sub-protocols by inspecting the
|
||||
values of ``UpgradeToWebsocket.getRequestedProtocols`` and pass the chosen protocol value to ``handleMessagesWith``.
|
||||
values of ``UpgradeToWebSocket.getRequestedProtocols`` and pass the chosen protocol value to ``handleMessagesWith``.
|
||||
|
||||
Handling Messages
|
||||
+++++++++++++++++
|
||||
|
|
@ -76,7 +76,7 @@ scenarios this fits very well and such a ``Flow`` can be constructed from a simp
|
|||
|
||||
There are other use-cases, e.g. in a server-push model, where a server message is sent spontaneously, or in a
|
||||
true bi-directional scenario where input and output aren't logically connected. Providing the handler as a ``Flow`` in
|
||||
these cases may not fit. An overload of ``UpgradeToWebsocket.handleMessagesWith`` is provided, instead,
|
||||
these cases may not fit. An overload of ``UpgradeToWebSocket.handleMessagesWith`` is provided, instead,
|
||||
which allows to pass an output-generating ``Source<Message, ?>`` and an input-receiving ``Sink<Message, ?>`` independently.
|
||||
|
||||
Note that a handler is required to consume the data stream of each message to make place for new messages. Otherwise,
|
||||
|
|
@ -87,40 +87,40 @@ Example
|
|||
|
||||
Let's look at an example_.
|
||||
|
||||
Websocket requests come in like any other requests. In the example, requests to ``/greeter`` are expected to be
|
||||
Websocket requests:
|
||||
WebSocket requests come in like any other requests. In the example, requests to ``/greeter`` are expected to be
|
||||
WebSocket requests:
|
||||
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketCoreExample.java
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketCoreExample.java
|
||||
:include: websocket-handling
|
||||
|
||||
It uses a helper method ``akka.http.javadsl.model.ws.Websocket.handleWebsocketRequestWith`` which can be used if
|
||||
only Websocket requests are expected. The method looks for the ``UpgradeToWebsocket`` header and returns a response
|
||||
that will install the passed Websocket handler if the header is found. If the request is no Websocket request it will
|
||||
It uses a helper method ``akka.http.javadsl.model.ws.WebSocket.handleWebSocketRequestWith`` which can be used if
|
||||
only WebSocket requests are expected. The method looks for the ``UpgradeToWebSocket`` header and returns a response
|
||||
that will install the passed WebSocket handler if the header is found. If the request is no WebSocket request it will
|
||||
return a ``400 Bad Request`` error response.
|
||||
|
||||
In the example, the passed handler expects text messages where each message is expected to contain (a person's) name
|
||||
and then responds with another text message that contains a greeting:
|
||||
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketCoreExample.java
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketCoreExample.java
|
||||
:include: websocket-handler
|
||||
|
||||
Routing support
|
||||
---------------
|
||||
|
||||
The routing DSL provides the ``handleWebsocketMessages`` directive to install a WebSocket handler if a request
|
||||
The routing DSL provides the ``handleWebSocketMessages`` directive to install a WebSocket handler if a request
|
||||
is a WebSocket request. Otherwise, the directive rejects the request.
|
||||
|
||||
Let's look at how the above example can be rewritten using the high-level routing DSL.
|
||||
|
||||
Instead of writing the request handler manually, the routing behavior of the app is defined by a route that
|
||||
uses the ``handleWebsocketRequests`` directive in place of the ``Websocket.handleWebsocketRequestWith``:
|
||||
uses the ``handleWebSocketRequests`` directive in place of the ``WebSocket.handleWebSocketRequestWith``:
|
||||
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketRoutingExample.java
|
||||
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketRoutingExample.java
|
||||
:include: websocket-route
|
||||
|
||||
The handling code itself will be the same as with using the low-level API.
|
||||
|
||||
See the `full routing example`_.
|
||||
|
||||
.. _example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebsocketCoreExample.java
|
||||
.. _full routing example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebsocketRoutingExample.java
|
||||
.. _example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebSocketCoreExample.java
|
||||
.. _full routing example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebSocketRoutingExample.java
|
||||
Loading…
Add table
Add a link
Reference in a new issue