org.redkale.net.http

## 类 WebSocket

- java.lang.Object
- - org.redkale.net.http.WebSocket

-     public abstract class WebSocket
      extends java.lang.Object

  >      一个WebSocket连接对应一个WebSocket实体，即一个WebSocket会绑定一个TCP连接。
  >      WebSocket 有两种模式:
  >       1) 普通模式: 协议上符合HTML5规范, 其流程顺序如下:
  >           1.1 onOpen 若返回null，视为WebSocket的连接不合法，强制关闭WebSocket连接；通常用于判断登录态。
  >           1.2 createGroupid 若返回null，视为WebSocket的连接不合法，强制关闭WebSocket连接；通常用于判断用户权限是否符合。
  >           1.3 onConnected WebSocket成功连接后在准备接收数据前回调此方法。
  >           1.4 onMessage/onFragment+ WebSocket接收到消息后回调此消息类方法。
  >           1.5 onClose WebSocket被关闭后回调此方法。

  >       此模式下 以上方法都应该被重载。

  >       2) 原始二进制模式: 此模式有别于HTML5规范，可以视为原始的TCP连接。通常用于音频视频通讯场景。其流程顺序如下:
  >           2.1 onOpen 若返回null，视为WebSocket的连接不合法，强制关闭WebSocket连接；通常用于判断登录态。
  >           2.2 createGroupid 若返回null，视为WebSocket的连接不合法，强制关闭WebSocket连接；通常用于判断用户权限是否符合。
  >           2.3 onRead WebSocket成功连接后回调此方法， 由此方法处理原始的TCP连接， 同时业务代码去控制WebSocket的关闭。

  >       此模式下 以上方法都应该被重载。

  详情见: http://www.redkale.org

- - ### 字段概要

    字段
    限定符和类型 | 字段和说明
    --- | ---
    `static int` | `RETCODE_ENGINE_NULL`
    `static int` | `RETCODE_GROUP_EMPTY`
    `static int` | `RETCODE_ILLEGALBUFFER`
    `static int` | `RETCODE_NODESERVICE_NULL`
    `static int` | `RETCODE_SEND_ILLPACKET`
    `static int` | `RETCODE_SENDEXCEPTION`
    `static int` | `RETCODE_WSOCKET_CLOSED`
    `static int` | `RETCODE_WSOFFLINE`

  - ### 构造器概要

    构造器
    限定符 | 构造器和说明
    --- | ---
    `protected` | `WebSocket()`

  - ### 方法概要

    所有方法 实例方法 抽象方法 具体方法
    限定符和类型 | 方法和说明
    --- | ---
    `void` | `close()` 显式地关闭WebSocket
    `protected abstract java.io.Serializable` | `createGroupid()` 创建groupid， null表示异常， 必须实现该方法， 通常为用户ID为groupid
    `<T> T` | `getAttribute(java.lang.String name)` 获取当前WebSocket下的属性
    `long` | `getCreatetime()`
    `java.io.Serializable` | `getGroupid()` 获取当前WebSocket所属的groupid
    `protected java.util.Collection<java.net.InetSocketAddress>` | `getOnlineNodes(java.io.Serializable groupid)` 获取在线用户的节点地址列表
    `protected java.util.Map<java.net.InetSocketAddress,java.util.List<java.lang.String>>` | `getOnlineRemoteAddress(java.io.Serializable groupid)` 获取在线用户的详细连接信息
    `java.lang.String` | `getRemoteAddr()` 获取客户端真实地址 同 HttpRequest.getRemoteAddr()
    `java.net.SocketAddress` | `getRemoteAddress()` 获取客户端直接地址, 当WebSocket连接是由代理服务器转发的，则该值固定为代理服务器的IP地址
    `java.io.Serializable` | `getSessionid()` 获取当前WebSocket的会话ID， 不会为null
    `protected WebSocketGroup` | `getWebSocketGroup()` 获取当前WebSocket所属的WebSocketGroup， 不会为null
    `protected WebSocketGroup` | `getWebSocketGroup(java.io.Serializable groupid)` 获取指定groupid的WebSocketGroup, 没有返回null
    `protected java.util.Collection<WebSocketGroup>` | `getWebSocketGroups()` 获取当前进程节点所有在线的WebSocketGroup
    `void` | `onClose(int code, java.lang.String reason)`
    `void` | `onConnected()`
    `void` | `onFragment(byte[] bytes, boolean last)`
    `void` | `onFragment(java.lang.String text, boolean last)`
    `void` | `onMessage(byte[] bytes)`
    `void` | `onMessage(java.lang.String text)`
    `java.io.Serializable` | `onOpen(HttpRequest request)` 返回sessionid, null表示连接不合法或异常,默认实现是request.getSessionid(false)，通常需要重写该方法
    `void` | `onPing(byte[] bytes)`
    `void` | `onPong(byte[] bytes)`
    `void` | `onRead(AsyncConnection channel)` 标记为WebSocketBinary才需要重写此方法
    `<T> T` | `removeAttribute(java.lang.String name)` 移出当前WebSocket下的属性
    `int` | `send(byte[] data)` 发送单一的二进制消息
    `int` | `send(byte[] data, boolean last)` 发送二进制消息
    `int` | `send(java.io.Serializable message, boolean last)` 发送消息, 消息类型是String或byte[]
    `int` | `send(java.lang.String text)` 发送单一的文本消息
    `int` | `send(java.lang.String text, boolean last)` 发送文本消息
    `int` | `send(WebSocketPacket packet)` 发送消息体, 包含二进制/文本
    `int` | `sendEachMessage(java.io.Serializable groupid, byte[] data)` 给指定groupid的WebSocketGroup下所有WebSocket节点发送二进制消息
    `int` | `sendEachMessage(java.io.Serializable groupid, byte[] data, boolean last)` 给指定groupid的WebSocketGroup下所有WebSocket节点发送二进制消息
    `int` | `sendEachMessage(java.io.Serializable groupid, java.lang.String text)` 给指定groupid的WebSocketGroup下所有WebSocket节点发送文本消息
    `int` | `sendEachMessage(java.io.Serializable groupid, java.lang.String text, boolean last)` 给指定groupid的WebSocketGroup下所有WebSocket节点发送文本消息
    `int` | `sendPing()`
    `int` | `sendPing(byte[] data)`
    `int` | `sendPong(byte[] data)`
    `int` | `sendRecentMessage(java.io.Serializable groupid, byte[] data)` 给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送二进制消息
    `int` | `sendRecentMessage(java.io.Serializable groupid, byte[] data, boolean last)` 给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送二进制消息
    `int` | `sendRecentMessage(java.io.Serializable groupid, java.lang.String text)` 给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送文本消息
    `int` | `sendRecentMessage(java.io.Serializable groupid, java.lang.String text, boolean last)` 给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送文本消息
    `void` | `setAttribute(java.lang.String name, java.lang.Object value)` 给当前WebSocket下的增加属性
    `java.lang.String` | `toString()`

    - ### 从类继承的方法 java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### 字段详细资料

    - #### RETCODE_SEND_ILLPACKET

          public static final int RETCODE_SEND_ILLPACKET

      另请参阅:
        常量字段值

    - #### RETCODE_WSOCKET_CLOSED

          public static final int RETCODE_WSOCKET_CLOSED

      另请参阅:
        常量字段值

    - #### RETCODE_ILLEGALBUFFER

          public static final int RETCODE_ILLEGALBUFFER

      另请参阅:
        常量字段值

    - #### RETCODE_SENDEXCEPTION

          public static final int RETCODE_SENDEXCEPTION

      另请参阅:
        常量字段值

    - #### RETCODE_ENGINE_NULL

          public static final int RETCODE_ENGINE_NULL

      另请参阅:
        常量字段值

    - #### RETCODE_NODESERVICE_NULL

          public static final int RETCODE_NODESERVICE_NULL

      另请参阅:
        常量字段值

    - #### RETCODE_GROUP_EMPTY

          public static final int RETCODE_GROUP_EMPTY

      另请参阅:
        常量字段值

    - #### RETCODE_WSOFFLINE

          public static final int RETCODE_WSOFFLINE

      另请参阅:
        常量字段值

  - ### 构造器详细资料

    - #### WebSocket

          protected WebSocket()

  - ### 方法详细资料

    - #### send

          public final int send(WebSocketPacket packet)

      发送消息体, 包含二进制/文本
      参数:
        `packet` - WebSocketPacket
      返回:
        0表示成功， 非0表示错误码

    - #### send

          public final int send(java.lang.String text)

      发送单一的文本消息
      参数:
        `text` - 不可为空
      返回:
        0表示成功， 非0表示错误码

    - #### send

          public final int send(java.lang.String text,
                                boolean last)

      发送文本消息
      参数:
        `text` - 不可为空
        `last` - 是否最后一条
      返回:
        0表示成功， 非0表示错误码

    - #### sendPing

          public final int sendPing()

    - #### sendPing

          public final int sendPing(byte[] data)

    - #### sendPong

          public final int sendPong(byte[] data)

    - #### getCreatetime

          public final long getCreatetime()

    - #### send

          public final int send(byte[] data)

      发送单一的二进制消息
      参数:
        `data` - byte[]
      返回:
        0表示成功， 非0表示错误码

    - #### send

          public final int send(byte[] data,
                                boolean last)

      发送二进制消息
      参数:
        `data` - 不可为空
        `last` - 是否最后一条
      返回:
        0表示成功， 非0表示错误码

    - #### send

          public final int send(java.io.Serializable message,
                                boolean last)

      发送消息, 消息类型是String或byte[]
      参数:
        `message` - 不可为空, 只能是String或者byte[]
        `last` - 是否最后一条
      返回:
        0表示成功， 非0表示错误码

    - #### sendEachMessage

          public final int sendEachMessage(java.io.Serializable groupid,
                                           java.lang.String text)

      给指定groupid的WebSocketGroup下所有WebSocket节点发送文本消息
      参数:
        `groupid` - groupid
        `text` - 不可为空
      返回:
        为0表示成功， 其他值表示异常

    - #### sendEachMessage

          public final int sendEachMessage(java.io.Serializable groupid,
                                           byte[] data)

      给指定groupid的WebSocketGroup下所有WebSocket节点发送二进制消息
      参数:
        `groupid` - groupid
        `data` - 不可为空
      返回:
        为0表示成功， 其他值表示异常

    - #### sendEachMessage

          public final int sendEachMessage(java.io.Serializable groupid,
                                           java.lang.String text,
                                           boolean last)

      给指定groupid的WebSocketGroup下所有WebSocket节点发送文本消息
      参数:
        `groupid` - groupid
        `text` - 不可为空
        `last` - 是否最后一条
      返回:
        为0表示成功， 其他值表示异常

    - #### sendEachMessage

          public final int sendEachMessage(java.io.Serializable groupid,
                                           byte[] data,
                                           boolean last)

      给指定groupid的WebSocketGroup下所有WebSocket节点发送二进制消息
      参数:
        `groupid` - groupid
        `data` - 不可为空
        `last` - 是否最后一条
      返回:
        为0表示成功， 其他值表示异常

    - #### sendRecentMessage

          public final int sendRecentMessage(java.io.Serializable groupid,
                                             java.lang.String text)

      给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送文本消息
      参数:
        `groupid` - groupid
        `text` - 不可为空
      返回:
        为0表示成功， 其他值表示异常

    - #### sendRecentMessage

          public final int sendRecentMessage(java.io.Serializable groupid,
                                             byte[] data)

      给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送二进制消息
      参数:
        `groupid` - groupid
        `data` - 不可为空
      返回:
        为0表示成功， 其他值表示异常

    - #### sendRecentMessage

          public final int sendRecentMessage(java.io.Serializable groupid,
                                             java.lang.String text,
                                             boolean last)

      给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送文本消息
      参数:
        `groupid` - groupid
        `text` - 不可为空
        `last` - 是否最后一条
      返回:
        为0表示成功， 其他值表示异常

    - #### sendRecentMessage

          public final int sendRecentMessage(java.io.Serializable groupid,
                                             byte[] data,
                                             boolean last)

      给指定groupid的WebSocketGroup下最近接入的WebSocket节点发送二进制消息
      参数:
        `groupid` - groupid
        `data` - 不可为空
        `last` - 是否最后一条
      返回:
        为0表示成功， 其他值表示异常

    - #### getOnlineNodes

          protected final java.util.Collection<java.net.InetSocketAddress> getOnlineNodes(java.io.Serializable groupid)

      获取在线用户的节点地址列表
      参数:
        `groupid` - groupid
      返回:
        地址列表

    - #### getOnlineRemoteAddress

          protected final java.util.Map<java.net.InetSocketAddress,java.util.List<java.lang.String>> getOnlineRemoteAddress(java.io.Serializable groupid)

      获取在线用户的详细连接信息
      参数:
        `groupid` - groupid
      返回:
        地址集合

    - #### getAttribute

          public final <T> T getAttribute(java.lang.String name)

      获取当前WebSocket下的属性
      类型参数:
        `T` - 属性值的类型
      参数:
        `name` - 属性名
      返回:
        属性值

    - #### removeAttribute

          public final <T> T removeAttribute(java.lang.String name)

      移出当前WebSocket下的属性
      类型参数:
        `T` - 属性值的类型
      参数:
        `name` - 属性名
      返回:
        属性值

    - #### setAttribute

          public final void setAttribute(java.lang.String name,
                                         java.lang.Object value)

      给当前WebSocket下的增加属性
      参数:
        `name` - 属性值
        `value` - 属性值

    - #### getGroupid

          public final java.io.Serializable getGroupid()

      获取当前WebSocket所属的groupid
      返回:
        groupid

    - #### getSessionid

          public final java.io.Serializable getSessionid()

      获取当前WebSocket的会话ID， 不会为null
      返回:
        sessionid

    - #### getRemoteAddress

          public final java.net.SocketAddress getRemoteAddress()

      获取客户端直接地址, 当WebSocket连接是由代理服务器转发的，则该值固定为代理服务器的IP地址
      返回:
        SocketAddress

    - #### getRemoteAddr

          public final java.lang.String getRemoteAddr()

      获取客户端真实地址 同 HttpRequest.getRemoteAddr()
      返回:
        String

    - #### getWebSocketGroup

          protected final WebSocketGroup getWebSocketGroup()

      获取当前WebSocket所属的WebSocketGroup， 不会为null
      返回:
        WebSocketGroup

    - #### getWebSocketGroup

          protected final WebSocketGroup getWebSocketGroup(java.io.Serializable groupid)

      获取指定groupid的WebSocketGroup, 没有返回null
      参数:
        `groupid` - groupid
      返回:
        WebSocketGroup

    - #### getWebSocketGroups

          protected final java.util.Collection<WebSocketGroup> getWebSocketGroups()

      获取当前进程节点所有在线的WebSocketGroup
      返回:
        WebSocketGroup列表

    - #### onOpen

          public java.io.Serializable onOpen(HttpRequest request)

      返回sessionid, null表示连接不合法或异常,默认实现是request.getSessionid(false)，通常需要重写该方法
      参数:
        `request` - HttpRequest
      返回:
        sessionid

    - #### createGroupid

          protected abstract java.io.Serializable createGroupid()

      创建groupid， null表示异常， 必须实现该方法， 通常为用户ID为groupid
      返回:
        groupid

    - #### onRead

          public void onRead(AsyncConnection channel)

      标记为WebSocketBinary才需要重写此方法
      参数:
        `channel` - 请求连接

    - #### onConnected

          public void onConnected()

    - #### onMessage

          public void onMessage(java.lang.String text)

    - #### onPing

          public void onPing(byte[] bytes)

    - #### onPong

          public void onPong(byte[] bytes)

    - #### onMessage

          public void onMessage(byte[] bytes)

    - #### onFragment

          public void onFragment(java.lang.String text,
                                 boolean last)

    - #### onFragment

          public void onFragment(byte[] bytes,
                                 boolean last)

    - #### onClose

          public void onClose(int code,
                              java.lang.String reason)

    - #### close

          public final void close()

      显式地关闭WebSocket

    - #### toString

          public java.lang.String toString()

      覆盖:
        `toString` 在类中 `java.lang.Object`