AMPS C/C++ Client Class Reference AMPS C/C++ Client Version 5.3.5.1

Public Member Functions | List of all members
AMPS::Command Class Reference

Command is an encapsulation of a single AMPS command sent by the client. More...

`#include <ampsplusplus.hpp>`

## Public Member Functions
| Command (const std::string &command_)
| Creates an object to represent the given AMPS command, such as "sow" or "subscribe". More...
| Command (const char *command_, size_t commandLen_)
| Creates an object to represent the given AMPS command, such as "sow" or "subscribe". More...
| Command (Message::Command::Type command_)
| Creates an object to represent the given AMPS command, such as "sow" or "subscribe". More...
Command & | reset (const std::string &command_)
| Resets the fields of self, and sets the command to command_. More...
Command & | reset (const char *command_, size_t commandLen_)
| Resets the fields of self, and sets the command to command_. More...
Command & | reset (Message::Command::Type command_)
| Resets the fields of self, and sets the command to command_. More...
Command & | setSowKey (const std::string &sowKey_)
| Sets the SowKey field of the command, typically used for a publish command to a topic in the state of the world when that topic is configured to require the publisher to set the SowKey. More...
Command & | setSowKey (const char *sowKey_, size_t sowKeyLen_)
| Sets the SowKey field of the command, typically used for a publish command to a topic in the state of the world when that topic is configured to require the publisher to set the SowKey. More...
Command & | setSowKeys (const std::string &sowKeys_)
| Sets the SowKeys for the command. More...
Command & | setSowKeys (const char *sowKeys_, size_t sowKeysLen_)
| Sets the SowKeys for the command. More...
Command & | setCommandId (const std::string &cmdId_)
Command & | setCommandId (const char *cmdId_, size_t cmdIdLen_)
Command & | setTopic (const std::string &topic_)
Command & | setTopic (const char *topic_, size_t topicLen_)
Command & | setFilter (const std::string &filter_)
Command & | setFilter (const char *filter_, size_t filterLen_)
Command & | setOrderBy (const std::string &orderBy_)
Command & | setOrderBy (const char *orderBy_, size_t orderByLen_)
Command & | setSubId (const std::string &subId_)
Command & | setSubId (const char *subId_, size_t subIdLen_)
Command & | setQueryId (const std::string &queryId_)
Command & | setQueryId (const char *queryId_, size_t queryIdLen_)
Command & | setBookmark (const std::string &bookmark_)
| Set the bookmark to be used this command. More...
Command & | setBookmark (const char *bookmark_, size_t bookmarkLen_)
| Set the bookmark to be used this command. More...
Command & | setCorrelationId (const std::string &correlationId_)
| Set the correlation ID for this command. More...
Command & | setCorrelationId (const char *correlationId_, size_t correlationIdLen_)
| Set the correlation ID for this command. More...
Command & | setOptions (const std::string &options_)
| Sets the options string for this command: see Message.Options for a helper class for constructing the string. More...
Command & | setOptions (const char *options_, size_t optionsLen_)
| Sets the options string for this command: see Message.Options for a helper class for constructing the string. More...
Command & | setSequence (const std::string &seq_)
Command & | setSequence (const char *seq_, size_t seqLen_)
Command & | setSequence (const amps_uint64_t seq_)
Command & | setData (const std::string &data_)
| Sets the data for this command from an existing string. More...
Command & | setData (const char *data_, size_t dataLen_)
| Sets the data for this command. More...
Command & | setTimeout (unsigned timeout_)
| Sets the client-side timeout for this command. More...
Command & | setTopN (unsigned topN_)
Command & | setBatchSize (unsigned batchSize_)
| Sets the batch size for this command, which controls how many records are sent together in the results of a SOW query. More...
Command & | setExpiration (unsigned expiration_)
| Set the expiration time for a publish command. More...
Command & | addAckType (const std::string &ackType_)
Command & | setAckType (const std::string &ackType_)
Command & | setAckType (unsigned ackType_)
std::string | getAckType () const
unsigned | getAckTypeEnum () const

## Detailed Description

Command is an encapsulation of a single AMPS command sent by the client.

Using Command you can build valid commands to be executed to process messages synchronously or asynchronously via the Client execute() and executeAsync() methods. Command is designed to be used as a "builder" enabling AMPS commands to be built easily, for example:

    Client client(...);
    // connect and logon
    for(Message m : client.execute(Command("sow").setTopic("topic"))) { ... }

The AMPS client is designed so that, in general, applications use the Command object to build commands sent to AMPS. The client provides instances of the Message object in return.

Command does not attempt to validate the command before it is submitted to the AMPS server. Any header can be set on any Command, and the AMPS client allows any value for any header. See the AMPS Command Reference for details on how the AMPS Server interprets commands and which headers and options are available on a given command type.

## Constructor & Destructor Documentation

## ◆ Command() [1/3]

AMPS::Command::Command | ( | const std::string & | command_ | ) |
| inline

Creates an object to represent the given AMPS command, such as "sow" or "subscribe".

Parameters

  command_ | The AMPS command to be created.

## ◆ Command() [2/3]

AMPS::Command::Command | ( | const char * | command_,
|  | size_t | commandLen_
| ) |  |
| inline

Creates an object to represent the given AMPS command, such as "sow" or "subscribe".

Parameters

  command_ | The AMPS command to be created.
  commandLen_ | The length of the new AMPS command to be created.

## ◆ Command() [3/3]

AMPS::Command::Command | ( | Message::Command::Type | command_ | ) |
| inline

Creates an object to represent the given AMPS command, such as "sow" or "subscribe".

Parameters

  command_ | The AMPS command to be created.

## Member Function Documentation

## ◆ addAckType()

Command& AMPS::Command::addAckType | ( | const std::string & | ackType_ | ) |
| inline

Parameters

  ackType_ | add an ack type to this command, such as "stats" or "completed". Additional acks are returned in the message stream.

## ◆ getAckType()

std::string AMPS::Command::getAckType | ( |  | ) | const
| inline

Returns
  The ack type set on this command.

## ◆ getAckTypeEnum()

unsigned AMPS::Command::getAckTypeEnum | ( |  | ) | const
| inline

Returns
  The ack type enum set on this command.

## ◆ reset() [1/3]

Command& AMPS::Command::reset | ( | const char * | command_,
|  | size_t | commandLen_
| ) |  |
| inline

Resets the fields of self, and sets the command to command_.

Parameters

  command_ | The new AMPS command to be created.
  commandLen_ | The length of the new AMPS command to be created.

## ◆ reset() [2/3]

Command& AMPS::Command::reset | ( | const std::string & | command_ | ) |
| inline

Resets the fields of self, and sets the command to command_.

Parameters

  command_ | The new AMPS command to be created.

## ◆ reset() [3/3]

Command& AMPS::Command::reset | ( | Message::Command::Type | command_ | ) |
| inline

Resets the fields of self, and sets the command to command_.

Parameters

  command_ | The new AMPS command to be created.

## ◆ setAckType() [1/2]

Command& AMPS::Command::setAckType | ( | const std::string & | ackType_ | ) |
| inline

Parameters

  ackType_ | set the ack type for this command, such as "stats,completed" or "processed,completed". Additional acks are returned in the message stream.

## ◆ setAckType() [2/2]

Command& AMPS::Command::setAckType | ( | unsigned | ackType_ | ) |
| inline

Parameters

  ackType_ | set the ack type for this command, such as `Message::AckType::Stats``|``Message::AckType::Completed` or `Message::AckType::Processed``|``Message::AckType::Completed`. Additional acks are returned in the message stream.

## ◆ setBatchSize()

Command& AMPS::Command::setBatchSize | ( | unsigned | batchSize_ | ) |
| inline

Sets the batch size for this command, which controls how many records are sent together in the results of a SOW query.

See the AMPS User Guide for details.

Parameters

  batchSize_ | the batch size for this command

## ◆ setBookmark() [1/2]

Command& AMPS::Command::setBookmark | ( | const char * | bookmark_,
|  | size_t | bookmarkLen_
| ) |  |
| inline

Set the bookmark to be used this command.

For a subscription, this can be either a specific bookmark, a bookmark list, or one of the Special Bookmark Values. For an acknowledgement of a queue message, this can be a specific bookmark or a bookmark list. See the AMPS Command Reference for details on when a bookmark is applicable.

Parameters

  bookmark_ | the bookmark for this command.
  bookmarkLen_ | the length of the bookmark for this command.

## ◆ setBookmark() [2/2]

Command& AMPS::Command::setBookmark | ( | const std::string & | bookmark_ | ) |
| inline

Set the bookmark to be used this command.

For a subscription, this can be either a specific bookmark, a bookmark list, or one of the Special Bookmark Values. For an acknowledgement of a queue message, this can be a specific bookmark or a bookmark list. See the AMPS Command Reference for details on when a bookmark is applicable.

Parameters

  bookmark_ | the bookmark for this command.

## ◆ setCommandId() [1/2]

Command& AMPS::Command::setCommandId | ( | const char * | cmdId_,
|  | size_t | cmdIdLen_
| ) |  |
| inline

Parameters

  cmdId_ | the command ID for this command. For relevant commands, one is generated for you if you do not supply one.
  cmdIdLen_ | the length of the command ID for this command.

## ◆ setCommandId() [2/2]

Command& AMPS::Command::setCommandId | ( | const std::string & | cmdId_ | ) |
| inline

Parameters

  cmdId_ | the command ID for this command. For relevant commands, one is generated for you if you do not supply one.

## ◆ setCorrelationId() [1/2]

Command& AMPS::Command::setCorrelationId | ( | const char * | correlationId_,
|  | size_t | correlationIdLen_
| ) |  |
| inline

Set the correlation ID for this command.

The correlation ID is an arbitrary string that can be used for whatever purpose the application needs. It is not interpreted or used by AMPS. However, the correlation ID must only contain characters that are valid base64 encoded characters.

Parameters

  correlationId_ | the correlation ID for this command.
  correlationIdLen_ | the length of the correlation ID for this command.

## ◆ setCorrelationId() [2/2]

Command& AMPS::Command::setCorrelationId | ( | const std::string & | correlationId_ | ) |
| inline

Set the correlation ID for this command.

The correlation ID is an arbitrary string that can be used for whatever purpose the application needs. It is not interpreted or used by AMPS. However, the correlation ID must only contain characters that are valid base64 encoded characters.

Parameters

  correlationId_ | the correlation ID for this command.

## ◆ setData() [1/2]

Command& AMPS::Command::setData | ( | const char * | data_,
|  | size_t | dataLen_
| ) |  |
| inline

Sets the data for this command.

Parameters

  data_ | the data for this command.
  dataLen_ | the length, in bytes, of your data (excluding any null-terminator)

## ◆ setData() [2/2]

Command& AMPS::Command::setData | ( | const std::string & | data_ | ) |
| inline

Sets the data for this command from an existing string.

Parameters

  data_ | the data for this command.

## ◆ setExpiration()

Command& AMPS::Command::setExpiration | ( | unsigned | expiration_ | ) |
| inline

Set the expiration time for a publish command.

For publishes to a Topic in the state of the world that has expiration enabled, this specifies how long to retain this publish in the state of the world (if expiration is not enabled for that topic, this value is ignored for that topic). For a message that will be delivered from a queue, this value sets the length of time that the message will be available to be delivered from the queue. Notice that this value does not affect storage in the transaction log.

Parameters

  expiration_ | the expiration time for this publish, in seconds

## ◆ setFilter() [1/2]

Command& AMPS::Command::setFilter | ( | const char * | filter_,
|  | size_t | filterLen_
| ) |  |
| inline

Parameters

  filter_ | the filter for this command.
  filterLen_ | the length of the filter for this command.

## ◆ setFilter() [2/2]

Command& AMPS::Command::setFilter | ( | const std::string & | filter_ | ) |
| inline

Parameters

  filter_ | the filter for this command.

## ◆ setOptions() [1/2]

Command& AMPS::Command::setOptions | ( | const char * | options_,
|  | size_t | optionsLen_
| ) |  |
| inline

Sets the options string for this command: see Message.Options for a helper class for constructing the string.

Parameters

  options_ | the options string for this command.
  optionsLen_ | the length of the options string for this command.

## ◆ setOptions() [2/2]

Command& AMPS::Command::setOptions | ( | const std::string & | options_ | ) |
| inline

Sets the options string for this command: see Message.Options for a helper class for constructing the string.

Parameters

  options_ | the options string for this command.

## ◆ setOrderBy() [1/2]

Command& AMPS::Command::setOrderBy | ( | const char * | orderBy_,
|  | size_t | orderByLen_
| ) |  |
| inline

Parameters

  orderBy_ | the order by clause for this command.
  orderByLen_ | the length of the order by clause for this command.

## ◆ setOrderBy() [2/2]

Command& AMPS::Command::setOrderBy | ( | const std::string & | orderBy_ | ) |
| inline

Parameters

  orderBy_ | the order by clause for this command.

## ◆ setQueryId() [1/2]

Command& AMPS::Command::setQueryId | ( | const char * | queryId_,
|  | size_t | queryIdLen_
| ) |  |
| inline

Parameters

  queryId_ | the query ID for this command. For relevant commands, one is generated for you if you do not supply one.
  queryIdLen_ | the length of the query ID for this command.

## ◆ setQueryId() [2/2]

Command& AMPS::Command::setQueryId | ( | const std::string & | queryId_ | ) |
| inline

Parameters

  queryId_ | the query ID for this command. For relevant commands, one is generated for you if you do not supply one.

## ◆ setSequence() [1/3]

Command& AMPS::Command::setSequence | ( | const amps_uint64_t | seq_ | ) |
| inline

Parameters

  seq_ | the sequence for this command. If the client has a publish store, the sequence from the store will be used regardless of if you set this.

## ◆ setSequence() [2/3]

Command& AMPS::Command::setSequence | ( | const char * | seq_,
|  | size_t | seqLen_
| ) |  |
| inline

Parameters

  seq_ | the sequence for this command. If the client has a publish store, the sequence from the store will be used regardless of if you set this.
  seqLen_ | the length of the sequence for this command.

## ◆ setSequence() [3/3]

Command& AMPS::Command::setSequence | ( | const std::string & | seq_ | ) |
| inline

Parameters

  seq_ | the sequence for this command. If the client has a publish store, the sequence from the store will be used regardless of if you set this.

## ◆ setSowKey() [1/2]

Command& AMPS::Command::setSowKey | ( | const char * | sowKey_,
|  | size_t | sowKeyLen_
| ) |  |
| inline

Sets the SowKey field of the command, typically used for a publish command to a topic in the state of the world when that topic is configured to require the publisher to set the SowKey.

For other commands (for example, "sow" or "sow_delete"), use the setSowKeys function to set the SowKeys header. See the AMPS Command Reference for details.

Parameters

  sowKey_ | the SowKey field of this command.
  sowKeyLen_ | the length of the SowKey field of this command.

## ◆ setSowKey() [2/2]

Command& AMPS::Command::setSowKey | ( | const std::string & | sowKey_ | ) |
| inline

Sets the SowKey field of the command, typically used for a publish command to a topic in the state of the world when that topic is configured to require the publisher to set the SowKey.

For other commands (for example, "sow" or "sow_delete"), use the setSowKeys function to set the SowKeys header. See the AMPS Command Reference for details.

Parameters

  sowKey_ | the SowKey field of this command.

## ◆ setSowKeys() [1/2]

Command& AMPS::Command::setSowKeys | ( | const char * | sowKeys_,
|  | size_t | sowKeysLen_
| ) |  |
| inline

Sets the SowKeys for the command.

When applicable, setting the SowKeys for a command limits the results of the command to only messages with one of the specified SowKeys. The SowKeys for a command are a comma-separated list of the keys that AMPS assigns to SOW messages.

The SowKey for a message is available through the Message.getSowKey function on a message.

See the AMPS User Guide and AMPS Command Reference for details on when AMPS will interpret this header on a command.

Parameters

  sowKeys_ | the SOWKeys field of this command.
  sowKeysLen_ | the length of the SOWKeys field of this command.

## ◆ setSowKeys() [2/2]

Command& AMPS::Command::setSowKeys | ( | const std::string & | sowKeys_ | ) |
| inline

Sets the SowKeys for the command.

When applicable, setting the SowKeys for a command limits the results of the command to only messages with one of the specified SowKeys. The SowKeys for a command are a comma-separated list of the keys that AMPS assigns to SOW messages.

The SowKey for a message is available through the Message.getSowKey function on a message.

See the AMPS User Guide and AMPS Command Reference for details on when AMPS will interpret this header on a command.

Parameters

  sowKeys_ | the SOWKeys field of this command.

## ◆ setSubId() [1/2]

Command& AMPS::Command::setSubId | ( | const char * | subId_,
|  | size_t | subIdLen_
| ) |  |
| inline

Parameters

  subId_ | the subscription ID for this command. For relevant commands, one is generated for you if you do not supply one.
  subIdLen_ | the length of the subscription ID for this command.

## ◆ setSubId() [2/2]

Command& AMPS::Command::setSubId | ( | const std::string & | subId_ | ) |
| inline

Parameters

  subId_ | the subscription ID for this command. For relevant commands, one is generated for you if you do not supply one.

## ◆ setTimeout()

Command& AMPS::Command::setTimeout | ( | unsigned | timeout_ | ) |
| inline

Sets the client-side timeout for this command.

If the client does not process an acknowledgement for the command within the specified timeout, the client throws an exception. Notice that the timeout is monitored on the AMPS client, not on the server, and the acknowledgement is processed on the client receive thread.

A timeout value of 0 indicates that the client should wait for a "processed" ack to be returned from the server without timing out.

Parameters

  timeout_ | the timeout for this command in milliseconds. By default, the timeout is 0, indicating that the command will block until a "processed" ack is returned and consumed by the client receive thread.

## ◆ setTopic() [1/2]

Command& AMPS::Command::setTopic | ( | const char * | topic_,
|  | size_t | topicLen_
| ) |  |
| inline

Parameters

  topic_ | the topic for this command.
  topicLen_ | the length of the topic for this command.

## ◆ setTopic() [2/2]

Command& AMPS::Command::setTopic | ( | const std::string & | topic_ | ) |
| inline

Parameters

  topic_ | the topic for this command.

## ◆ setTopN()

Command& AMPS::Command::setTopN | ( | unsigned | topN_ | ) |
| inline

Parameters

  topN_ | the "top N" field for this command. This value limits the number of records returned from a SOW query to the first N records.

The documentation for this class was generated from the following file:

- include/amps/ampsplusplus.hpp