!htc,doc,htp #19508 fix casing of WebSocket (as per spec)

This commit is contained in:
Konrad Malawski 2016-01-19 20:43:59 +01:00
parent 0dd889aa17
commit 1b47fbeac7
72 changed files with 698 additions and 501 deletions

View file

@ -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);
}

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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