Spring Websocket Plugin

  • Tags: /
  • Latest: 1.1.0
  • Last Updated: 02 August 2014
  • Grails version: 2.4.3 > *
  • Authors: zyro
0 vote
Dependency:
compile ":spring-websocket:1.1.0"

 Documentation  Source  Issues

Summary

Spring Websocket Plugin

Description

Spring Websocket Grails Plugin

The plugin targets Grails 2.4.0+. Lower versions will not work because they lack the mandatory Spring version 4.0+. Currently, only the Grails Tomcat Plugins (tomcat-7.0.52+/tomcat8-8.0.1.1+) are known to work with this plugin.

This plugin aims at making the WebSocket support introduced in Spring 4.0 available to Grails applications.

You can use the corresponding Spring docs/apis/samples as a reference. That is mentioned multiple times in this readme because there is everything explained in fine detail.

Grails version requirements:

grails-spring-websocketGrails
1.0.x2.4.0 - 2.4.2
1.1.x2.4.3+

Installation

To install the plugin into a Grails application add the following line to your BuildConfig.groovy plugins section:

compile ':spring-websocket:1.1.0'

If you are using version 8.x of the tomcat plugin (8.0.1.1+), there is nothing extra to do. If you are using version 7.x (7.0.52+), add the following BuildConfig.groovy settings to ensure proper functionality:

grails.tomcat.nio = true
grails.tomcat.scan.enabled = true

Usage

The plugin makes the Spring websocket/messaging web-mvc controller annotations useable in Grails controllers, too.

I think basic usage is explained best by example code. But: the code below is just some very minimal it-works proof. Check the Spring docs/apis/samples for more advanced use-cases, e.g. security and authentication.

Controller (annotated handler method)

/grails-app/controllers/example/ExampleController.groovy:

package example

import org.springframework.messaging.handler.annotation.MessageMapping import org.springframework.messaging.handler.annotation.SendTo

class ExampleController {

def index() {}

@MessageMapping("/hello") @SendTo("/topic/hello") protected String hello(String world) { return "hello from controller, ${world}!" }

}

Unless you want your handler method to be exposed as controller action, it is important that you define the annotated method as private or protected.

Client-side (sock.js / stomp.js)

/grails-app/views/example/index.gsp:

<!DOCTYPE html>
<html>
   <head>
      <meta name="layout" content="main"/>

<asset:javascript src="jquery" /> <asset:javascript src="spring-websocket" />

<script type="text/javascript"> $(function() { var socket = new SockJS("${createLink(uri: '/stomp')}"); var client = Stomp.over(socket);

client.connect({}, function() { client.subscribe("/topic/hello", function(message) { $("#helloDiv").append(JSON.parse(message.body)); }); });

$("#helloButton").click(function() { client.send("/app/hello", {}, JSON.stringify("world")); }); }); </script> </head> <body> <button id="helloButton">hello</button> <div id="helloDiv"></div> </body> </html>

This would be the index view of the controller above. The js connects to the message broker and subscribes to /topic/hello . For this example, I added a button allowing to trigger a send/receive roundtrip.

While this example shows JQuery used with the asset-pipeline plugin, the use of JQuery is not required.

If you prefer the resources plugin instead of the asset-pipeline plugin, you can use the spring-websocket resources module - it includes sock.js and stomp.js:

<r:require module="spring-websocket" />

Service (brokerMessagingTemplate bean)

You can also inject and use the brokerMessagingTemplate bean to send messages directly, e.g. from a service.

/grails-app/services/example/ExampleService.groovy:

class ExampleService {

def brokerMessagingTemplate

void hello() { brokerMessagingTemplate.convertAndSend "/topic/hello", "hello from service!" }

}

Configuration

If the default values are fine for your application, you are good to go. No configuration required then.

The following configuration options are available (e.g. by adding some or all of them to your Config.groovy ):

Keygrails.plugin.springwebsocket.dispatcherServlet.additionalMappings
TypeCollection<String>
Default["/stomp/"]
DescriptionBy default, the GrailsDispatcherServlet is mapped to .dispatch. Because the sock.js support in Spring is not using a separate servlet but additional handlers for the DispatcherServlet, the relevant endpoints have to be covered by the servlet-mapping. Usually, you will want to have your stomp endpoints covered.

Keygrails.plugin.springwebsocket.messageBroker.applicationDestinationPrefixes
TypeCollection<String>
Default["/app"]
DescriptionPrefixes to filter destinations targeting application annotated methods. Annotations should not contain the destination prefix. E.g. with the default value, this means if your js client sends to /app/foo/bar , your controller annotation should look like @MessageMapping('/foo/bar')

Keygrails.plugin.springwebsocket.messageBroker.userDestinationPrefix
TypeString
Default"/user/"
DescriptionThe Prefix to identify user destinations.

Keygrails.plugin.springwebsocket.messageBroker.brokerPrefixes
TypeCollection<String>
Default["/queue", "/topic"]
DescriptionPrefixes to filter destinations targeting the broker. This setting affects the direction server --> client. E.g. with the default value, the broker would process a message to /topic/foo but not one to /unknown/prefix/foo .

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.enabled
Typeboolean (groovy truth)
Defaultfalse
DescriptionIf enabled, use a "real" stomp relay like RabbitMQ or ActiveMQ (with their corresponding stomp components active). If not (default), a simple Map-based broker implementation will be used.

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.host
TypeString
Default127.0.0.1
DescriptionOnly relevant if stompRelay.enabled = true . The host of the stomp relay (IP address or hostname).

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.port
Typeint
Default61613
DescriptionOnly relevant if stompRelay.enabled = true . The port of the stomp relay.

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.systemLogin
TypeString
Defaultguest
DescriptionOnly relevant if stompRelay.enabled = true . The login of the stomp relay for the shared system connection.

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.systemPasscode
TypeString
Defaultguest
DescriptionOnly relevant if stompRelay.enabled = true . The passcode of the stomp relay for the shared system connection.

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.clientLogin
TypeString
Defaultguest
DescriptionOnly relevant if stompRelay.enabled = true . The login of the stomp relay for the client connections.

Keygrails.plugin.springwebsocket.messageBroker.stompRelay.clientPasscode
TypeString
Defaultguest
DescriptionOnly relevant if stompRelay.enabled = true . The passcode of the stomp relay for the client connections.

Keygrails.plugin.springwebsocket.stompEndpoints
TypeCollection<Collection<String>>
Default[["/stomp"]]
DescriptionExpose a STOMP endpoint at the specified url path (or paths). For every inner Collection, a stomp endpoint is registered with those url path(s). E.g. with the default value, one stomp endpoint is registered and listening at /stomp

Keygrails.plugin.springwebsocket.clientInboundChannel.threadPoolSize
TypeRange<Integer>
Default4..10
DescriptionCore to max thread pool size for the TaskExecutor of the client inbound channel (client --> server)

Keygrails.plugin.springwebsocket.clientOutboundChannel.threadPoolSize
TypeRange<Integer>
Default4..10
DescriptionCore to max thread pool size for the TaskExecutor of the client outbound channel (server --> client)

Keygrails.plugin.springwebsocket.useCustomConfig
Typeboolean (groovy truth)
Defaultfalse
DescriptionSet this to true if you want to take full control and responsibility for the spring websocket configuration. Then, all other config options above will have no effect. Neither the WebSocketConfig nor the GrailsSimpAnnotationMethodMessageHandler will be exposed to the application.

If you need more sophisticated configuration options, currently the way to go would be using the useCustomConfig setting and heading over to the Spring docs/apis/samples covering the configuration of websockets/messaging. You can of course use the plugin's WebSocketConfig for orientation. It uses @EnableWebSocketMessageBroker and implements WebSocketMessageBrokerConfigurer . But for bigger config adjustments, it is likely you end up extending Spring's WebSocketMessageBrokerConfigurationSupport .

Future versions of this plugin may cover more configuration options.