Open Message Queue 5.0.1--WebSocket Integration
 
 

(WebSockets are introduced in Open MQ 5.0.1. You must have build 3 or higher)
Back to Open MQ 5.0.1 Index Page

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.0.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 4.0.1 build (date >= 09_23_2013)
  • 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

 

 
 
Terms of Use; Privacy Policy; Copyright ©2013-2015 (revision 20150226.965aeb8)
 
 
Close
loading
Please Confirm
Close