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:

sendReply(reply, request, options)

Send a reply message in response to a request message.

This call returns immediately. When the send completes successfully, the eFTL library calls your onComplete callback.

Parameters:
Name Type Description
reply eFTLMessage The reply message to send.
request eFTLMessage The request message.
options object A JavaScript object holding request callbacks.
Properties
Name Type Argument Description
onComplete onComplete <optional>
 Process reply completion.
onError onError <optional>
 Process request errors.

sendRequest(request, timeout, options)

Publish a request message.

This call returns immediately. When the reply is received the eFTL library calls your onReply callback.

Parameters:
Name Type Description
request eFTLMessage The request message to publish.
timeout number The number of milliseconds to wait for a reply.
options object A JavaScript object holding request callbacks.
Properties
Name Type Argument Description
onReply onReply <optional>
 Process reply.
onError onError <optional>
 Process request errors.

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.

For durable subscriptions, this call will cause the persistence service to remove the durable subscription as well, along with any persisted messages.

Programs receive subscription identifiers via their onSubscribe handlers.

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

unsubscribeAll()

Close all subscriptions.

For durable subscriptions, this call will cause the persistence service to remove the durable subscription as well, along with any persisted messages.

Programs receive subscription identifiers via their onSubscribe handlers.

See: