java websocket api_Spring Framework 参考文档（WebSocket API）

WebSocket API

Spring Framework提供了一个WebSocket API，你可以使用它来编写处理WebSocket消息的客户端和服务器端应用程序。

WebSocketHandler

创建WebSocket服务器就像实现WebSocketHandler一样简单，或者更可能是扩展TextWebSocketHandler或BinaryWebSocketHandler，下面的示例使用TextWebSocketHandler：

import org.springframework.web.socket.WebSocketHandler;

import org.springframework.web.socket.WebSocketSession;

import org.springframework.web.socket.TextMessage;

public class MyHandler extends TextWebSocketHandler {

@Override

public void handleTextMessage(WebSocketSession session, TextMessage message) {

// ...

}

}

有专门的WebSocket Java配置和XML命名空间支持将前面的WebSocket处理程序映射到特定的URL，如下面的示例所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;

import org.springframework.web.socket.config.annotation.WebSocketConfigurer;

import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(myHandler(), "/myHandler");

}

@Bean

public WebSocketHandler myHandler() {

return new MyHandler();

}

}

下面的示例显示了与前面示例等价的XML配置：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:websocket="http://www.springframework.org/schema/websocket"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/websocket

http://www.springframework.org/schema/websocket/spring-websocket.xsd">

本示例用于Spring MVC应用程序，并且应该包含在DispatcherServlet的配置中，然而，Spring的WebSocket支持不依赖于Spring MVC，在WebSocketHttpRequestHandler的帮助下，将WebSocketHandler集成到其他http服务环境中相对简单。

WebSocket握手

定制初始的HTTP WebSocket握手请求的最简单方法是通过HandshakeInterceptor，它公开握手之前和之后的方法，你可以使用这样的拦截器来阻止握手或使WebSocketSession的任何属性有效，下面的示例使用内置的拦截器将HTTP会话属性传递给WebSocket会话：

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(new MyHandler(), "/myHandler")

.addInterceptors(new HttpSessionHandshakeInterceptor());

}

}

下面的示例显示了与前面示例等价的XML配置：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:websocket="http://www.springframework.org/schema/websocket"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/websocket

http://www.springframework.org/schema/websocket/spring-websocket.xsd">

更高级的选项是扩展DefaultHandshakeHandler，该处理程序执行WebSocket握手的步骤，包括验证客户端源、协商子协议和其他细节。如果应用程序需要配置定制的RequestUpgradeStrategy以适应WebSocket服务器引擎和还不支持的版本，那么它可能还需要使用这个选项(有关此主题的更多信息，请参阅部署)，Java配置和XML命名空间都使配置自定义HandshakeHandler成为可能。

Spring提供了一个WebSocketHandlerDecorator基类，你可以使用它来修饰WebSocketHandler具有额外的行为。默认情况下，在使用WebSocket Java配置或XML命名空间时，会提供并添加日志记录和异常处理实现。ExceptionWebSocketHandlerDecorator捕获来自任何WebSocketHandler的所有未捕获的异常，并以状态1011关闭WebSocket会话，这表示服务器错误。

部署

Spring WebSocket API很容易集成到Spring MVC应用程序中，其中DispatcherServlet同时服务于HTTP WebSocket握手和其他HTTP请求，通过调用WebSocketHttpRequestHandler，很容易将其集成到其他HTTP处理场景中。这很方便，也很容易理解，但是，对于JSR-356运行时，需要特别考虑。

Java WebSocket API(JSR-356)提供了两种部署机制，第一个涉及Servlet容器类路径扫描(Servlet 3特性)在启动时，另一个是Servlet容器初始化时使用的注册API。这两种机制都无法为所有HTTP处理使用单个“前端控制器” - 包括WebSocket握手和所有其他HTTP请求 - 比如Spring MVC的DispatcherServlet。

这是JSR-356的一个重要限制，Spring的WebSocket支持地址具有特定于服务器的RequestUpgradeStrategy实现，即使在JSR-356运行时运行也是如此。对于Tomcat、Jetty、GlassFish、WebLogic、WebSphere和Undertow(和WildFly)，目前存在这样的策略。

已经创建了克服Java WebSocket API中上述限制的请求，可以在eclipse-ee4j/websocket-api#211中进行跟踪。Tomcat、Undertow和WebSphere提供了它们自己的API选项，可以实现这一点，Jetty也是如此，我们希望更多的服务器也能这样做。

第二个需要考虑的问题是，具有JSR-356支持的Servlet容器预计将执行ServletContainerInitializer(SCI)扫描，这可能会减慢应用程序的启动速度 — 在某些情况下，会显著降低启动速度。如果在升级到支持JSR-356的Servlet容器版本后观察到重大影响，通过使用web.xml中的元素，应该可以选择性地启用或禁用web片段(和SCI扫描)，如下例所示：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="

http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"

version="3.0">

然后可以根据名称选择性地启用web片段，比如Spring自己的SpringServletContainerInitializer，它为Servlet 3 Java初始化API提供支持，下面的示例展示了如何做到这一点：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="

http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"

version="3.0">

spring_web

服务器配置

每个基础WebSocket引擎都公开了控制运行时特性的配置属性，比如消息缓冲区大小、空闲超时等等。

对于Tomcat、WildFly和GlassFish，你可以将ServletServerContainerFactoryBean添加到WebSocket Java配置中，如下面的示例所示：

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Bean

public ServletServerContainerFactoryBean createWebSocketContainer() {

ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean();

container.setMaxTextMessageBufferSize(8192);

container.setMaxBinaryMessageBufferSize(8192);

return container;

}

}

下面的示例显示了与前面示例等价的XML配置：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:websocket="http://www.springframework.org/schema/websocket"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/websocket

http://www.springframework.org/schema/websocket/spring-websocket.xsd">

对于客户端WebSocket配置，你应该使用WebSocketContainerFactoryBean(XML)或ContainerProvider.getWebSocketContainer()(Java配置)。

对于Jetty，需要提供预配置的Jetty WebSocketServerFactory，并通过WebSocket Java配置将其插入Spring的DefaultHandshakeHandler，下面的示例展示了如何做到这一点：

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(echoWebSocketHandler(),

"/echo").setHandshakeHandler(handshakeHandler());

}

@Bean

public DefaultHandshakeHandler handshakeHandler() {

WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER);

policy.setInputBufferSize(8192);

policy.setIdleTimeout(600000);

return new DefaultHandshakeHandler(

new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy)));

}

}

下面的示例显示了与前面示例等价的XML配置：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:websocket="http://www.springframework.org/schema/websocket"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/websocket

http://www.springframework.org/schema/websocket/spring-websocket.xsd">

允许的源

在Spring Framework 4.1.5中，WebSocket和SockJS的默认行为是只接受相同源的请求，也可以允许所有或指定的源列表。这种检查主要是为浏览器客户端设计的，没有什么可以阻止其他类型的客户端修改Origin header值(请参阅RFC 6454: Web Origin概念以了解更多细节)。

三种可能的行为是：

只允许相同源的请求(默认)：在这种模式下，当启用SockJS时，Iframe HTTP响应header X-Frame-Options被设置为SAMEORIGIN，并且JSONP传输被禁用，因为它不允许检查请求的源，因此，当启用该模式时，不支持IE6和IE7。

允许指定的源列表：每个允许的源必须以http://或https://开始，在这种模式下，当启用SockJS时，IFrame传输将被禁用，因此，当启用该模式时，将不支持IE6到IE9。

允许所有的源：要启用此模式，你应该提供*作为允许的源值，在这种模式下，所有的传输都是可用的。

你可以配置WebSocket和SockJS允许的源，如下面的例子所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;

import org.springframework.web.socket.config.annotation.WebSocketConfigurer;

import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("http://mydomain.com");

}

@Bean

public WebSocketHandler myHandler() {

return new MyHandler();

}

}

下面的示例显示了与前面示例等价的XML配置：

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:websocket="http://www.springframework.org/schema/websocket"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/websocket

http://www.springframework.org/schema/websocket/spring-websocket.xsd">