Class: Client

Client

new Client(name) → {amps.Client}

This is the constructor of Client class.
Parameters:
Name Type Description
name string Unique name for the client (important for queues and sow).
Source:
Returns:
Type
amps.Client

Methods

ack(topic, bookmark) → {Promise}

This method ACKs a message queue message using the topic and bookmark values.
Parameters:
Name Type Description
topic String The topic of the message to ACK.
bookmark String The bookmark of the message to ACK.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.ack('queue-topic', '12290412031115262887|1484244707000000008|');

ack(message) → {Promise}

This method ACKs a message queue message using the message object.
Parameters:
Name Type Description
message object AMPS message object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.ack(queueMessage);

connect(uri, authenticatoropt) → {Promise}

This method connects the AMPS client to the server. It automatically calls logon() upon successful connection.
Parameters:
Name Type Attributes Description
uri string The URI containing all required credentials/addresses/types.
authenticator object <optional>
The authenticator object for custom authentication scenarios. The default authenticator is provided. See amps.DefaultAuthenticator for details.
Source:
Returns:
The promise object with the result of fullfilling/failing the connection promise.
Type
Promise
Example
var client = new amps.Client('my-application');

client.connect('ws://localhost:9100/amps/json')
    .then(function() {
        // now the client is ready to send and receive any commands
        // ...
    })
    .catch(function(err) {
        console.error('Connection error: ', err);
    });

deltaSubscribe(onMessage, topic, filteropt, optionsopt) → {Promise}

This method performs the delta_subscribe command. The delta_subscribe command is like the subscribe command except that subscriptions placed through delta_subscribe will receive only messages that have changed between the SOW record and the new update. If delta_subscribe is used on a record which does not currently exist in the SOW or if it is used on a topic which does not have a SOW-topic store defined, then delta_subscribe behaves like a subscribe command.
Parameters:
Name Type Attributes Description
onMessage function a message handler that will be called each time a message is received.
topic string The topic argument in sow (must be a string).
filter string <optional>
The filter argument in sow (must be a string).
options object <optional>
The options like ackType, bookmark, commandId, etc in an object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.deltaSubscribe(function(message) { console.log(message); }, 'topic')
    .then(function(subscriptionId) { console.log(subscriptionId); })
    .catch(function(err) { console.error('err: ', err); });

disconnect()

This method disconnects the client from an AMPS server (if the connection existed).
Source:

errorHandler(errorHandler) → {amps.Client}

This method sets up the error handler for all general errors such as connection issues, exceptions, etc.
Parameters:
Name Type Description
errorHandler function the callback function that will be invoked in case of a general error.
Source:
Returns:
the amps.Client object.
Type
amps.Client
Example
var client = new amps.Client().errorHandler(function(err) {
    console.error('err: ', err);
});

execute(command, handler, timeoutopt) → {Promise}

This is the command execution interface method that allows to send commands that don't have a convenience method or require additional settings that are not provided by the convenience methods. The purpose of the method is to execute Command objects.
Parameters:
Name Type Attributes Description
command amps.Command a Command object.
handler function a callback to report the messages (including ack messages if they were requested).
timeout int <optional>
a timeout value for the command execution in milliseconds.
Source:
Returns:
The promise object fullfilled with the command id created.
Type
Promise
Example
var subscribeCommand = new amps.Command('subscribe')
  .topic('messages')
  .filter('/id > 20');

client.execute(subscribeCommand, function(message) {
    console.log('message: ', message.data);
}).then(function(commandId) {
    console.log('commandId: ', commandId);
});

heartbeat(interval, timeoutopt) → {amps.Client}

This method sets up the heartbeat mode with the server. It sends a command to AMPS that starts or refreshes a heartbeat timer. When a heartbeat timer is active, AMPS publishes periodic heartbeat messages to AMPS and expects the client to respond with a heartbeat message. If the client does not provide a heartbeat within the time specified, AMPS logs an error and disconnects the connection.
Parameters:
Name Type Attributes Description
interval int the heartbeat value in seconds.
timeout int <optional>
the timeout value in seconds. By default it is the heartbeat interval value times 2.
Source:
Returns:
the client object.
Type
amps.Client
Example
// Initialize a client with the heartbeat of 5 seconds
var client = new amps.Client().heartbeat(5);

publish(topic, data, optionsopt)

This method performs the publish command. The publish command is the primary way to inject messages into the AMPS processing stream. A publish command received by AMPS will be forwarded to other connected clients with matching subscriptions.
Parameters:
Name Type Attributes Description
topic string the topic to publish data.
data the data to publish to a topic.
options object <optional>
an object with options, like: {expiration: 30, ...}
Source:
Example
client.publish('topic', '{"id": 1}');

serverVersion() → {string}

This method returns the server version returned by the AMPS server in the logon acknowledgement. If logon has not been performed yet, returns null.
Source:
Returns:
the version of the AMPS server.
Type
string

sow(onMessage, topic, filteropt, optionsopt) → {Promise}

This method performs the sow command. The sow command is use to query the contents of a previously defined SOW Topic. A sow command can be used to query an entire SOW Topic, or a filter can be used to further refine the results found inside a SOW Topic. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide.
Parameters:
Name Type Attributes Description
onMessage function a message handler that will be called each time a message is received.
topic string The topic argument in sow (must be a string).
filter string <optional>
The filter argument in sow (must be a string).
options object <optional>
The options like ackType, bookmark, commandId, etc in an object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.sow(function(message) { console.log(message); }, 'sow-topic')
    .then(function(subscriptionId) { console.log(subscriptionId); })
    .catch(function(err) { console.error('err: ', err); });

sowAndDeltaSubscribe(onMessage, topic, filteropt, optionsopt) → {Promise}

This method performs the sow_and_delta_subscribe command. A sow_and_delta_subscribe command is used to combine the functionality of commands sow and a delta_subscribe in a single command. The sow_and_delta_subscribe command is used (a) to query the contents of a SOW topic (this is the sow command); and (b) to place a subscription such that any messages matching the subscribed SOW topic and query filter will be published to the AMPS client (this is the delta_subscribe command). As with the delta_subscribe command, publish messages representing updates to SOW records will contain only the information that has changed. If a sow_and_delta_subscribe is issued on a record that does not currently exist in the SOW topic, or if it is used on a topic that does not have a SOW-topic store defined, then a sow_and_delta_subscribe will behave like a sow_and_subscribe command.
Parameters:
Name Type Attributes Description
onMessage function a message handler that will be called each time a message is received.
topic string The topic argument in sow (must be a string).
filter string <optional>
The filter argument in sow (must be a string).
options object <optional>
The options like ackType, bookmark, commandId, etc in an object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.sowAndDeltaSubscribe(function(message) { console.log(message); }, 'sow-topic')
    .then(function(subscriptionId) { console.log(subscriptionId); })
    .catch(function(err) { console.error('err: ', err); });

sowAndSubscribe(onMessage, topic, filteropt, optionsopt) → {Promise}

This method performs the sow_and_subscribe command. A sow_and_subscribe command is used to combine the functionality of sow and a subscribe command in a single command. The sow_and_subscribe command is used (a) to query the contents of a SOW topic (this is the sow command); and (b) to place a subscription such that any messages matching the subscribed SOW topic and query filter will be published to the AMPS client (this is the subscribe command). As with the subscribe command, publish messages representing updates to SOW records will contain only information that has changed.
Parameters:
Name Type Attributes Description
onMessage function a message handler that will be called each time a message is received.
topic string The topic argument in sow (must be a string).
filter string <optional>
The filter argument in sow (must be a string).
options object <optional>
The options like ackType, bookmark, commandId, etc in an object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.sowAndSubscribe(function(message) { console.log(message); }, 'sow-topic')
    .then(function(subscriptionId) { console.log(subscriptionId); })
    .catch(function(err) { console.error('err: ', err); });

subscribe(onMessage, topic, filteropt, optionsopt) → {Promise}

This method performs the subscribe command. The subscribe command is the primary way to retrieve messages from the AMPS processing stream. A client can issue a subscribe command on a topic to receive all published messages to that topic in the future. Additionally, content filtering can be used to choose which messages the client is interested in receiving.
Parameters:
Name Type Attributes Description
onMessage function a message handler that will be called each time a message is received.
topic string The topic argument in subscribe (must be a string).
filter string <optional>
The filter argument in subscribe (must be a string).
options object <optional>
The options like ackType, bookmark, commandId, etc in an object.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.subscribe(function(message) { console.log(message); }, 'topic')
    .then(function(subscriptionId) { console.log(subscriptionId); })
    .catch(function(err) { console.error('err: ', err); });

unsubscribe(subId) → {Promise}

This method performs the unsubscribe command. The unsubscribe command unsubscribes the client from the topic which messages the client is is no more interested in receiving.
Parameters:
Name Type Description
subId string The id of the subscription.
Source:
Returns:
The promise object with the results of execution of the command.
Type
Promise
Example
client.unsubscribe('123');

version() → {string}

This method returns a static string built into amps.js.
Source:
Returns:
the version of this AMPS client.
Type
string