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配置:
<beans xmlns="http://www.springframework.org/schema/beans"
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:handlers>
<websocket:mapping path="/myHandler" handler="myHandler"/>
</websocket:handlers>
<bean id="myHandler" class="org.springframework.samples.MyHandler"/>
</beans>
本示例用於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配置:
<beans xmlns="http://www.springframework.org/schema/beans"
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:handlers>
<websocket:mapping path="/myHandler" handler="myHandler"/>
<websocket:handshake-interceptors>
<bean class="org.springframework.web.socket.server.support.HttpSessionHandshakeInterceptor"/>
</websocket:handshake-interceptors>
</websocket:handlers>
<bean id="myHandler" class="org.springframework.samples.MyHandler"/>
</beans>
更高級的選項是擴展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
中的<absolute-ordering />
元素,應該可以選擇性地啓用或禁用web片段(和SCI掃描),如下例所示:
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
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">
<absolute-ordering/>
</web-app>
然後可以根據名稱選擇性地啓用web片段,比如Spring自己的SpringServletContainerInitializer
,它爲Servlet 3 Java初始化API提供支持,下面的示例展示瞭如何做到這一點:
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
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">
<absolute-ordering>
<name>spring_web</name>
</absolute-ordering>
</web-app>
服務器配置
每個基礎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配置:
<beans xmlns="http://www.springframework.org/schema/beans"
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">
<bean class="org.springframework...ServletServerContainerFactoryBean">
<property name="maxTextMessageBufferSize" value="8192"/>
<property name="maxBinaryMessageBufferSize" value="8192"/>
</bean>
</beans>
對於客戶端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配置:
<beans xmlns="http://www.springframework.org/schema/beans"
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:handlers>
<websocket:mapping path="/echo" handler="echoHandler"/>
<websocket:handshake-handler ref="handshakeHandler"/>
</websocket:handlers>
<bean id="handshakeHandler" class="org.springframework...DefaultHandshakeHandler">
<constructor-arg ref="upgradeStrategy"/>
</bean>
<bean id="upgradeStrategy" class="org.springframework...JettyRequestUpgradeStrategy">
<constructor-arg ref="serverFactory"/>
</bean>
<bean id="serverFactory" class="org.eclipse.jetty...WebSocketServerFactory">
<constructor-arg>
<bean class="org.eclipse.jetty...WebSocketPolicy">
<constructor-arg value="SERVER"/>
<property name="inputBufferSize" value="8092"/>
<property name="idleTimeout" value="600000"/>
</bean>
</constructor-arg>
</bean>
</beans>
允許的起源
在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配置:
<beans xmlns="http://www.springframework.org/schema/beans"
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:handlers allowed-origins="http://mydomain.com">
<websocket:mapping path="/myHandler" handler="myHandler" />
</websocket:handlers>
<bean id="myHandler" class="org.springframework.samples.MyHandler"/>
</beans>