AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.3.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 (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 (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...
 
CommandsetSowKeys (const std::string &sowKeys_)
 Sets the SowKeys for the command. More...
 
CommandsetCommandId (const std::string &v_)
 
CommandsetTopic (const std::string &v_)
 
CommandsetFilter (const std::string &v_)
 
CommandsetOrderBy (const std::string &v_)
 
CommandsetSubId (const std::string &v_)
 
CommandsetQueryId (const std::string &v_)
 
CommandsetBookmark (const std::string &v_)
 Set the bookmark to be used this command. More...
 
CommandsetCorrelationId (const std::string &v_)
 Set the correlation ID for this command. More...
 
CommandsetOptions (const std::string &v_)
 Sets the options string for this command: see Message.Options for a helper class for constructing the string. More...
 
CommandsetSequence (const std::string &v_)
 
CommandsetSequence (const amps_uint64_t v_)
 
CommandsetData (const std::string &v_)
 Sets the data for this command from an existing string. More...
 
CommandsetData (const char *v_, size_t length_)
 Sets the data for this command. More...
 
CommandsetTimeout (unsigned v_)
 Sets the client-side timeout for this command. More...
 
CommandsetTopN (unsigned v_)
 
CommandsetBatchSize (unsigned v_)
 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 v_)
 Set the expiration time for a publish command. More...
 
CommandaddAckType (const std::string &v_)
 
CommandsetAckType (const std::string &v_)
 
CommandsetAckType (unsigned v_)
 
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 ( 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 &  v_)
inline
Parameters
v_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 ( 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 &  v_)
inline
Parameters
v_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  v_)
inline
Parameters
v_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  v_)
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
v_the batch size for this command
Command& AMPS::Command::setBookmark ( const std::string &  v_)
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
v_the bookmark for this command.
Command& AMPS::Command::setCommandId ( const std::string &  v_)
inline
Parameters
v_the command ID for this command. For relevant commands, one is generated for you if you do not supply one.
Command& AMPS::Command::setCorrelationId ( const std::string &  v_)
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
v_the correlation ID for this command.
Command& AMPS::Command::setData ( const std::string &  v_)
inline

Sets the data for this command from an existing string.

Parameters
v_the data for this command.
Command& AMPS::Command::setData ( const char *  v_,
size_t  length_ 
)
inline

Sets the data for this command.

Parameters
v_the data for this command.
length_the length, in bytes, of your data (excluding any null-terminator)
Command& AMPS::Command::setExpiration ( unsigned  v_)
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
v_the expiration time for this publish, in seconds
Command& AMPS::Command::setFilter ( const std::string &  v_)
inline
Parameters
v_the filter for this command.
Command& AMPS::Command::setOptions ( const std::string &  v_)
inline

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

Parameters
v_the options string for this command.
Command& AMPS::Command::setOrderBy ( const std::string &  v_)
inline
Parameters
v_the order by clause for this command.
Command& AMPS::Command::setQueryId ( const std::string &  v_)
inline
Parameters
v_the query ID for this command. For relevant commands, one is generated for you if you do not supply one.
Command& AMPS::Command::setSequence ( const std::string &  v_)
inline
Parameters
v_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 amps_uint64_t  v_)
inline
Parameters
v_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::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 SowKyes. 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::setSubId ( const std::string &  v_)
inline
Parameters
v_the subscription ID for this command. For relevant commands, one is generated for you if you do not supply one.
Command& AMPS::Command::setTimeout ( unsigned  v_)
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
v_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 &  v_)
inline
Parameters
v_the topic for this command.
Command& AMPS::Command::setTopN ( unsigned  v_)
inline
Parameters
v_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: