com.crankuptheamps.client

Class Command

java.lang.Object

com.crankuptheamps.client.Command

public class Command
extends java.lang.Object

Command is an encapsulation of a single AMPS command sent by the client. Using Command you can build commands to be executed by the client, with message processing happening either synchronously via the Client execute() method or asynchronously via the executeAsync() methods. Command is designed to be used as a "builder" enabling AMPS commands to be built easily, for example:

 
 Client client = new Client(...);
 for(Message m : client.execute(new Command("sow").setTopic("topic"))) { ... }
 
 

Notice that the Message class can represent both command messages to AMPS and response messages from AMPS. In contrast, Command represents only commands to AMPS, so the class includes only properties that are valid on outgoing commands.

Since:

4.0.0.0

Constructor Summary

Constructors

Constructor and Description
Command() Create a new Command with no command type or arguments set.
Command(int command)
Command(java.lang.String command) Create a new `Command` object with the specified command code.

Method Summary

Modifier and Type	Method and Description
Command	addAckType(int ackType) Adds an additional ackType to the ackTypes already set for this Command.
int	getAckType() Get the ackType for this command.
int	getBatchSize() Get the batchSize set on this command.
java.lang.String	getBookmark() Get the bookmark for this command.
long	getClientSequenceNumber() Get the client sequence number set on this command.
int	getCommand() Retrieves the command type associated with this `Command` object.
CommandId	getCommandId() Gets the automatically generated command ID associated with this command.
java.lang.String	getCorrelationId() Gets the correlation Id set with this command.
java.lang.String	getData() Get the data set on this command.
int	getExpiration() Get the expiration set on this command.
java.lang.String	getFilter() Get the filter for this command.
java.lang.String	getOptions() Get the options for this command.
java.lang.String	getOrderBy() Get the orderBy clause for this command.
CommandId	getQueryId() Retrieve the query identifier associated with the 'Command' object.
java.lang.String	getSowKey() Retrieves the State of the World (SOW) key associated with this instance.
java.lang.String	getSOWKey() Deprecated. Use getSowKey() instead.
java.lang.String	getSowKeys() Returns the SOW keys on this command.
java.lang.String	getSOWKeys() Deprecated. Use getSowKeys() instead
CommandId	getSubId() Get the subId set on this command.
long	getTimeout() Gets the timeout set on this command.
java.lang.String	getTopic() Get the topic set on this command.
int	getTopN() Get the topN value for this command.
boolean	hasExpiration() Returns true if this command has an expiration set.
boolean	isSow() Checks if the current command represents a State of the World (SOW) operation.
boolean	isSubscribe() Checks if the current command represents a subscription.
boolean	needsSequenceNumber() Checks whether a sequence number is needed for this message based on the message command.
protected CommandId	prepare(Client client_) Binds self to a given client, preparing a message from that client to be sent.
Command	reset(int command) Resets this 'Command' object with a new Command type and re-initializes all other fields altering its purpose.
Command	reset(java.lang.String command) Resets the current 'Command' object with a new command type specified as a string value and re-initializes all associated fields.
Command	setAckType(int ackType) Set the ackType for this command.
Command	setBatchSize(int batchSize) Set the batchSize for this command.
Command	setBookmark(java.lang.String bookmark) Set the bookmark for this command.
Command	setClientSequenceNumber(long seqNumber) Sets the client sequence number for this command.
Command	setCommand(int command) Set the command type for this 'Command' object.
Command	setCommandId(CommandId commandId) Sets a unique command identifier 'CommandId' for this `Command` object.
Command	setCorrelationId(java.lang.String correlationId_) Sets the correlation Id for this command.
Command	setData(byte[] data, int offset, int length) Set the raw data for this command.
Command	setData(CompositeMessageBuilder builder) Set the data for this command.
Command	setData(java.lang.String data) Set the data for this command.
Command	setExpiration(int expiration) Set the expiration for this command.
Command	setFilter(java.lang.String filter) Set the filter for this command.
Command	setOptions(java.lang.String options) Set the options for this command.
Command	setOrderBy(java.lang.String orderBy) Set the orderBy clause for this command.
Command	setQueryId(CommandId queryId) Set a custom QueryId for this Command.
Command	setSowKey(java.lang.String sowKey) The SowKey for a command is only used to publish to a SOW topic and if the user wants to restrict the command to a set of messages identified by key, SowKeys is used instead.
Command	setSOWKey(java.lang.String sowKey) Deprecated. Use setSowKey() instead.
Command	setSowKeys(java.lang.String sowKeys) Sets the SowKeys for this command.
Command	setSOWKeys(java.lang.String sowKeys) Deprecated. Use setSowKeys() instead.
Command	setSubId(CommandId subId) Set the subId for this command.
Command	setSubId(java.lang.String subId) Sets the subId for this command using a string representation.
Command	setTimeout(long timeout) Set the timeout for this command (in milliseconds).
Command	setTopic(byte[] topic, int offset, int length) Set the topic for this command from raw bytes, offset, and length.
Command	setTopic(java.lang.String topic) Set the topic for this command.
Command	setTopN(int topN) Sets the top_n header for this command.
void	unsetExpiration() Clears any expiration value set on self.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Command

public Command()

Create a new Command with no command type or arguments set. Provides a starting point for creating 'Command' objects.

Since:

4.0.0.0

Command

public Command(java.lang.String command)

Create a new `Command` object with the specified command code. This constructor creates a new `Command` object, initializing it with an integer value representing a specific command code. The initialization process is handled internally by the constructor.

Parameters:

command - A Message.Command value indicating the AMPS command.

Since:

4.0.0.0

Command

public Command(int command)

Method Detail

getSOWKey

@Deprecated
public java.lang.String getSOWKey()

Deprecated. Use getSowKey() instead.

Returns the SOW key on this command.

Returns:

the sow key

Since:

4.0.0.0

getSowKey

public java.lang.String getSowKey()

Retrieves the State of the World (SOW) key associated with this instance.

Returns:

A string representing the SOW key.

Since:

5.0.0.0

setSOWKey

@Deprecated
public Command setSOWKey(java.lang.String sowKey)

Deprecated. Use setSowKey() instead.

The SowKey for a command is used to publish to a SOW topic with explicit keys set by the user rather than AMPS. The SOW key for a message is available through the Message.getSowKey() method on a message.

Parameters:

sowKey - the sow key to set

Returns:

Returns this instance so that various operations can be chained together.

Since:

4.3.0.0

setSowKey

public Command setSowKey(java.lang.String sowKey)

The SowKey for a command is only used to publish to a SOW topic and if the user wants to restrict the command to a set of messages identified by key, SowKeys is used instead. The SOW key for a message is available through the Message.getSowKey() method on a message.

Parameters:

sowKey - the sow key to set

Returns:

Returns this instance so that various operations can be chained together.

Since:

5.0.0.0

See Also:

setSowKeys(String), getSowKeys()

getSowKeys

public java.lang.String getSowKeys()

Returns the SOW keys on this command.

Returns:

the sow key

Since:

5.0.0.0

getSOWKeys

@Deprecated
public java.lang.String getSOWKeys()

Deprecated. Use getSowKeys() instead

Returns the SOW keys on this command.

Returns:

the sow key

Since:

4.3.0.0

setSowKeys

public Command setSowKeys(java.lang.String sowKeys)

Sets the SowKeys for this command. SowKeys are a comma-separated list of unique keys assigned by AMPS to SOW messages to be deleted. AMPS uses these ids to locate and remove the specified records. The SOW key for a message is available through the Message.getSowKey() method on a message. This method specifies that the command is only intended to apply to the keys provided.You cannot perform bulk updates by including multiple SOW keys in a single publish operation. It also works to limit queiries.

Parameters:

sowKeys - the sow keys to set

Returns:

Returns this instance so that various operations can be chained together.

Since:

5.0.0.0

setSOWKeys

@Deprecated
public Command setSOWKeys(java.lang.String sowKeys)

Deprecated. Use setSowKeys() instead.

The SowKeys for a command are a comma-separated list of the keys that AMPS assigns to SOW messages. The SOW key for a message is available through the Message.getSowKey() method on a message.

Parameters:

sowKeys - the sow keys to set

Returns:

Returns this instance so that various operations can be chained together.

Since:

4.0.0.0

isSubscribe

public final boolean isSubscribe()

Checks if the current command represents a subscription.

Returns:

true if this command is a subscription command, otherwise false.

Since:

4.0.0.0

isSow

public final boolean isSow()

Checks if the current command represents a State of the World (SOW) operation.

Returns:

true if this command queries a SOW, otherwise false.

Since:

4.0.0.0

needsSequenceNumber

public boolean needsSequenceNumber()

Checks whether a sequence number is needed for this message based on the message command.

Returns:

true if this command can be associated with a client sequence number, false otherwise.

Since:

4.0.0.0

reset

public Command reset(int command)

Resets this 'Command' object with a new Command type and re-initializes all other fields altering its purpose. This method allows the reusability of the current `Command` object by changing its state to represent a different command type.

Parameters:

command - A Message.Command value indicating the AMPS command.

Returns:

This `Command` object with its state reset to the new command type, supporting method chaining.

Since:

4.0.0.0

reset

public Command reset(java.lang.String command)

Resets the current 'Command' object with a new command type specified as a string value and re-initializes all associated fields. Translates the string into a command type using `translateCommand` and alters the object's purpose.

Parameters:

command - A string representing the new command type.

Returns:

This current 'Command' object with its state reset to the new type, allowing method chaining.

Since:

4.0.0.0

getCommandId

public CommandId getCommandId()

Gets the automatically generated command ID associated with this command.

Returns:

The commandId, which is automatically generated for some command types.

Since:

4.0.0.0

setCommandId

public Command setCommandId(CommandId commandId)

Sets a unique command identifier 'CommandId' for this `Command` object.

Parameters:

commandId - A unique command identifier to be associated with this `Command`.

Returns:

Returns This `Command` object with the specified identifier.

Since:

4.0.0.0

getQueryId

public CommandId getQueryId()

Retrieve the query identifier associated with the 'Command' object. This method is used to access the identifier set by the 'setQueryId' method when needed. It allows you to read or obtain the QueryId for tracking, monitoring, or correlating messages within the messaging system.

Returns:

The query identifier ('CommandId') previously set using the 'setQueryId' method, or 'null' if not set.

Since:

4.0.0.0

setQueryId

public Command setQueryId(CommandId queryId)

Set a custom QueryId for this Command. The QueryId is a unique identifier that you can assign to this command. You have the option to set this independently of the Command so customizing the QueryId provides flexibility as you can assign QueryIds based on application-specific logic. When the QueryId is independent of the Command in AMPS, it means you are not bound by the CommandId for assigning QueryIds. Instead, you have the freedom to create custom identifiers for queries and messages, which can be valuable when you have scenarios when you need to correlate responses from different types of queries based on shared attributes other than the CommandId.

Parameters:

queryId - A unique query identifier to be associated with this `Command`.

Returns:

This `Command` object with the specified query identifier.

Since:

4.0.0.0

getCommand

public int getCommand()

Retrieves the command type associated with this `Command` object.

Returns:

The command type integer associated with this `Command`.

Since:

4.0.0.0

setCommand

public Command setCommand(int command)

Set the command type for this 'Command' object.

Parameters:

command - An integer representing the command type to be associated with this `Command`.

Returns:

This `Command` object with the specified command type.

Since:

4.0.0.0

getTopic

public java.lang.String getTopic()

Get the topic set on this command.

Returns:

the topic

Since:

4.0.0.0

setTopic

public Command setTopic(java.lang.String topic)

Set the topic for this command.

Parameters:

topic - the topic to set

Returns:

Returns this instance of Command.

Since:

4.0.0.0

setTopic

public Command setTopic(byte[] topic,
                        int offset,
                        int length)

Set the topic for this command from raw bytes, offset, and length.

Parameters:

topic - The raw bytes to be used for the topic.

offset - The offset into topic where the topic data begins

length - The length of the topic.

Returns:

Returns this instance of Command.

Since:

4.0.0.0

getFilter

public java.lang.String getFilter()

Get the filter for this command.

Returns:

The filter.

Since:

4.0.0.0

setFilter

public Command setFilter(java.lang.String filter)

Set the filter for this command.

Parameters:

filter - The filter to set.

Returns:

Returns this instance of the Command.

Since:

4.0.0.0

getOrderBy

public java.lang.String getOrderBy()

Get the orderBy clause for this command.

Returns:

The orderBy.

Since:

4.0.0.0

setOrderBy

public Command setOrderBy(java.lang.String orderBy)

Set the orderBy clause for this command.

Parameters:

orderBy - The orderBy to set.

Returns:

Returns this instance of Command.

Since:

4.0.0.0

getSubId

public CommandId getSubId()

Get the subId set on this command.

Returns:

The subId.

Since:

4.0.0.0

setSubId

public Command setSubId(CommandId subId)

Set the subId for this command.

Parameters:

subId - The subId to set.

Returns:

Returns this instance so that various operations can be chained together.

Since:

4.0.0.0

setSubId

public Command setSubId(java.lang.String subId)

Sets the subId for this command using a string representation.

Parameters:

subId - The subId to set.

Returns:

Returns this instance of Command.

Since:

4.0.0.0

getBookmark

public java.lang.String getBookmark()

Get the bookmark for this command.

Returns:

The bookmark.

Since:

4.0.0.0

setBookmark

public Command setBookmark(java.lang.String bookmark)

Set the bookmark for this command.

Parameters:

bookmark - the bookmark to set

Returns:

The current instance of Command.

Since:

4.0.0.0

getOptions

public java.lang.String getOptions()

Get the options for this command.

Returns:

The options.

Since:

4.0.0.0

setOptions

public Command setOptions(java.lang.String options)

Set the options for this command. Options are a comma-delimited list.

Parameters:

options - the options to set

Returns:

Returns this instance so that various operations can be chained together.

Since:

4.0.0.0

getAckType

public int getAckType()

Get the ackType for this command.

Returns:

The ackType.

Since:

4.0.0.0

setAckType

public Command setAckType(int ackType)

Set the ackType for this command. Different ackTypes are supported for each command. See the Command Reference for details.

Parameters:

ackType - The ackType to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

addAckType

public Command addAckType(int ackType)

Adds an additional ackType to the ackTypes already set for this Command.

Parameters:

ackType - the ackType to add

Returns:

Returns this instance so that various operations can be chained together.

Since:

4.0.0.0

getData

public java.lang.String getData()

Get the data set on this command.

Returns:

The data.

Since:

4.0.0.0

setData

public Command setData(java.lang.String data)

Set the data for this command.

Parameters:

data - The data to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

setData

public Command setData(byte[] data,
                       int offset,
                       int length)

Set the raw data for this command.

Parameters:

data - The raw bytes to be used for the data.

offset - The offset into data where the data begins.

length - The length of the data.

Returns:

The current instance of Command.

Since:

4.0.0.0

setData

public Command setData(CompositeMessageBuilder builder)

Set the data for this command.

Parameters:

builder - a CompositeMessageBuilder to set self's data from.

Returns:

The current instance of Command.

getTimeout

public long getTimeout()

Gets the timeout set on this command.

Returns:

The timeout value.

Since:

4.0.0.0

setTimeout

public Command setTimeout(long timeout)

Set the timeout for this command (in milliseconds). If the client does not receive and consume a processed ack within the specified timeout, this method throws an exception. Notice that the timeout is monitored in the AMPS client, not on the server, and the client receive thread receives and consumes the ack from the server.

Parameters:

timeout - The timeout to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

getTopN

public int getTopN()

Get the topN value for this command.

Returns:

The topN.

Since:

4.0.0.0

setTopN

public Command setTopN(int topN)

Sets the top_n header for this command. This parameter sets a maximum number of records returned by a SOW query. This should usually be set as part of the command's options string, rather than using this method.

Parameters:

topN - The topN to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

getBatchSize

public int getBatchSize()

Get the batchSize set on this command.

Returns:

The batchSize.

Since:

4.0.0.0

setBatchSize

public Command setBatchSize(int batchSize)

Set the batchSize for this command. This sets the number of records returned in a batch during a SOW query.

Parameters:

batchSize - The batchSize to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

getExpiration

public int getExpiration()

Get the expiration set on this command. This method returns 0 if no expiration is set. Use hasExpiration() to check if an expiration is set.

Returns:

The expiration

Since:

4.0.0.0

hasExpiration

public boolean hasExpiration()

Returns true if this command has an expiration set.

Returns:

True if an expiration is set.

Since:

4.0.0.0

setExpiration

public Command setExpiration(int expiration)

Set the expiration for this command. For a publish command to a SOW topic or a queue, the expiration sets the amount of time to retain the message in the SOW or the queue.

Parameters:

expiration - The expiration to set.

Returns:

The current instance of Command.

Since:

4.0.0.0

unsetExpiration

public void unsetExpiration()

Clears any expiration value set on self.

Since:

4.0.0.0

prepare

protected CommandId prepare(Client client_)
                     throws AMPSException

Binds self to a given client, preparing a message from that client to be sent.

Parameters:

client_ - The client to bind against.

Returns:

The CommandId for this command, if one is set, or null.

Throws:

AMPSException - Thrown when preparing the command fails.

Since:

4.0.0.0

setClientSequenceNumber

public Command setClientSequenceNumber(long seqNumber)

Sets the client sequence number for this command.

Parameters:

seqNumber - Sequence number for this command.

Returns:

The current instance of Command.

Since:

4.0.0.0

getClientSequenceNumber

public long getClientSequenceNumber()

Get the client sequence number set on this command.

Returns:

The client sequence number generated for this command, or 0 if none was generated.

Since:

4.0.0.0

setCorrelationId

public Command setCorrelationId(java.lang.String correlationId_)

Sets 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 CorrelationId is a user provided string included in the log message for a logon. AMPS does not interpret or use this string for any other purpose.

Returns:

The current instance of Command.

Since:

4.0.0.0

getCorrelationId

public java.lang.String getCorrelationId()

Gets the correlation Id set with this command.

Returns:

The correlation id.

Since:

4.0.0.0