WebSocket (jooby-project 1.6.6 API)

All Superinterfaces:

AutoCloseable, Closeable, Registry
```
public interface WebSocket
extends Closeable, Registry
```
WebSockets

Creating web sockets is pretty straightforward:
```
  {
    ws("/", (ws)  -> {
      // connected
      ws.onMessage(message  -> {
        System.out.println(message.value());
        ws.send("Message Received");
      });
      ws.send("Connected");
    });
  }
 
```
First thing you need to do is to register a new web socket in your App using the Router.ws(String, WebSocket.OnOpen1) method. You can specify a path to listen for web socket connection. The path can be a static path or a path pattern (like routes). On new connections the WebSocket.OnOpen1.onOpen(WebSocket) will be executed from there you can listen using the onMessage(OnMessage), onClose(OnClose) or onError(OnError) events. Inside a handler you can send text or binary message.
mvc

Starting from 1.1.0 is it possible to use a class as web socket listener (in addition to the script web sockets supported). Your class must implement onMessage(OnMessage), like:
```
 &#64;Path("/ws")
 class MyHandler implements WebSocket.OnMessage<String> {

   private WebSocket ws;

   &#64;Inject
   public MyHandler(WebSocket ws) {
     this.ws = ws;
   }

   &#64;Override
   public void onMessage(String message) {
    ws.send("Got it!");
   }
 }

 {
   ws(MyHandler.class);
 }

 
```
Optionally, your listener might implements the WebSocket.OnClose, WebSocket.OnError or WebSocket.OnOpen callbacks. Or if you want to implement all them, then just WebSocket.Handler

data types

If your web socket is suppose to send/received a specific data type, like: json it is nice to define a consume and produce types:
```
   ws("/", (ws)  -> {
     ws.onMessage(message  -> {
       // read as json
       MyObject object = message.to(MyObject.class);
     });

     MyObject object = new MyObject();
     ws.send(object); // convert to text message using a json converter
   })
   .consumes(MediaType.json)
   .produces(MediaType.json);
 
```
Or via annotations for mvc listeners:
```
 &#64;Consumes("json")
 &#64;Produces("json")
 &#64;Path("/ws")
 class MyHandler implements WebSocket.OnMessage<MyObject> {

   public void onMessage(MyObject message) {
     // ...
     ws.send(new ResponseObject());
   }

 }
 
```
The message MyObject will be processed by a json parser and the response object will be renderered as json too.
Since:

0.1.0

Author:

edgar

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`WebSocket.CloseStatus` Hold a status code and optionally a reason message for `close()` operations.
`static class`	`WebSocket.Definition` Configure a web socket.
`static interface`	`WebSocket.Handler<T>`
`static interface`	`WebSocket.OnClose`
`static interface`	`WebSocket.OnError` Web socket err callback.
`static interface`	`WebSocket.OnMessage<T>` Web socket message callback.
`static interface`	`WebSocket.OnOpen` A web socket connect handler.
`static interface`	`WebSocket.OnOpen1` A web socket connect handler.
`static interface`	`WebSocket.SuccessCallback` Web socket success callback.

Field Summary

Fields
Modifier and Type	Field and Description
`static WebSocket.CloseStatus`	`BAD_DATA` "1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message)."
`static WebSocket.OnError`	`ERR` Default err callback.
`static WebSocket.CloseStatus`	`GOING_AWAY` "1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page."
`static com.google.inject.Key<Set<WebSocket.Definition>>`	`KEY` Websocket key.
`static WebSocket.CloseStatus`	`NORMAL` "1000 indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled."
`static WebSocket.CloseStatus`	`NOT_ACCEPTABLE` "1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message)."
`static WebSocket.CloseStatus`	`POLICY_VIOLATION` "1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy.
`static WebSocket.CloseStatus`	`PROTOCOL_ERROR` "1002 indicates that an endpoint is terminating the connection due to a protocol error."
`static WebSocket.CloseStatus`	`REQUIRED_EXTENSION` "1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake.
`static WebSocket.CloseStatus`	`SERVER_ERROR` "1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request."
`static WebSocket.CloseStatus`	`SERVICE_OVERLOAD` "1013 indicates that the service is experiencing overload.
`static WebSocket.CloseStatus`	`SERVICE_RESTARTED` "1012 indicates that the service is restarted.
`static WebSocket.SuccessCallback`	`SUCCESS` Default success callback.
`static WebSocket.CloseStatus`	`TOO_BIG_TO_PROCESS` "1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process."

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`Map<String,Object>`	`attributes()` Web socket attributes.
`default void`	`broadcast(Object data)` Send data to all connected sessions.
`default void`	`broadcast(Object data, WebSocket.OnError err)` Send data to all connected sessions.
`default void`	`broadcast(Object data, WebSocket.SuccessCallback success)` Send data to all connected sessions.
`void`	`broadcast(Object data, WebSocket.SuccessCallback success, WebSocket.OnError err)` Send data to all connected sessions.
`default void`	`close()` Gracefully closes the connection, after sending a description message
`default void`	`close(int code)` Gracefully closes the connection, after sending a description message
`default void`	`close(int code, String reason)` Gracefully closes the connection, after sending a description message
`void`	`close(WebSocket.CloseStatus status)` Gracefully closes the connection, after sending a description message
`MediaType`	`consumes()`
`<T> T`	`get(String name)` Get a web socket attribute.
`<T> Optional<T>`	`ifGet(String name)` Get a web socket attribute or empty value.
`boolean`	`isOpen()` True if the websocket is still open.
`void`	`onClose(WebSocket.OnClose callback)` Register an close callback to execute when client close the web socket.
`void`	`onError(WebSocket.OnError callback)` Register an error callback to execute when an error is found.
`void`	`onMessage(WebSocket.OnMessage<Mutant> callback)` Register a callback to execute when a new message arrive.
`String`	`path()`
`String`	`pattern()`
`void`	`pause()` Pause the client stream.
`MediaType`	`produces()`
`void`	`resume()` Resume the client stream.
`default void`	`send(Object data)` Send data through the connection.
`default void`	`send(Object data, WebSocket.OnError err)` Send data through the connection.
`default void`	`send(Object data, WebSocket.SuccessCallback success)` Send data through the connection.
`void`	`send(Object data, WebSocket.SuccessCallback success, WebSocket.OnError err)` Send data through the connection.
`WebSocket`	`set(String name, Object value)` Set a web socket attribute.
`void`	`terminate()` Immediately shuts down the connection.
`WebSocket`	`unset()` Clear/reset all the web socket attributes.
`<T> Optional<T>`	`unset(String name)` Clear/remove a web socket attribute.
`Map<Object,String>`	`vars()`

Methods inherited from interface org.jooby.Registry
require, require, require, require, require

- Field Detail
  - KEY
```
static final com.google.inject.Key<Set<WebSocket.Definition>> KEY
```
    Websocket key.
  - SUCCESS
```
static final WebSocket.SuccessCallback SUCCESS
```
    Default success callback.
  - ERR
```
static final WebSocket.OnError ERR
```
    Default err callback.
  - NORMAL
```
static final WebSocket.CloseStatus NORMAL
```
    "1000 indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled."
  - GOING_AWAY
```
static final WebSocket.CloseStatus GOING_AWAY
```
    "1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page."
  - PROTOCOL_ERROR
```
static final WebSocket.CloseStatus PROTOCOL_ERROR
```
    "1002 indicates that an endpoint is terminating the connection due to a protocol error."
  - NOT_ACCEPTABLE
```
static final WebSocket.CloseStatus NOT_ACCEPTABLE
```
    "1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message)."
  - BAD_DATA
```
static final WebSocket.CloseStatus BAD_DATA
```
    "1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message)."
  - POLICY_VIOLATION
```
static final WebSocket.CloseStatus POLICY_VIOLATION
```
    "1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy."
  - TOO_BIG_TO_PROCESS
```
static final WebSocket.CloseStatus TOO_BIG_TO_PROCESS
```
    "1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process."
  - REQUIRED_EXTENSION
```
static final WebSocket.CloseStatus REQUIRED_EXTENSION
```
    "1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead."
  - SERVER_ERROR
```
static final WebSocket.CloseStatus SERVER_ERROR
```
    "1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request."
  - SERVICE_RESTARTED
```
static final WebSocket.CloseStatus SERVICE_RESTARTED
```
    "1012 indicates that the service is restarted. A client may reconnect, and if it chooses to do, should reconnect using a randomized delay of 5 - 30s."
  - SERVICE_OVERLOAD
```
static final WebSocket.CloseStatus SERVICE_OVERLOAD
```
    "1013 indicates that the service is experiencing overload. A client should only connect to a different IP (when there are multiple for the target) or reconnect to the same IP upon user action."
- Method Detail
  - path
```
@Nonnull
String path()
```
    Returns:
    
    Current request path.
  - pattern
```
@Nonnull
String pattern()
```
    Returns:
    
    The currently matched pattern.
  - vars
```
@Nonnull
Map<Object,String> vars()
```
    Returns:
    
    The currently matched path variables (if any).
  - consumes
```
@Nonnull
MediaType consumes()
```
    Returns:
    
    The type this route can consumes, defaults is: * / *.
  - produces
```
@Nonnull
MediaType produces()
```
    Returns:
    
    The type this route can produces, defaults is: * / *.
  - onMessage
```
void onMessage(WebSocket.OnMessage<Mutant> callback)
        throws Exception
```
    Register a callback to execute when a new message arrive.
    
    Parameters:
    
    callback - A callback
    
    Throws:
    
    Exception - If something goes wrong.
  - onError
```
void onError(WebSocket.OnError callback)
```
    Register an error callback to execute when an error is found.
    
    Parameters:
    
    callback - A callback
  - onClose
```
void onClose(WebSocket.OnClose callback)
      throws Exception
```
    Register an close callback to execute when client close the web socket.
    
    Parameters:
    
    callback - A callback
    
    Throws:
    
    Exception - If something goes wrong.
  - close
```
default void close(int code,
                   String reason)
```
    Gracefully closes the connection, after sending a description message
    
    Parameters:
    
    code - Close status code.
    
    reason - Close reason.
  - close
```
default void close(int code)
```
    Gracefully closes the connection, after sending a description message
    
    Parameters:
    
    code - Close status code.
  - close
```
default void close()
```
    Gracefully closes the connection, after sending a description message
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
  - isOpen
```
boolean isOpen()
```
    True if the websocket is still open.
    
    Returns:
    
    True if the websocket is still open.
  - close
```
void close(WebSocket.CloseStatus status)
```
    Gracefully closes the connection, after sending a description message
    
    Parameters:
    
    status - Close status code.
  - resume
```
void resume()
```
    Resume the client stream.
  - pause
```
void pause()
```
    Pause the client stream.
  - terminate
```
void terminate()
        throws Exception
```
    Immediately shuts down the connection.
    
    Throws:
    
    Exception - If something goes wrong.
  - send
```
default void send(Object data)
           throws Exception
```
    Send data through the connection. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    Throws:
    
    Exception - If something goes wrong.
  - send
```
default void send(Object data,
                  WebSocket.SuccessCallback success)
           throws Exception
```
    Send data through the connection. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    success - A success callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - send
```
default void send(Object data,
                  WebSocket.OnError err)
           throws Exception
```
    Send data through the connection. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    err - An err callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - send
```
void send(Object data,
          WebSocket.SuccessCallback success,
          WebSocket.OnError err)
   throws Exception
```
    Send data through the connection. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    success - A success callback.
    
    err - An err callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - broadcast
```
default void broadcast(Object data)
                throws Exception
```
    Send data to all connected sessions. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    Throws:
    
    Exception - If something goes wrong.
  - broadcast
```
default void broadcast(Object data,
                       WebSocket.SuccessCallback success)
                throws Exception
```
    Send data to all connected sessions. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    success - A success callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - broadcast
```
default void broadcast(Object data,
                       WebSocket.OnError err)
                throws Exception
```
    Send data to all connected sessions. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    err - An err callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - broadcast
```
void broadcast(Object data,
               WebSocket.SuccessCallback success,
               WebSocket.OnError err)
        throws Exception
```
    Send data to all connected sessions. If the web socket is closed this method throw an Err with NORMAL close status.
    
    Parameters:
    
    data - Data to send.
    
    success - A success callback.
    
    err - An err callback.
    
    Throws:
    
    Exception - If something goes wrong.
  - set
```
@Nullable
WebSocket set(String name,
                        Object value)
```
    Set a web socket attribute.
    
    Parameters:
    
    name - Attribute name.
    
    value - Attribute value.
    
    Returns:
    
    This socket.
  - get
```
<T> T get(String name)
```
    Get a web socket attribute.
    
    Parameters:
    
    name - Attribute name.
    
    Returns:
    
    Attribute value.
  - ifGet
```
<T> Optional<T> ifGet(String name)
```
    Get a web socket attribute or empty value.
    
    Type Parameters:
    
    T - Attribute type.
    
    Parameters:
    
    name - Attribute name.
    
    Returns:
    
    Attribute value or empty value.
  - unset
```
<T> Optional<T> unset(String name)
```
    Clear/remove a web socket attribute.
    
    Type Parameters:
    
    T - Attribute type.
    
    Parameters:
    
    name - Attribute name.
    
    Returns:
    
    Attribute value (if any).
  - unset
```
WebSocket unset()
```
    Clear/reset all the web socket attributes.
    
    Returns:
    
    This socket.
  - attributes
```
Map<String,Object> attributes()
```
    Web socket attributes.
    
    Returns:
    
    Web socket attributes.

Interface WebSocket

WebSockets

mvc

data types

Nested Class Summary

Field Summary

Method Summary

Methods inherited from interface org.jooby.Registry

Field Detail

KEY

SUCCESS

ERR

NORMAL

GOING_AWAY

PROTOCOL_ERROR

NOT_ACCEPTABLE

BAD_DATA

POLICY_VIOLATION

TOO_BIG_TO_PROCESS

REQUIRED_EXTENSION

SERVER_ERROR

SERVICE_RESTARTED

SERVICE_OVERLOAD

Method Detail

path

pattern

vars

consumes

produces

onMessage

onError

onClose

close

close

close

isOpen

close

resume

pause

terminate

send

send

send

send

broadcast

broadcast

broadcast

broadcast

set

get

ifGet

unset

unset

attributes