Listener 的设计跟 WebSocket 的经典接口非常像。开发者用起来，会有熟悉感（就是出于这种角度考虑的）。

区别在于三个点：

* 有流
* 有事件
* 有元信息

监听器可以有很多不同的实现（比如转换协议...）。内置的几个常用监听器，可见后续的资料。

### 1、监听器
 
* Listener 监听器（可双向互听）

| 接口                                                  | 描述                 | 备注    |
|--------------------------------|-------------|------|
| listener::onOpen(session)                      | 当打开会话时     |  <mark>此时，服务端不能发消息；客户端可以发</mark>         |
| listener::onMessage(session, message)   | 当收到消息时     |           |
| listener::onClose(session)                      | 当关闭会话时     |           |
| listener::onError(session, error)              | 当出错时           |           |

服务端 onOpen 时，握手未完成，不能给“当前会话”发消息。具体参考：[《协议指令流详解》](/article/768)

* Listener 内置的常用监听器

开发者还可以定义或扩展实现，当然也可以基于 Listener 从零始定制。

| 监听器实现类          |                              |                  |
|--------------|------------------------------|------------------|
| SimpleListener   | 简单监听器                        | Listener 的空实现    |
| PipelineListener | 管道监听器                        | Listener 的链式组织实现 |
| EventListener    | 事件监听器，根据消息事件路由（message::event） | 相当于消息的路由器        |
| PathListener     | 路径监听器，根据握手地址路由（session::path）  | 相当于路径（频道）的路由器<br/>一般用在服务端    |
| | | |
| BrokerListener     | 经纪人监听器  | 提供经纪人转发服务    |

* PipelineListener 管道监听器主要接口（内部有个监听器列表）

| 接口                          | 说明                             | 
| ----------------- | ------------------- | 
| prev(listener) -> self    | 在列表头部添加监听器     | 
| next(listener) -> self     | 在列表尾部添加监听器     | 
| size()                         | 列表数量                      | 


* EventListener 事件监听器，根据消息事件路由（内部有个事件的监听器路由器）

| 接口                          | 说明                             | 
| ----------------- | ------------------- | 
| doOnOpen(listener) -> self    | 代理 onOpen 事件处理     | 
| doOnMessage(listener) -> self     | 代理 onMessage 事件处理（所有 event 路由处理，会先经过这里）     | 
| doOnClose(listener) -> self     | 代理 onClose 事件处理     | 
| doOnError(listener) -> self     | 代理 onError 事件处理     |  
| doOn(event, listener) -> self     | doOnMessage 执行完后，代理 event 的路由处理     | 


* PathListener 路径监听器，根据握手地址路由（内部有个路径的监听器路由器，一般用于服务端）

| 接口                          | 说明                             | 
| ----------------- | ------------------- | 
| doOf(path, listener) -> self     | 代理 path 的路由监听     | 
| of(path) -> EventListener     | 创建一个 path 下的 EventListener。是  doOf 的另一种体验方式     | 





### 2、监听器接口

* Listener 监听器完整接口（以 Java 为例）

```
/**
 * 监听器
 */
public interface Listener {
    /**
     * 打开时
     *
     * @param session 会话
     */
    void onOpen(Session session) throws IOException;

    /**
     * 收到消息时
     *
     * @param session 会话
     * @param message 消息
     */
    void onMessage(Session session, Message message) throws IOException;

    /**
     * 关闭时
     *
     * @param session 会话
     */
    void onClose(Session session);

    /**
     * 出错时
     *
     * @param session 会话
     * @param error   错误信息
     */
    void onError(Session session, Throwable error);
}
```