//  ========================================================================
//  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.