| // ======================================================================== |
| // Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| |
| [[jetty-websocket-api-annotations]] |
| === Using WebSocket Annotations |
| |
| The most basic form of WebSocket is a marked up POJO with annotations |
| provided by the Jetty WebSocket API. |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| include::{SRCDIR}/jetty-websocket/websocket-common/src/test/java/examples/echo/AnnotatedEchoSocket.java[] |
| ---- |
| |
| The above example is a simple WebSocket echo endpoint that will echo back any TEXT messages it receives. |
| |
| This implementation is using a stateless approach to a Echo socket, as the Session is being passed into the Message event as the event occurs. |
| This would allow you to reuse the single instance of the AnnotatedEchoSocket for working with multiple endpoints. |
| |
| The annotations you have available: |
| |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/WebSocket.html[@WebSocket]:: |
| A required class level annotation. |
| + |
| Flags this POJO as being a WebSocket. |
| + |
| The class must be not abstract and public. |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/OnWebSocketConnect.html[@OnWebSocketConnect]:: |
| An optional method level annotation. |
| + |
| Flags one method in the class as receiving the On Connect event. |
| + |
| Method must be public, not abstract, return void, and have a single link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[Session] parameter. |
| |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/OnWebSocketClose.html[@OnWebSocketClose]:: |
| An optional method level annotation. |
| + |
| Flags one method in the class as receiving the On Close event. |
| + |
| Method signature must be public, not abstract, and return void. |
| + |
| The method parameters: |
| + |
| . link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`Session`] (optional) |
| . `int closeCode` (required) |
| . `String closeReason` (required) |
| |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/OnWebSocketMessage.html[@OnWebSocketMessage]:: |
| An optional method level annotation. |
| + |
| Flags up to 2 methods in the class as receiving On Message events. |
| + |
| You can have 1 method for TEXT messages, and 1 method for BINARY messages. |
| + |
| Method signature must be public, not abstract, and return void. |
| + |
| The method parameters for Text messages: |
| + |
| * link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`Session`] (optional) |
| * `String text` (required) |
| + |
| The method parameters for Binary messages: |
| + |
| * link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`Session`] (optional) |
| * `byte buf[]` (required) |
| * `int offset` (required) |
| * `int length` (required) |
| |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/OnWebSocketError.html[@OnWebSocketError]:: |
| An optional method level annotation. |
| + |
| Flags one method in the class as receiving Error events from the WebSocket implementation. |
| + |
| Method signatures must be public, not abstract, and return void. |
| + |
| The method parameters: |
| + |
| 1. link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`Session`] (optional) |
| 2. `Throwable cause` (required) |
| |
| link:{JDURL}/org/eclipse/jetty/websocket/api/annotations/OnWebSocketFrame.html[@OnWebSocketFrame]:: |
| An optional method level annotation. |
| + |
| Flags one method in the class as receiving Frame events from the WebSocket implementation after they have been processed by any extensions declared during the Upgrade handshake. |
| + |
| Method signatures must be public, not abstract, and return void. |
| + |
| The method parameters: |
| + |
| 1. link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`Session`] (optional) |
| 2. link:{JDURL}/org/eclipse/jetty/websocket/api/extensions/Frame.html[`Frame`] (required) |
| + |
| The Frame received will be notified on this method, then be processed by Jetty, possibly resulting in another event, such as On Close, or On Message. |
| Changes to the Frame will not be seen by Jetty. |