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.

When communicating with EMS, to publish a messages on a specific EMS destination include the message field name _dest. To distinguish between topics and queues the destination can be prefixed with either "TOPIC:" or "QUEUE:", for example "TOPIC:MyDest" or "QUEUE:MyDest". A destination with no prefix is a topic.

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 publish a message on a specific EMS destination add a string field to the message; for example:

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

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.

removeKVMap(name)

Remove a key-value map.

Parameters:
Name Type Description
name string The key-value map name.
See:

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.

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.

When communicating with EMS, to subscribe to messages published on a specific EMS destination use a subscription matcher that includes the message field name _dest. To distinguish between topics and queues the destination name can be prefixed with either "TOPIC:" or "QUEUE:", for example "TOPIC:MyDest" or "QUEUE:MyDest". A destination name with no prefix is a topic.

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 on a specific EMS destination, create a subscription matcher for that destination; for example:

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

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: