This accessor sends and/or receives messages from a TCP socket at
the specified host and port. If the value of the port input is initially
negative, then this accessor waits until it receives a non-negative port
input before making a connection. Otherwise,
upon initialization, it initiates a connection to the
specified server. If at any time during execution it receives
a 'port' input, then it will close any open socket and, if the new
'port' value is non-negative, open
a new socket to the current 'host' and 'port'.
When the connection is established, a true boolean is sent to
the connected output. If the connection is broken during execution, then a false
boolean is sent to the connected output. The swarmlet could respond to this by
retrying to connect (send an event to either the port or host input).
Whenever an input is received on the toSend input,
the data on that input is sent to the socket. If the socket is not yet open,
this accessor will, by default, queue the message to send when a socket next opens,
unless the discardMessagesBeforeOpen parameter is true, in which case,
input messages that are received before the socket is opened will be
discarded.
Whenever a message is received from the socket, that message is
produced on the received output.
When wrapup() is invoked, this accessor closes the connection.
The send and receive types can be any of those supported by the host.
The list of supported types will be provided as options for the sendType
and receiveType parameter. For the Ptolemy II host, these include at
least 'string', 'number', 'image', and a variety of numeric types.
If both ends of the socket are known to be JavaScript clients, then you should use the 'number' data type for numeric data. If one end or the other is not JavaScript, then you can use more specified types such as 'float' or 'int', if they are supported by the host. In all cases, received numeric data will be converted to JavaScript 'number' when emitted. For sent data, this will try to convert a JavaScript number to the specified type. The type 'number' is equivalent to 'double'.
When type conversions are needed, e.g. when you send a double
with sendType set to int, or an int with sendType set to byte,
then a "primitive narrowing conversion" will be applied, as specified here:
https://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.3.
For numeric types, you can also send an array all at once by providing an
array to the toSend input port.
The elements of the array will be sent in sequence all
at once, and may be received in one batch. If both ends have
rawBytes set to false (specifying message framing), then these
elements will be emitted at the receiving end all at once in a single
array. Otherwise, they will be emitted one at a time.
For strings, you can also send an array of strings in a single call, but these will be simply be concatenated and received as a single string.
If the rawBytes option is set to false, then each data item provided on toSend,
of any type or array of types, will be coalesced into a single message and
the receiving end (if it also has rawBytes set to false) will emit the entire
message, and only the message, exactly once. Otherwise, a message may get
fragmented, emitted in pieces, or coalesced with subsequent messages.
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
toSendbut 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.
This accessor requires the 'socket' module.
- Version:
- $$Id$$
- Source:
Inputs:
| Name | Type | Description |
|---|---|---|
host |
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. |
Outputs:
| Name | Type | Description |
|---|---|---|
connected |
boolean | Output `true` on connected and `false` on disconnected. |
received |
The data received from the web socket server. |
Parameters:
| Name | Type | Description |
|---|---|---|
connectTimeout |
int | The time to wait (in milliseconds) before declaring a connection attempt to have failed. This defaults to 6000. |
idleTimeout |
int | The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout. |
discardMessagesBeforeOpen |
boolean | If true, then discard any messages passed to SocketClient.send() before the socket is opened. If false, then queue the messages to be sent when the socket opens. This defaults to false. |
keepAlive |
boolean | Whether to keep a connection alive and reuse it. This defaults to true. |
maxUnsentMessages |
int | The maximum number of unsent messages to queue before further calls to this.send() will fail. A value of 0 means no limit. This defaults to 100. |
noDelay |
boolean | If true, data as sent as soon as it is available (the default). If false, data may be accumulated until a reasonable packet size is formed in order to make more efficient use of the network (using Nagle's algorithm). |
pfxKeyCertPassword |
string | If sslTls is set to true and the server requires client authentication, then this option needs to specify the password for the pfx key-cert file specified by pfxKeyCertPath. |
pfxKeyCertPath |
string | If sslTls is set to true and the server requires client authentication, then this option needs to specify the fully qualified filename for the file that stores the private key and certificate that this client will use to authenticate itself to the server. This path can be any of those understood by the Ptolemy host, e.g. paths beginning with $CLASSPATH/. |
rawBytes |
boolean | If true (the default), then transmit only the data bytes provided to this.send() without any header. If false, then prepend sent data with length information and assume receive data starts with length information. Setting this false on both ends will ensure that each data item passed to this.send() is emitted once in its entirety at the receiving end, as a single message. When this is false, the receiving end can emit a partially received message or could concatenate two messages and emit them together. |
receiveBufferSize |
int | The size of the receive buffer. Defaults to 65536. |
receiveType |
string | See above. |
reconnectAttempts |
int | The number of times to try to reconnect. If this is greater than 0, then a failure to attempt will trigger additional attempts. This defaults to 10. |
reconnectInterval |
int | The time between reconnect attempts, in milliseconds. This defaults to 1000 (1 second). |
sendBufferSize |
int | The size of the receive buffer. Defaults to 65536. |
sendType |
string | See above. |
sslTls |
boolean | Whether SSL/TLS is enabled. This defaults to false. |
trustAll |
boolean | Whether to trust servers. 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. FIXME: Need to provide a trusted list if this is false. |
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. |
Methods
(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) dataReceivedHandler()
Function is called by client when data has been received over the connection. This has been refactored out of exports.connect to facilitate overriding by an extending accessor.
(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) isOpen()
Return true if this client has an open connection to the server.
(static) send()
Send the specified data if the client is set and open,
reconnect the client if the socket is closed, and otherwise either
discard or queue the data to send later depending on the value of
discardMessagesBeforeOpen.
(static) setup()
Set up the accessor by defining the parameters, inputs, and outputs.
(static) toSendInputHandler()
Handle input on 'toSend' by sending the specified data to the server.
(static) wrapup()
Close the web socket connection.