Class: eFTLConnection

eFTLConnection

new eFTLConnection()

A connection object represents a program's connection to an eFTL server.

The eFTL JavaScript library creates new instances of eFTLConnection internally.

Programs use connection objects to send messages, and subscribe to messages.

Programs receive connection objects through onConnect, onError, onDisconnect, and onReconnect callbacks.

See:

Methods

acknowledge(message)

Acknowledge this message.

Messages consumed from subscriptions with a client acknowledgment mode must be explicitly acknowledged. The eFTL server will stop delivering messages to the client once the server's configured maximum number of unacknowledged messages is reached.

Parameters:
Name Type Description
message object The message being acknowledged.
See:

acknowledgeAll(message)

Acknowledge all messages up to and including this message.

Messages consumed from subscriptions with a client acknowledgment mode must be explicitly acknowledged. The eFTL server will stop delivering messages to the client once the server's configured maximum number of unacknowledged messages is reached.

Parameters:
Name Type Description
message object The message being acknowledged.
See:

createKVMap(name) → {eFTLKVMap}

Create an eFTLKVMap.
Parameters:
Name Type Description
name string The key-value map name.
Returns:
A new key-value map.
Type
eFTLKVMap

createMessage() → {eFTLMessage}

Create an eFTLMessage.
Returns:
A new message.
Type
eFTLMessage

disconnect()

Disconnect from the eFTL server.

Programs may disconnect to free server resources.

This call returns immediately; disconnecting continues asynchronously. When the connection has closed, the eFTL library calls your onDisconnect callback.

See:

getClientId() → {string}

Gets the client identifier for this connection.

See:
Returns:
The unique client identifier.
Type
string

isConnected() → {boolean}

Determine whether this connection to the eFTL server is open or closed.
Returns:
true if this connection is open; false otherwise.
Type
boolean

publish(message, options)

Publish a one-to-many message to all subscribing clients.

This call returns immediately; publishing continues asynchronously. When the publish completes successfully, the eFTL library calls your onComplete callback.

It is good practice to publish each message to a specific destination by using the message field name _dest.

Parameters:
Name Type Description
message eFTLMessage Publish this message.
options object A JavaScript object holding publish callbacks.
Properties
Name Type Argument Description
onComplete onComplete <optional>
 Process publish completion.
onError onError <optional>
 Process publish errors.
Example

To direct a message to a specific destination, add a string field to the message; for example:

message.set("_dest", "myTopic");

reconnect()

Reopen a closed connection.

You may call this method within your onDisconnect callback.

This call returns immediately; connecting continues asynchronously. When the connection is ready to use, the eFTL library calls your onReconnect callback.

Reconnecting automatically re-activates all subscriptions on the connection. The eFTL library invokes your onSubscribe callback for each successful resubscription.

subscribe(options) → {object}

Subscribe to messages.

Register a subscription for one-to-many messages.

This call returns immediately; subscribing continues asynchronously. When the subscription is ready to receive messages, the eFTL library calls your onSubscribe callback.

A matcher can narrow subscription interest in the inbound message stream.

It is good practice to subscribe to messages published to a specific destination by using the message field name _dest.

Parameters:
Name Type Description
options object A JavaScript object holding subscription callbacks.
Properties
Name Type Argument Description
matcher string <optional>
 The subscription uses this content matcher to narrow the message stream.
durable string <optional>
 The subscription is associated with this durable name.
ack string <optional>
 An optional message acknowledgment mode; 'auto', 'client', or 'none'. Default is 'auto'.
type string <optional>
 An optional durable type; 'shared' or 'last-value'.
key string <optional>
 The key field for 'last-value' durable subscriptions.
onSubscribe onSubscribe <optional>
 The new subscription is ready.
onError onError <optional>
 Process subscription errors.
onMessage onMessage <optional>
 Process inbound messages
See:
Returns:
The subscription identifier.
Type
object
Example

To subscribe to messages published to a specific destination, create a subscription matcher for that destination; for example:

var matcher = '{"_dest":"myTopic"}';


An acknowledgment mode for the subscription can be set to automatically acknowledge consumed
messages, require explicit client acknowledgment of the consumed messages, or to disable
message acknowledgment altogether. The default is to automatically acknowledge consumed messages.


When explicit client acknowledgment is specified the eFTL server will stop delivering messages 
to the client once the server's configured maximum number of unacknowledged messages is reached.

unsubscribe(subscriptionId)

Close a subscription.

Programs receive subscription identifiers via their onSubscribe handlers.

Parameters:
Name Type Description
subscriptionId object Close this subscription.
See:

unsubscribeAll()

Close all subscriptions.

See: