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.