Move the docu for web sockets from the wiki. WIP
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/bf6dfb8e Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/bf6dfb8e Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/bf6dfb8e Branch: refs/heads/reference-guide Commit: bf6dfb8efd273c3dd9c89e3b6d517e43e6840e20 Parents: 4dae90d Author: Martin Tzvetanov Grigorov <[email protected]> Authored: Mon Jan 28 09:44:08 2013 +0100 Committer: Martin Tzvetanov Grigorov <[email protected]> Committed: Mon Jan 28 09:44:08 2013 +0100 ---------------------------------------------------------------------- .../src/documentation/source/index.rst | 1 + .../src/documentation/source/stateless.rst | 2 +- .../src/documentation/source/websockets.rst | 93 ++++++++++++++- .../wicket/reference/stateless/CheckedPage.java | 2 +- 4 files changed, 94 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/wicket/blob/bf6dfb8e/wicket-reference-guide/src/documentation/source/index.rst ---------------------------------------------------------------------- diff --git a/wicket-reference-guide/src/documentation/source/index.rst b/wicket-reference-guide/src/documentation/source/index.rst index 3fb1824..c91de7e 100644 --- a/wicket-reference-guide/src/documentation/source/index.rst +++ b/wicket-reference-guide/src/documentation/source/index.rst @@ -17,6 +17,7 @@ Contents: models behaviors ajax + events stateless ioc websockets http://git-wip-us.apache.org/repos/asf/wicket/blob/bf6dfb8e/wicket-reference-guide/src/documentation/source/stateless.rst ---------------------------------------------------------------------- diff --git a/wicket-reference-guide/src/documentation/source/stateless.rst b/wicket-reference-guide/src/documentation/source/stateless.rst index 8f71dac..0ff74d2 100644 --- a/wicket-reference-guide/src/documentation/source/stateless.rst +++ b/wicket-reference-guide/src/documentation/source/stateless.rst @@ -39,7 +39,7 @@ then the value of *counter* field will always be *0* because a new instance of S Keeping it stateless -------------------- -To make sure that a page is stateless and there is no stateful component/behavior added to it by accident `StatelessChecker <http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/devutils/stateless/StatelessChecker.html>`_ can be used. If there is a stateful component or behavior then this checker will throw an exception which message explains where is the problem. +To make sure that a page is stateless and there is no stateful component/behavior added to it by accident `StatelessChecker <http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/devutils/stateless/StatelessChecker.html>`_ can be used. If there is a stateful component or behavior then this checker will throw an exception with a message explaining where is the problem. 1. Add dependency to `wicket-devutils` http://git-wip-us.apache.org/repos/asf/wicket/blob/bf6dfb8e/wicket-reference-guide/src/documentation/source/websockets.rst ---------------------------------------------------------------------- diff --git a/wicket-reference-guide/src/documentation/source/websockets.rst b/wicket-reference-guide/src/documentation/source/websockets.rst index 407d3d0..8fa70cd 100644 --- a/wicket-reference-guide/src/documentation/source/websockets.rst +++ b/wicket-reference-guide/src/documentation/source/websockets.rst @@ -1,2 +1,91 @@ -Native WebSocket -================= +Wicket Native WebSockets +======================== + +Since version 6.0 Wicket provides an experimental module that provides integration with WebSocket support in the web containers like Jetty and Apache Tomcat. + +Each of the integrations provide a custom implementation of `WicketFilter <http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/protocol/http/WicketFilter.html>`_ that first checks whether the current web request needs to upgrade its protocol from HTTP to WebSocket. This is done by checking the request headers for the special header with name "Upgrade". If the request is an upgrade then the filter registers an endpoint for the web socket connection. Later this endpoint is used to read/write messages from/to the client. + +When a client is connected it is being registered in a global (application scoped) registry using as a key the application, the client session id and the id of the page that registered it. Later when the server needs to push a message it uses this registry to filter which clients need to receive the message. +When a message is received from the client Wicket uses the associated page id for the web connection and loads the Wicket Page as Ajax requests do, then it broadcasts an `IWebSocketMessage <http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/protocol/ws/api/message/IWebSocketMessage.html>`_ (:ref:Wicket 1.5 Event system) to all its components and behaviors so they can react on it. +The server-side can push plain text and binary messages to the client - pure web socket messages, but can also add components for re-render, prepend/append JavaScript as you do with AjaxRequestTarget. + +h3. How to use it ? + +h5. Maven dependency + +Add dependency to either org.apache.wicket:wicket-native-websocket-jetty or org.apache.wicket:wicket-native-websocket-tomcat. + +h5. Custom WicketFilter + +Setup the custom WicketFilter implementation for the chosen web container in your web.xml. + +For Jetty 7.5+ this is + <filter-class>org.apache.wicket.protocol.http.Jetty7WebSocketFilter</filter-class> + +For Tomcat 7.0.27+: + <filter-class>org.apache.wicket.protocol.http.Tomcat7WebSocketFilter</filter-class> + +h5. WebSocketBehavior + +_org.apache.wicket.protocol.ws.api.WebSocketBehavior_ is much like Ajax behaviors that you may know from earlier versions of Wicket. +Add WebSocketBehavior to the page that will use web socket communication: + +MyPage.java + +:: + + public class MyPage extends WebPage { + + public MyPage() { + add(new WebSocketBehavior() { + @Override + protected void onMessage(WebSocketRequestHandler handler, TextMessage message) { + } + }); + } + } + +Use _message.getText()_ to read the message sent by the client and use the passed _handler.push(String)_ to push a text message to the connected client. Additionally you can use _handler.add(Component...)_ to add Wicket components for re-render, _handler#prependJavaScript(CharSequence)_ and _handler#appendJavaScript(CharSequence)_ as you do with AjaxRequestTarget. + +See the demo application at [martin-g's GitHub|https://github.com/martin-g/wicket-native-websocket-example]. It is written with Scala and uses [Akka|http://akka.io] which are not available at Maven central repository so it cannot be hosted at Apache Git servers. + +h5. Client side APIs + +By adding a _WebSocketBehavior_ to your component(s) Wicket will contribute _wicket-websocket-jquery.js_ library which provides some helper functions to write your client side code. There is a default websocket connection per Wicket Page opened for you which you can use like _Wicket.WebSocket.send('\{msg: "my message"\}')_. + +If you need more WebSocket connections then you can do: _var ws = new Wicket.WebSocket(); ws.send('message');_ + +To close a connection: _Wicket.WebSocket.close()_ or _ws.close()_. + +_Wicket.WebSocket_ is a simple wrapper around the native _window.WebSocket_ API which is used to intercept the calls and to fire special events (Wicket.Event PubSub). +|| Event name || Arguments || Description || +| /websocket/open | jqEvent | A WebSocket connection has been just opened | +| /websocket/message | jqEvent, message | A message has been received from the server | +| /websocket/closed | jqEvent | A WebSocket connection has been closed | +| /websocket/error | jqEvent | An error occurred in the communication. The connection will be closed | + +If you don't need to listen for these events then you can just use the native JavaScript API (window.WebSocket). + +A demo code can be seen in the [Demo Application|https://github.com/martin-g/wicket-native-websocket-example/blob/master/src/main/resources/org/apache/wicket/websocket/jetty/example/client.js] + +h3. Testing + +The module provides _org.apache.wicket.protocol.ws.util.tester.WebSocketTester_ which gives you the possibility to emulate sending and receiving messages without the need to run in a real web container, as WicketTester does this for HTTP requests. + +Check [WebSocketTesterTest|https://git-wip-us.apache.org/repos/asf/wicket/repo?p=wicket.git;a=blob;f=wicket-experimental/wicket-native-websocket/wicket-native-websocket-core/src/test/java/org/apache/wicket/protocol/ws/util/tester/WebSocketTesterTest.java;hb=master] for an example. + +h3. Differences with Wicket-Atmosphere module. + +Wicket-Atmosphere provides integration with [Atmosphere|https://github.com/Atmosphere/atmosphere/] and let it handle the inconsistencies in WebSocket protocol support in different browsers and web containers. If either the browser or the web container do not support WebSockets then Atmosphere will downgrade (depending on the configuration) to either long-polling, streaming, server-side events, jsonp, ... to simulate the long running connection. + +Wicket Native WebSocket uses only WebSocket connections, so it wont work for browsers and web containers which do not support WebSockets. There are no plans to add such support in future. Use it only if you really know that you will run your application in an environment that supports WebSockets. + +Currently supported web containers are Jetty 7.5+ and Tomcat 7.0.27+. +Currently supported browsers are Google Chrome/Chromium, Firefox 11+, Safari 5.x (with Jetty), IE10. + +FAQ +--- + +1. Request and session scoped beans do not work. + +The Web Socket communication is not intercepted by Servlet Filters and Listeners and thus the Dependency Injection libraries have no chance to export the request and session beans. http://git-wip-us.apache.org/repos/asf/wicket/blob/bf6dfb8e/wicket-reference-guide/stateless/src/main/java/org/apache/wicket/reference/stateless/CheckedPage.java ---------------------------------------------------------------------- diff --git a/wicket-reference-guide/stateless/src/main/java/org/apache/wicket/reference/stateless/CheckedPage.java b/wicket-reference-guide/stateless/src/main/java/org/apache/wicket/reference/stateless/CheckedPage.java index 7d5ade4..4b1e40d 100644 --- a/wicket-reference-guide/stateless/src/main/java/org/apache/wicket/reference/stateless/CheckedPage.java +++ b/wicket-reference-guide/stateless/src/main/java/org/apache/wicket/reference/stateless/CheckedPage.java @@ -5,6 +5,6 @@ import org.apache.wicket.markup.html.WebPage; //#check-stateless @org.apache.wicket.devutils.stateless.StatelessComponent public class CheckedPage extends WebPage +//#check-stateless { } -//#check-stateless
