@ -984,11 +984,12 @@ public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport
@@ -984,11 +984,12 @@ public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport
[[websocket-stomp]]
== STOMP Over WebSocket Messaging Architecture
The WebSocket protocol defines two main types of messages -- text and binary --
but leaves their content undefined. Instead it's expected that the client and
server may agree on using a sub-protocol, i.e. a higher-level protocol that defines
the message content. Using a sub-protocol is optional but either way the client
and server both need to understand how to interpret messages.
The WebSocket protocol defines two types of messages, text and binary, but their
content is undefined. It's expected that the client and server may agree on using
a sub-protocol (i.e. a higher-level protocol) to define message semantics.
While the use of a sub-protocol with WebSocket is completely optional either way
client and server will need to agree on some kind of protocol to help interpret
messages.
@ -996,12 +997,14 @@ and server both need to understand how to interpret messages.
@@ -996,12 +997,14 @@ and server both need to understand how to interpret messages.
=== Overview of STOMP
http://stomp.github.io/stomp-specification-1.2.html#Abstract[STOMP] is a simple
text-oriented messaging protocol that was originally created for scripting languages
(such as Ruby, Python, and Perl) to connect to enterprise message brokers. It is
designed to address a subset of commonly used patterns in messaging protocols. STOMP
can be used over any reliable 2-way streaming network protocol such as TCP and WebSocket.
such as Ruby, Python, and Perl to connect to enterprise message brokers. It is
designed to address a subset of commonly used messaging patterns. STOMP can be
used over any reliable 2-way streaming network protocol such as TCP and WebSocket.
Although STOMP is a text-oriented protocol, the payload of messages can be
either text or binary.
STOMP is a frame based protocol with frames modeled on HTTP. This is the
structure of a frame:
STOMP is a frame based protocol whose frames are modeled on HTTP. The structure
It is important to know that a server cannot send unsolicited messages. All messages
from a server must be in response to a specific client subscription, and the
+"subscription-id"+ header of the server message must match the +"id"+ header of the
client subscription.
====
The above overview is intended to provide the most basic understanding of the
STOMP protocol. It is recommended to review the protocol
http://stomp.github.io/stomp-specification-1.2.html[specification], which is
easy to follow and manageable in terms of size.
http://stomp.github.io/stomp-specification-1.2.html[specification] in full.
The following summarizes the benefits for an application of using STOMP over WebSocket:
The benefits of using STOMP as a WebSocket sub-protocol:
* Standard message format
* Application-level protocol with support for common messaging patterns
* Client-side support, e.g. https://github.com/jmesnil/stomp-websocket[stomp.js], https://github.com/cujojs/msgs[msgs.js]
* The ability to interpret, route, and process messages on both the client and server-side
* The option to plug in a message broker -- RabbitMQ, ActiveMQ, many others -- to broadcast messages (explained later)
* No need to invent a custom message format
* Use existing https://github.com/jmesnil/stomp-websocket[stomp.js] client in the browser
* Ability to route messages to based on destination
* Option to use full-fledged message broker such as RabbitMQ, ActiveMQ, etc. for broadcasting
Most importantly the use of STOMP (vs plain WebSocket) enables the Spring Framework
to provide a programming model for application-level use in the same way that
@ -1088,10 +1101,12 @@ Spring MVC provides a programming model based on HTTP.
@@ -1088,10 +1101,12 @@ Spring MVC provides a programming model based on HTTP.
[[websocket-stomp-enable]]
=== Enable STOMP over WebSocket
The Spring Framework provides support for using STOMP over WebSocket through
the +spring-messaging+ and +spring-websocket+ modules. It's easy to enable it.
Here is an example of configuring a STOMP WebSocket endpoint with SockJS fallback
options. The endpoint is available for clients to connect to a URL path `/portfolio`:
the +spring-messaging+ and +spring-websocket+ modules.
Here is an example of exposing a STOMP WebSocket/SockJS endpoint at the URL path
`/portfolio` where messages whose destination starts with "/app" are routed to
message-handling methods (i.e. application work) and messages whose destinations
start with "/topic" or "/queue" will be routed to the message broker (i.e.
broadcasting to other connected clients):
[source,java,indent=0]
[subs="verbatim,quotes"]
@ -1103,23 +1118,21 @@ options. The endpoint is available for clients to connect to a URL path `/portfo
@@ -1103,23 +1118,21 @@ options. The endpoint is available for clients to connect to a URL path `/portfo
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
@Override
public void configureMessageBroker(MessageBrokerRegistry config) {
config.setApplicationDestinationPrefixes("/app");
config.enableSimpleBroker("/queue", "/topic");
}
@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
registry.addEndpoint("/portfolio").withSockJS();
}
// ...
@Override
public void configureMessageBroker(MessageBrokerRegistry config) {
config.setApplicationDestinationPrefixes("/app");
config.enableSimpleBroker("/topic", "/queue");
}
}
----
XML configuration equivalent:
and in XML:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
@ -1137,13 +1150,29 @@ XML configuration equivalent:
@@ -1137,13 +1150,29 @@ XML configuration equivalent:
Rossen Stoyanchev
11 years ago
