sendMessage method

Future<void> sendMessage(
  1. String message, [
  2. String? sequence,
  3. int? delayTimeout,
  4. ClientMessageListener? listener,
  5. bool? enqueueWhileDisconnected,
])

Operation method that sends a message to the Server.

The message is interpreted and handled by the Metadata Adapter associated to the current Session. This operation supports in-order guaranteed message delivery with automatic batching. In other words, messages are guaranteed to arrive exactly once and respecting the original order, whatever is the underlying transport (HTTP or WebSockets). Furthermore, high frequency messages are automatically batched, if necessary, to reduce network round trips.
Upon subsequent calls to the method, the sequential management of the involved messages is guaranteed. The ordering is determined by the order in which the calls to sendMessage are issued.
If a message, for any reason, doesn't reach the Server (this is possible with the HTTP transport), it will be resent; however, this may cause the subsequent messages to be delayed. For this reason, each message can specify a "delayTimeout", which is the longest time the message, after reaching the Server, can be kept waiting if one of more preceding messages haven't been received yet. If the "delayTimeout" expires, these preceding messages will be discarded; any discarded message will be notified to the listener through ClientMessageListener.onDiscarded. Note that, because of the parallel transport of the messages, if a zero or very low timeout is set for a message and the previous message was sent immediately before, it is possible that the latter gets discarded even if no communication issues occur. The Server may also enforce its own timeout on missing messages, to prevent keeping the subsequent messages for long time.
Sequence identifiers can also be associated with the messages. In this case, the sequential management is restricted to all subsets of messages with the same sequence identifier associated.
Notifications of the operation outcome can be received by supplying a suitable listener. The supplied listener is guaranteed to be eventually invoked; listeners associated with a sequence are guaranteed to be invoked sequentially.
The "UNORDERED_MESSAGES" sequence name has a special meaning. For such a sequence, immediate processing is guaranteed, while strict ordering and even sequentialization of the processing is not enforced. Likewise, strict ordering of the notifications is not enforced. However, messages that, for any reason, should fail to reach the Server whereas subsequent messages had succeeded, might still be discarded after a server-side timeout, in order to ensure that the listener eventually gets a notification.
Moreover, if "UNORDERED_MESSAGES" is used and no listener is supplied, a "fire and forget" scenario is assumed. In this case, no checks on missing, duplicated or overtaken messages are performed at all, so as to optimize the processing and allow the highest possible throughput.

Lifecycle Since a message is handled by the Metadata Adapter associated to the current connection, a message can be sent only if a connection is currently active. If the special enqueueWhileDisconnected flag is specified it is possible to call the method at any time and the client will take care of sending the message as soon as a connection is available, otherwise, if the current status is "DISCONNECTED*", the message will be abandoned and the ClientMessageListener.onAbort event will be fired.
Note that, in any case, as soon as the status switches again to "DISCONNECTED*", any message still pending is aborted, including messages that were queued with the enqueueWhileDisconnected flag set to true.
Also note that forwarding of the message to the server is made in a separate thread, hence, if a message is sent while the connection is active, it could be aborted because of a subsequent disconnection. In the same way a message sent while the connection is not active might be sent because of a subsequent connection.

  • message a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.
  • sequence an alphanumeric identifier, used to identify a subset of messages to be managed in sequence; underscore characters are also allowed. If the "UNORDERED_MESSAGES" identifier is supplied, the message will be processed in the special way described above. The parameter is optional; if set to null, "UNORDERED_MESSAGES" is used as the sequence name.
  • delayTimeout a timeout, expressed in milliseconds. If higher than the Server configured timeout on missing messages, the latter will be used instead.
    The parameter is optional; if a negative value is supplied, the Server configured timeout on missing messages will be applied.
    This timeout is ignored for the special "UNORDERED_MESSAGES" sequence, although a server-side timeout on missing messages still applies.
  • listener an object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available.
  • enqueueWhileDisconnected if this flag is set to true, and the client is in a disconnected status when the provided message is handled, then the message is not aborted right away but is queued waiting for a new session. Note that the message can still be aborted later when a new session is established.

⚠ WARNING ⚠ The completion of the returned Future indicates that the operation has been accepted and is in progress, but not necessarily completed. To receive notifications about events generated by the operation, it is necessary to register a ClientMessageListener.

Implementation

Future<void> sendMessage(String message, [String? sequence, int? delayTimeout, ClientMessageListener? listener, bool? enqueueWhileDisconnected]) async {
  var arguments = <String, dynamic>{
    'message': message,
    'sequence': sequence,
    'delayTimeout': delayTimeout,
    'enqueueWhileDisconnected': enqueueWhileDisconnected
  };
  return await NativeBridge.instance.client_sendMessage(_id, listener, arguments);
}