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). |
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. |
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. |
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. |
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. |
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).
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. |
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. |
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. |
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, ...} |
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.
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. |
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. |
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. |
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. |
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. |
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.
Returns:
the version of this AMPS client.
- Type
- string