服务器 API

服务器启动与停止监听器

Socketio4j 允许你为服务器注册监听器 启动 和 停止 事件。 监听器在执行时具有 异常隔离，确保某个监听器的失败不会影响其他监听器或服务器的生命周期。

启动监听器

添加启动监听器

ServerStartListener startListener = s -> {
    System.out.println(
        "Server started on " + s.getConfiguration().getPort()
    );
};

server.addStartListener(startListener);

移除启动监听器

server.removeStartListener(startListener);

停止监听器

添加停止监听器

ServerStopListener stopListener = s -> {
    System.out.println("Server stopped");
};

server.addStopListener(stopListener);

移除停止监听器

server.removeStopListener(stopListener);

执行保证

• 启动监听器在服务器成功启动后被调用

• 停止监听器在优雅关闭过程中被调用

• 每个监听器都以 异常隔离

• 监听器抛出的异常 不会 中断：

  • 服务器启动或关机

  • 其他已注册的监听器

最佳实践

• 保持监听器逻辑轻量且非阻塞

• 避免在监听器中执行长时间运行或阻塞操作

• 仅将监听器用于日志、指标和协调

命名空间

默认命名空间

根命名空间 ("/") 会自动创建。

添加命名空间

SocketIONamespace chat = server.addNamespace("/chat");

获取命名空间

SocketIONamespace chat = server.getNamespace("/chat");

移除命名空间

server.removeNamespace("/chat");

获取所有命名空间

Collection<SocketIONamespace> namespaces = server.getAllNamespaces();

客户端

获取所有已连接的客户端（默认命名空间）

Collection<SocketIOClient> clients = server.getAllClients();

按会话 ID 获取客户端

SocketIOClient client = server.getClient(uuid);

返回 null 如果未找到。

广播

向所有客户端广播（所有命名空间）

server.getBroadcastOperations()
      .sendEvent("announcement", "Hello everyone");

向房间广播（跨所有命名空间）

server.getRoomOperations("room1", "room2")
      .sendEvent("message", "Hello rooms");

事件监听器（默认命名空间）

事件监听器（类型化）

server.addEventListener("chat", Message.class, (client, data, ack) -> {
    System.out.println(data);
});

多类型事件监听器

server.addMultiTypeEventListener(
    "event",
    (client, data, ack) -> {},
    String.class,
    ChatMessage.class
);

通配事件监听器

CatchAllEventListener anyListener = (client, event, args) -> {
    System.out.println("Event: " + event);
};
// add
server.addOnAnyEventListener(anyListener);

// remove
server.removeOnAnyEventListener(anyListener);

别名：

• onAny(...)

• offAny(...)

事件拦截器

server.addEventInterceptor((client, event, args) -> {
    return true; // allow
});

用于验证、过滤或安全检查。

移除所有事件监听器

server.removeAllListeners("eventName");

连接生命周期监听器

连接监听器

server.addConnectListener(client -> {
    System.out.println("Connected: " + client.getSessionId());
});

断开监听器

server.addDisconnectListener(client -> {
    System.out.println("Disconnected");
});

Ping / Pong 监听器

server.addPingListener(client -> {});
server.addPongListener(client -> {});

有助于监控连接健康状态。

监听器自动注册

注册监听器对象

server.addListeners(new ChatEventHandler());

使用显式类注册

server.addListeners(new ChatEventHandler(), ChatEventHandler.class);

支持基于注解的监听器。

查看 事件 以获取更多细节