Back to Open MQ 5.0.1 Index Page

Enable Broker for 'wsjms' WebSocket Service
Enable Broker for 'wssjms' WebSocket Service
Broker WebSocket Configuration
Connect MQ JMS Client to Broker over WebSocket
Connect STOMP Client to Broker over WebSocket
Using Broker WebSocket Services with GlassFish Server

WebSocket is an HTML5 technology that provides bidirectional communication which starts via an HTTP request. Open MQ provides WebSocket support in two ways -- Java JMS over WebSocket and STOMP (1.2), and we include an experimental mapping via JSON. In addition, we provide support for both unencrypted and secure WebSocket connections.

This page provides setup details for using WebSocket in Open MQ.

Enable Broker for 'wsjms' WebSocket Service

The default 'ws' WebSocket service in a broker is named 'wsjms'. To enable the 'wsjms' service, add it to the following broker property setting
imq.service.activelist
By default it is set to following
imq.service.activelist=jms,admin
To add 'wsjms',
imq.service.activelist=jms,admin,wsjms

A broker 'ws' WebSocket service, by default, listens at port 7670 which is set by broker property
imq.wsjms.ws.port=7670

A broker WebSocket service can support 3 types of WebSocket clients

• mqjms - Java JMS client over WebSocket
• mqstomp - Any WebSocket client that sends the STOMP 1.2 protocol to broker
• mqjsonstomp - Any WebSocket client that sends JSON formatted STOMP 1.2 protocol to broker

The type(s) of WebSocket clients that a broker can support is controlled by the broker property
imq.<websocket-service-name>.services

By default, the 'wsjms' and 'wssjms' (see next section) WebSocket services support all 3 types of clients,
imq.wsjms.services=mqjms,mqstomp,mqjsonstomp

Enable Broker for 'wss' WebSocket Service

• Before start broker, please follow the Administration Guide on how to set up broker SSL certificate
• Add a 'wss' WebSocket service to broker property
  imq.service.activelist
  
  The default 'wss' WebSocket service in a broker is named 'wssjms'. To enable the 'wssjms' service, for example,
  imq.service.activelist=jms,admin,wssjms
  
  The 'wssjms' service, by default, listens at port 7671 which is set by broker property
  imq.wssjms.wss.port=7671
  
  
• Start the broker with -passfile option that specifies imq.keystore.password

Broker WebSocket Configuration

Please see mq/lib/props/broker/default.properties for a current list of broker properties that configures a WebSocket service. Some of them have been mentioned in above sections. The following broker property can also be set

imq.<websocket-service-name>.allowedOrigins - A list of comma separated origins (protocol scheme and hostname are checked) that are allowed to access the WebSocket service. When it is not set (default), all origins are allowed
imq.<wss-service-name>.wss.requireClientAuth - Set to true to require (default not) SSL client authentication for the 'wss' service

How to Connect a Java JMS Client to Broker over WebSocket (mqjms)

• To make a Java JMS client communicate broker over WebSocket,
  • Set connection factory property
    imqAddressList=mqws://<broker-host>:<broker-ws-port>/<ws-service-name>
    for 'ws' WebSocket service, or
    imqAddressList=mqwss://<broker-host>:<broker-wss-port>/<wss-service-name>
    for 'wss' WebSocket service
    
    For example,
    imqAddressList=mqws://mybrokerhost:7670/wsjms
    
    
  • Add following jar files to application classpath in addition to imq.jar, jms.jar. These jar files are in mq/lib
    javax.websocket-api.jar
    tyrus-client.jar
    tyrus-core.jar
    tyrus-websocket-core.jar
    tyrus-spi.jar
    tyrus-container-grizzly.jar
    grizzly-http-server.jar
    grizzly-framework.jar
    grizzly-http.jar
    
    There are JMS client examples in mq/examples. These examples can be run over WebSocket by setting connection factory property imqAddressList appropriately. For example,
    • Download latest OpenMQ (>= 5.1)
    • Start broker with the default WebSocket service 'wsjms' enabled
      mq/bin/imqbrokerd -Dimq.service.activelist=wsjms,admin -tty
      
    • to run the mq/examples/jms20/syncqueue example over WebSocket connecting to the broker 'wsjms' service,
      • 1. set CLASSPATH to include above jar files and mq/lib/jms.jar, mq/lib/imq.jar
        2. run, for example, on the broker host
           java -DimqAddressList=mqws://localhost:7670/wsjms SendObjectMsgsToQueue <queue-name>
           
           
    • to run the mq/examples/applications/uclient (UniversalClient), connecting to the broker 'wsjms' service,
      • 1. set CLASSPATH to include above jar files and mq/lib/jms.jar, mq/lib/imq.jar
        2. run
           java UniversalClient
        3. When the UniversalClient GUI comes up, click 'Actions'->'Connect ...', the 'Universal Client: Connection information' dialog will show up, then in the 'Connection Factory Attributes' text field, set 'imqAddressList' to
           imqAddressList=mqws://<broker-host>:7670/wsjms
           then click 'Connect'

• To work with 'wss' WebSocket service
  Use Java keytool to export/import broker certificate and use Java SSL system properties to configure client for Secure WebSocket communication with broker
  javax.net.ssl.keyStorePassword
  javax.net.ssl.trustStorePassword
  java.net.ssl.keyStore
  javax.net.ssl.trustStore
  
  
• To Work with HTTP proxy
  Use Java system HTTP proxy properties
  http.proxyHost
  http.proxyPort
  https.proxyHost
  https.proxyPort

How to Connect a STOMP Client (mqstomp) to Broker over WebSocket

• Simply create a WebSocket using URL
  ws://<broker-host>:<broker-ws-port>/<ws-service-name>/mqstomp
  for 'ws' WebSocket service, or
  wss://<broker-host>:<broker-wss-port>/<wss-service-name>/mqstomp
  for 'wss' WebSocket service
  
  For example,
  ws://mybrokerhost:7670/wsjms/mqstomp
  
  
• For STOMP JavaScript client, set the WebSocket binaryType to either "blob" or "arraybuffer"

Here is a simple example of STOMP client in JavaScript.

How to Connect a JSON format STOMP Client (mqjsonstomp) to Broker over WebSocket

• Simply create a WebSocket using URL
  
  ws://<broker-host>:<broker-ws-port>/<ws-service-name>/mqjsonstomp
  for 'ws' WebSocket service, or
  wss://<broker-host>:<broker-wss-port>/<wss-service-name>/mqjsonstomp
  for 'wss' WebSocket service
  
  For example,
  ws://mybrokerhost:7670/wsjms/mqjsonstomp

Here is a simple example of JSON format STOMP client in JavaScript.

JSON Objects for JSON Format STOMP Client over WebSocket (mqjsonstomp)

• A mqjsonstomp client sends JSON formatted STOMP frames to broker. A JSON formatted STOMP frame is a JSON object that consists
  • A JSON String field 'command' whose value is a STOMP command
  • A JSON Object for 'headers' representing a STOMP frame headers
  • A JSON Object for 'body' representing a STOMP frame body
    The 'body' JSON Object contains
    • An optional JSON String field 'type' which can have value 'text' or 'bytes'. If this field is omitted, it defaults to 'text'
    • An optional JSON String field 'encoder', which currently can only be 'base64' to specify the encoding scheme used for the message body if 'type' is 'bytes'
    • A JSON Object 'text' which represents the message body
• The following shows some JavaScript example code of a mqjsonstomp client sending/receiving a STOMP frame to/from broker
  var jmsframe = {};
  jmsframe.command = "CONNECT";
  jmsframe.headers = {"login":"guest", "passcode":"guest", "accept-version":"1.2"};
  var data = JSON.stringify(jmsframe);
  websocket.send(data);
  
  function onMessage(evt) {
      var jmsframe = JSON.parse(evt.data);
      //process jmsframe.command
      //process jmsframe.headers
      //process jmsframe.body
  }

Using Broker WebSocket Services with GlassFish Server

OpenMQ (GlassFish MQ) is the system JMS provider for GlassFish server. To use broker WebSocket services with GlassFish server, currently

• Download latest GlassFish latest release (>= 4.1)
• Example steps to enable the 'wsjms' in the GlassFish embedded broker
  • asadmin start-domain
  • asadmin create-local-instance myinst
  • asadmin set myinst.jms-service.start-args="-Dimq.service.activelist=jms,admin,wsjms"
  • asadmin start-instance myinst
  • run any imqcmd to lazily start the embedded broker, for example, on the 'myinst' host
    imqcmd list dst -b :<broker-portmapper-port>
    where <broker-portmapper-port> is the JMS_PROVIDER_PORT in 'asadmin create-local-instance' output