Accessor: net/WebSocketClient


This accessor sends and/or receives messages from a web socket at the specified host and port. WebSockets provide full-duplex communication channels over a single TCP/IP connection. In initialize(), it begins connecting to the web socket server. Once the connection is established, a true boolean is sent to the connected output. If connection is not established immediately, the accessor will attempt to reconnect numberOfRetries times at an interval of reconnectInterval.

Whenever an input is received on the toSend input, the message is sent to the socket. If the socket is not yet open, this accessor will, by default, queue the message to send when the socket opens, unless the discardMessagesBeforeOpen parameter is true, in which case, input messages that are received before the socket is opened will be discarded. If messages are queued and throttleFactor is non-zero, then whenever a message is queued to be later sent, the accessor's input handler will stall by a number of milliseconds given by the queue size times the throttleFactor. The longer the queue, the longer the stall. Note that this will likely block the host from executing, so this feature should be used with caution.

Whenever a message is received from the socket, that message is produced on the 'received' output. Note that the message may actually be sent over multiple 'frames', but the frames will be aggregated and produced as one message.

When wrapup() is invoked, this accessor closes the connection.

If the connection is dropped midway, the swarmlet may monitor the 'connected' output for a value 'false' and attempt a reconnection by providing either a port or server input.

The default type for both sending and receiving is 'application/json', which allows sending and receiving anything that has a string representation in JSON. The types supported by this implementation include at least:

  • application/json: The this.send() function uses JSON.stringify() and sends the result with a UTF-8 encoding. An incoming byte stream will be parsed as JSON, and if the parsing fails, will be provided as a string interpretation of the byte stream.
  • text/*: Any text type is sent as a string encoded in UTF-8.
  • image/x: Where x is one of json, png, gif, and more. In this case, the data passed to this.send() is assumed to be an image, as encoded on the host, and the image will be encoded as a byte stream in the specified format before sending. A received byte stream will be decoded as an image, if possible.

    When a model with an instance of this accessor stops executing, there are two mechanisms by which data in transit can be lost. In both cases, warning messages or error messages will be issued to the host to be displayed or otherwise handled as the host sees fit.

  • First, there might be queued messages that were received on toSend but have not yet been sent, either because the socket has not yet been opened or because it was closed from the other side.

  • Second, a message might be received from the server after shutdown has commenced. In particular, received messages are handled asynchronously by a handler function that can be invoked at any time, and that handler might be invoked after it is no longer possible for this accessor to produce outputs (it has entered its wrapup phase of execution).

    The server might similarly lose messages by the same two mechanisms occurring on the server side. In that case, messages will presumably be displayed on the server side.

    Accessors that extend this one can override the toSendInputHandler function to customize what is sent. See RosPublisher.js for an example.

    This accessor requires the 'webSocket' module.

  • $$Id$$
  • Hokeun Kim, Marcus Pan, Edward A. Lee, Matt Weber
Name Type Description
server string The IP address or domain name of server. Defaults to 'localhost'.
port int The port on the server to connect to. Defaults to -1, which means wait for a non-negative input before connecting.
toSend The data to be sent over the socket.
Name Type Description
connected boolean Output `true` on connected and `false` on disconnected.
received The data received from the web socket server.
Name Type Description
receiveType string The MIME type for incoming messages, which defaults to 'application/json'.
sendType string The MIME type for outgoing messages, which defaults to 'application/json'.
connectTimeout int The time in milliseconds to wait before giving up on a connection (default is 1000).
numberOfRetries int The number of times to retry if a connection fails. Defaults to 5.
timeBetweenRetries int The time between retries in milliseconds. Defaults to 500.
trustAll boolean Whether to trust any server certificate. This defaults to false. Setting it to true means that if sslTls is set to true, then any certificate provided by the server will be trusted.
trustedCACertPath string If sslTls is set to true and trustAll is set to false, then this option needs to specify the fully qualified filename for the file that stores the certificate of a certificate authority (CA) that this client will use to verify server certificates. This path can be any of those understood by the Ptolemy host, e.g. paths beginning with $CLASSPATH/. FIXME: Need to be a list of paths for certificates rather than a single path.
sslTls boolean Whether SSL/TLS is enabled. This defaults to false.
discardMessagesBeforeOpen boolean If true, then any messages received on `toSend` before the socket is open will be discarded. This defaults to false.
throttleFactor int If non-zero, specifies a time (in milliseconds) to stall when a message is queued because the socket is not yet open. The time of the stall will be the queue size (after adding the message) times the throttleFactor. This defaults to 100. Making it non-zero causes the input handler to take time if there are pending unsent messages.


(static) connect()

Initiate a connection to the server using the current parameter values, set up handlers for for establishment of the connection, incoming data, errors, and closing from the server, and set up a handler for inputs on the toSend() input port.


(static) initialize()

Set up input handlers, and if the current value of the 'port' input is non-negative, initiate a connection to the server using the current parameter values, and set up handlers for for establishment of the connection, incoming data, errors, and closing from the server.


(static) onClose()

Send false to 'connected' output. This will be called if either side closes the connection.


(static) onMessage()

Send the message received from web socket to the 'received' output.


(static) onOpen()

Executes once web socket establishes a connection. Sets 'connected' output to true.


(static) sendToWebSocket()

Sends JSON data to the web socket.


(static) setup()

Set up the accessor by defining the parameters, inputs, and outputs.


(static) toSendInputHandler()

Handles input on 'toSend'.


(static) wrapup()

Close the web socket connection.