//
//  ========================================================================
//  Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//  ========================================================================
//  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-events]]
=== WebSocket Events

Every WebSocket can receive various events:

On Connect Event::
  An indication to the WebSocket that the Upgrade has succeeded and the WebSocket is now open.
+
You will receive a link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[`org.eclipse.jetty.websocket.api.Session`] object that references the specific session for this Open Event.
+
For normal WebSockets, it is important to hold onto this Session and use it for communicating with the Remote Endpoint.
+
For Stateless WebSockets, the Session will be passed into each event as it occurs, allowing you to only have 1 instance of a WebSocket serving many Remote Endpoints.

On Close Event::
  An indication that the WebSocket is now closed.
+
Every Close Event will have a link:{JDURL}/org/eclipse/jetty/websocket/api/StatusCode.html[Status   Code] (and an optional Closure Reason Message)
+
A normal WebSocket closure will go through a Close Handshake where both the Local Endpoint and the Remote Endpoint both send a Close frame to indicate that the connection is closed.
+
It is possible for the Local WebSocket to indicate its desire to Close by issuing a Close frame to the Remote Endpoint, but the Remote Endpoint can continue to send messages until it sends a Close Frame.
This is known as a Half-Open connection, and it is important to note that once the Local Endpoint has send the Close Frame it cannot write anymore WebSocket traffic.
+
On an abnormal closure, such as a connection disconnect or a connection timeout, the low level connection will be terminated without going through a Close Handshake, this will still result in an On Close Event (and likely a corresponding On Error Event).
On Error Event::
  If an error occurred, during the implementation, the WebSocket will be notified via this event handler.
On Message Event::
  An indication that a complete message has been received and is ready for handling by your WebSocket.
+
This can be a (UTF8) TEXT message or a raw BINARY message.
