Wednesday, November 12, 2014

SSJS and Websockets

***websocket project has been broken out into its own project, on openntf***

A new use case recently emerged during my latest development efforts to build a websocket based application / dashboard.  In addition to the requestURI routing path feature that updates all clients via websocket in the UI, I also needed to execute some server side logic for any messages coming in through that channel.  I thought of a few options:

  • Have the client side web browser that is behaving as the visual dashboard post the data back to the server via Ajax / REST call 
  • Send update via REST call and have the server process and dispatch the message via websocket
  • Load up an embedded client on the same server as the websocket server to receive and process the messages

I opted for the last approach, and took it a bit further than just loading a single client.  In the next incremental release of the Domino WebSocket plugin, developers will be able to register SSJS libraries to consume / intercept websocket client events via simple API call.  NOTE:  The SSJS is compiled and executed under the Rhino scripting engine, not the XPages version of SSJS.  There are some syntax differences you need to be aware of, namely type declarations (i.e. var str:String = "some string" will not compile must only be var str="some string").  Be sure to omit them when writing SSJS for websockets.  Below are the steps required to register a script library with the websocket plugin:

1) Create your SSJS script library websocket client (must be of type SSJS when creating lib in designer)

Below is the output from the SSJS client to any users on /chat.nsf

2) Register your Rhino compliant SSJS lib a couple of ways... via SSJS API call

command line

(note that * covers all events onOpen, onMessage, onClose, and onError)

A few other important notes about the default objects in scope of your script(s):
  • session (uses server's Id, so make sure the server has appropriate rights to the target nsf housing the script lib)
  • websocketClient  (you can use this object to send messages out in response to incoming events)
  • event (just the name of the event onOpen, onClose, onMessage, onError)
  • socketMessage is only available via onMessage event
  • bundleUtils  (facilitates accessing specific OSGi plugins in the XPage runtime see print method in above code, target class must use no arg constructor)

New Command line options:

  • register-script (takes four arguments host uri event scriptpath)
  • reload-scripts (takes no arguments and reloads from source nsf and re-compiles all scripts)
  • show-scripts  (takes no arguments, renders all the registered scripts)
  • remove-script (takes one argument that is the path to the lib i.e. /chat.nsf/scriptlib)


  • At some point I might refactor the client out of the websocket plugin into its own to allow SSJS clients access to any remote websocket server (Domino, Node, JavaEE based).

I'll be pushing this up to github and openntf soon, please check back in a few days.... thanks for taking the time


latest release available on openntf