AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.3
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...
 
Commandreset (const std::string &command_)
 Resets the fields of self, and sets the command to command_. More...
 
Commandreset (const char *command_, size_t commandLen_)
 Resets the fields of self, and sets the command to command_. More...
 
Commandreset (Message::Command::Type command_)
 Resets the fields of self, and sets the command to command_. More...
 
CommandsetSowKey (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...
 
CommandsetSowKey (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...
 
CommandsetSowKeys (const std::string &sowKeys_)
 Sets the SowKeys for the command. More...
 
CommandsetSowKeys (const char *sowKeys_, size_t sowKeysLen_)
 Sets the SowKeys for the command. More...
 
CommandsetCommandId (const std::string &cmdId_)
 
CommandsetCommandId (const char *cmdId_, size_t cmdIdLen_)
 
CommandsetTopic (const std::string &topic_)
 
CommandsetTopic (const char *topic_, size_t topicLen_)
 
CommandsetFilter (const std::string &filter_)
 
CommandsetFilter (const char *filter_, size_t filterLen_)
 
CommandsetOrderBy (const std::string &orderBy_)
 
CommandsetOrderBy (const char *orderBy_, size_t orderByLen_)
 
CommandsetSubId (const std::string &subId_)
 
CommandsetSubId (const char *subId_, size_t subIdLen_)
 
CommandsetQueryId (const std::string &queryId_)
 
CommandsetQueryId (const char *queryId_, size_t queryIdLen_)
 
CommandsetBookmark (const std::string &bookmark_)
 Set the bookmark to be used this command. More...
 
CommandsetBookmark (const char *bookmark_, size_t bookmarkLen_)
 Set the bookmark to be used this command. More...
 
CommandsetCorrelationId (const std::string &correlationId_)
 Set the correlation ID for this command. More...
 
CommandsetCorrelationId (const char *correlationId_, size_t correlationIdLen_)
 Set the correlation ID for this command. More...
 
CommandsetOptions (const std::string &options_)
 Sets the options string for this command: see Message.Options for a helper class for constructing the string. More...
 
CommandsetOptions (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...
 
CommandsetSequence (const std::string &seq_)
 
CommandsetSequence (const char *seq_, size_t seqLen_)
 
CommandsetSequence (const amps_uint64_t seq_)
 
CommandsetData (const std::string &data_)
 Sets the data for this command from an existing string. More...
 
CommandsetData (const char *data_, size_t dataLen_)
 Sets the data for this command. More...
 
CommandsetTimeout (unsigned timeout_)
 Sets the client-side timeout for this command. More...
 
CommandsetTopN (unsigned topN_)
 
CommandsetBatchSize (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...
 
CommandsetExpiration (unsigned expiration_)
 Set the expiration time for a publish command. More...
 
CommandaddAckType (const std::string &ackType_)
 
CommandsetAckType (const std::string &ackType_)
 
CommandsetAckType (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

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.
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.
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

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.
std::string AMPS::Command::getAckType ( ) const
inline
Returns
The ack type set on this command.
unsigned AMPS::Command::getAckTypeEnum ( ) const
inline
Returns
The ack type enum set on this command.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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)
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
Command& AMPS::Command::setFilter ( const std::string &  filter_)
inline
Parameters
filter_the filter for this command.
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.
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.
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.
Command& AMPS::Command::setOrderBy ( const std::string &  orderBy_)
inline
Parameters
orderBy_the order by clause for this command.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Command& AMPS::Command::setTopic ( const std::string &  topic_)
inline
Parameters
topic_the topic for this command.
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.
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: