com.crankuptheamps.client
Class Client

java.lang.Object
  extended by com.crankuptheamps.client.Client
All Implemented Interfaces:
Closeable
Direct Known Subclasses:
HAClient

public class Client
extends Object
implements Closeable

The base AMPS client object used in AMPS applications. Each client object manages a single connection to AMPS. Each AMPS connection has a name, a specific transport (such as tcp), a protocol (used for framing messages to AMPS), and a message type (such as FIX or JSON).

The client object creates and manages background threads. The object provides both a synchronous interface for processing messages on the calling thread and an asynchronous interface suitable for populating a queue to be processed by worker threads.

The Client provides named convenience methods for many AMPS commands. These methods provide control over commonly used parameters and support most programs. For full control over AMPS, you build a Command object and use execute(com.crankuptheamps.client.Command) or executeAsync(com.crankuptheamps.client.Command, com.crankuptheamps.client.MessageHandler) to run the command.

AMPS uses the client name to detect duplicate messages, so the name of each instance of the client application should be unique.

An example of a simple Java program publishing the JSON message { "message" : "Hello, World!"} is listed below.


    public static void main(String[] args) {
    Client client = new Client("ConsolePublisher");

   try
   {
     client.connect("tcp://127.0.0.1:9007/amps");
     System.out.println("connected..");
     client.logon();
    
     client.publish("messages", "{\"message\" : \"Hello, World!\"}");

     System.exit(0);
    }
   catch (AMPSException e)
   {
     System.err.println(e.getLocalizedMessage());
     e.printStackTrace(System.err);
   }

  }
 


Nested Class Summary
static class Client.Bookmarks
          Functions that take a bookmark (String) such as bookmarkSubscribe(com.crankuptheamps.client.MessageHandler, java.lang.String, java.lang.String, com.crankuptheamps.client.CommandId, java.lang.String, java.lang.String, long) can be passed a literal bookmark ID, or one of these special values.
static class Client.Version
           
 
Field Summary
protected  ExceptionListener exceptionListener
           
static int MIN_MULTI_BOOKMARK_VERSION
           
static int MIN_PERSISTED_BOOKMARK_VERSION
           
 
Constructor Summary
Client(String name)
          Creates a client.
Client(String name, int version)
          Creates a client.
Client(String name, Transport transport)
          Creates a client with a transport.
Client(String name, Transport transport, int version)
          Creates a client with a transport
 
Method Summary
 void addConnectionStateListener(ConnectionStateListener listener_)
          Adds a ConnectionStateListener instance that will be invoked when this client connects or disconnects.
 Message allocateMessage()
          Creates a new Message appropriate for this client.
 CommandId bookmarkDeltaSubscribe(MessageHandler messageHandler, String topic, String filter, CommandId subId, String bookmark, String options, long timeout)
          Places a bookmark delta subscription with AMPS.
 CommandId bookmarkSubscribe(MessageHandler messageHandler, String topic, String filter, CommandId subId, String bookmark, String options, long timeout)
          Places a bookmark subscription with AMPS.
protected  void broadcastConnectionStateChanged(int newState_)
           
 void close()
          Disconnect from the AMPS server.
 void connect(String uri)
          Connects to the AMPS instance through the provided URI.
 void deltaPublish(byte[] topic, int topicOffset, int topicLength, byte[] data, int dataOffset, int dataLength)
          Delta publish a message to an AMPS topic.
 void deltaPublish(byte[] topic, int topicOffset, int topicLength, byte[] data, int dataOffset, int dataLength, int expiration)
          Delta publish a message to an AMPS topic.
 void deltaPublish(String topic, String data)
          Delta publish a message to an AMPS topic.
 void deltaPublish(String topic, String data, int expiration)
          Delta publish a message to an AMPS topic.
 CommandId deltaSubscribe(MessageHandler messageHandler, String topic, long timeout)
          Places a delta subscription with AMPS.
 CommandId deltaSubscribe(MessageHandler messageHandler, String topic, String filter, long timeout)
          Places a delta subscription with AMPS.
 CommandId deltaSubscribe(MessageHandler messageHandler, String topic, String filter, String options, long timeout)
          Places a delta subscription with AMPS.
 CommandId deltaSubscribe(MessageHandler messageHandler, String topic, String filter, String options, long timeout, String subId)
          Places a delta subscription with AMPS.
 void disconnect()
          Disconnect from the AMPS server.
 MessageStream execute(Command command)
          Execute the provided command and return messages received in response in a MessageStream.
 CommandId executeAsync(Command command, MessageHandler handler)
          Execute the provided command on a background thread and provide messages received in response to the handler provided.
 long flush()
          Clear the queued messages which may be waiting in the transport
 long flush(long timeout)
          Clear the queued messages which may be waiting in the transport
 BookmarkStore getBookmarkStore()
          Returns the underlying bookmark store for this client.
 ConnectionInfo getConnectionInfo()
          Assembles a new ConnectionInfo with the state of this client and associated classes.
 ClientDisconnectHandler getDisconnectHandler()
          Returns the current ClientDisconnectHandler set on self.
 String getName()
          Return the name of the Client.
 Store getPublishStore()
          Returns the underlying publish store for this client.
 int getServerVersion()
          Return the server version retrieved during logon.
 SubscriptionManager getSubscriptionManager()
          Returns the SubscriptionManager instance used for recording active subscriptions.
 Transport getTransport()
          Return the underlying transport.
 URI getURI()
          Return the URI the Client is connected to.
 String getVersion()
          Return the build number for the client that is stored in the Manifes.mf of the jar file.
static int getVersionAsInt(String version)
          Return the numeric value for the given version string with the pattern: Major.Minor.Maintenance.Hotfix The version uses 2 digits each for major minor maintenance and hotfix i.e., 3.8.1.5 will return 3080105 Version strings passed in can be shortened to not include all levels so 3.8 will return 3080000.
 CommandId logon()
          Logs into AMPS with the parameters provided in the connect method.
 CommandId logon(long timeout)
          Logs into AMPS with the parameters provided in the connect method.
 CommandId logon(long timeout, Authenticator authenticator)
          Logs into AMPS with the parameters provided in the connect method.
 long publish(byte[] topic, int topicOffset, int topicLength, byte[] data, int dataOffset, int dataLength)
          Publish a message to an AMPS topic.
 long publish(byte[] topic, int topicOffset, int topicLength, byte[] data, int dataOffset, int dataLength, int expiration)
          Publish a message to an AMPS topic.
 long publish(String topic, String data)
          Publish a message to an AMPS topic.
 long publish(String topic, String data, int expiration)
          Publish a message to an AMPS topic.
 void publishFlush()
          Clear the queued messages which may be waiting in the transport, publish store or in the AMPS publish queue.
 void publishFlush(long timeout)
          Return when all published messages have been confirmed to have made it through the publish queue inside the AMPS instnace.
 void removeConnectionStateListener(ConnectionStateListener listener_)
          Removes a ConnectionStateListener from being invoked when this client connects or disconnects.
 void send(Message message)
          Send a Message to AMPS via the Transport used in the Client.
 CommandId send(MessageHandler messageHandler, Message message, long timeout)
          Send a Message to AMPS and register the messageHandler for any messages resulting from the command execution.
 void setBookmarkStore(BookmarkStore val)
          Sets the underlying bookmark store, which is used to track which messages the client has received and which messages have been processed by the program.
 void setDisconnectHandler(ClientDisconnectHandler disconnectHandler_)
          Sets the ClientDisconnectHandler.
 void setDuplicateMessageHandler(MessageHandler messageHandler)
          Sets the MessageHandler instance used for duplicate messages.
 void setExceptionListener(ExceptionListener exceptionListener)
          Sets the ExceptionListener instance used for communicating absorbed exceptions.
 void setFailedWriteHandler(FailedWriteHandler handler_)
          Sets the FailedWriteHandler instance used to report on failed messages that have been written.
 void setHeartbeat(int intervalSeconds_)
          Requests a server heartbeat, and configures the client to close the connection if a heartbeat (or other activity) is not seen on the connection after two heartbeat intervals.
 void setHeartbeat(int intervalSeconds_, int timeoutSeconds_)
          Requests a server heartbeat, and configures the client to close the connection if a heartbeat (or other activity) is not seen on the connection.
 void setLastChanceMessageHandler(MessageHandler messageHandler)
          Sets the MessageHandler instance used when no other handler matches.
 void setPublishStore(Store store)
          Sets the underlying publish store, which is used to store published messages until the AMPS instance has acknowledged those messages.
 void setSubscriptionManager(SubscriptionManager subscriptionManager)
          Sets the SubscriptionManager instance used for recording active subscriptions.
 void setUnhandledMessageHandler(MessageHandler messageHandler)
          Deprecated. Use setLastChanceMessageHandler instead.
 CommandId sow(MessageHandler messageHandler, String topic, int batchSize, long timeout)
          Executes a SOW query.
 CommandId sow(MessageHandler messageHandler, String topic, long timeout)
          Executes a SOW query.
 CommandId sow(MessageHandler messageHandler, String topic, String filter, int batchSize, long timeout)
          Executes a SOW query.
 CommandId sow(MessageHandler messageHandler, String topic, String filter, int batchSize, String options, long timeout)
          Executes a SOW query.
 CommandId sow(MessageHandler messageHandler, String topic, String filter, String orderBy, String bookmark, int batchSize, int topN, String options, long timeout)
          Executes a SOW query.
 MessageStream sow(String topic)
          Synchronously execute a SOW query.
 MessageStream sow(String topic, String filter)
          Synchronously execute a SOW query.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, int batchSize, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, boolean oofEnabled, boolean sendEmpties, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, boolean oofEnabled, boolean sendEmpties, String options, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndDeltaSubscribe(MessageHandler messageHandler, String topic, String filter, String orderBy, int batchSize, int topN, String options, long timeout)
          Executes a SOW query and places a delta subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, int batchSize, long timeout)
          Executes a SOW query and places a subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, long timeout)
          Executes a SOW query and places a subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, boolean oofEnabled, long timeout)
          Executes a SOW query and places a subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, long timeout)
          Executes a SOW query and places a subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, String filter, int batchSize, String options, long timeout)
          Executes a SOW query and places a subscription.
 CommandId sowAndSubscribe(MessageHandler messageHandler, String topic, String filter, String orderBy, String bookmark, int batchSize, int topN, String options, long timeout)
          Executes a SOW query and places a subscription.
 MessageStream sowAndSubscribe(String topic)
          Executes a SOW query and places a subscription.
 MessageStream sowAndSubscribe(String topic, String filter)
          Executes a SOW query and places a subscription.
 CommandId sowDelete(MessageHandler messageHandler, String topic, String filter, long timeout)
          Executes a SOW delete with filter.
 CommandId sowDelete(MessageHandler messageHandler, String topic, String filter, String options, long timeout)
          Executes a SOW delete with filter.
 Message sowDelete(String topic, String filter, long timeout)
          Executes a SOW delete with filter.
 CommandId sowDeleteByData(MessageHandler messageHandler, String topic, String data, long timeout)
          Executes a SOW delete by data.
 CommandId sowDeleteByKeys(MessageHandler messageHandler, String topic, String keys, long timeout)
          Executes a SOW delete using the SowKey assigned by AMPS to specify the messages to delete.
 void startTimer()
          Sends a start timer command to AMPS, which can be later stopped with a stop timer command.
 CommandId stopTimer(MessageHandler handler_)
          Sends a stop timer command to AMPS
 CommandId subscribe(MessageHandler messageHandler, String topic, long timeout)
          Places a subscription with AMPS.
 CommandId subscribe(MessageHandler messageHandler, String topic, String filter, long timeout)
          Places a subscription with AMPS.
 CommandId subscribe(MessageHandler messageHandler, String topic, String filter, String options, long timeout)
          Places a subscription with AMPS.
 CommandId subscribe(MessageHandler messageHandler, String topic, String filter, String options, long timeout, String subId)
          Places a subscription with AMPS.
 MessageStream subscribe(String topic)
          Places a subscription with AMPS.
 MessageStream subscribe(String topic, String filter)
          Places a subscription with AMPS.
 void unsubscribe()
          Remove all of the client's subscriptions from AMPS.
 void unsubscribe(CommandId subscriptionId)
          Remove a subscription from AMPS.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

exceptionListener

protected ExceptionListener exceptionListener

MIN_PERSISTED_BOOKMARK_VERSION

public static final int MIN_PERSISTED_BOOKMARK_VERSION
See Also:
Constant Field Values

MIN_MULTI_BOOKMARK_VERSION

public static final int MIN_MULTI_BOOKMARK_VERSION
See Also:
Constant Field Values
Constructor Detail

Client

public Client(String name)
Creates a client.

Parameters:
name - Name for the client. This name is used for duplicate message detection and should be unique.

Client

public Client(String name,
              int version)
Creates a client.

Parameters:
name - Name for the client. This name is used for duplicate message detection and should be unique.
version - Server version connecting to

Client

public Client(String name,
              Transport transport)
Creates a client with a transport.

Parameters:
name - Name for the client. This name is used for duplicate message detection and should be unique.
transport - Transport to use for this client

Client

public Client(String name,
              Transport transport,
              int version)
Creates a client with a transport

Parameters:
name - Name for the client. This name is used for duplicate message detection and should be unique.
transport - Transport to use with the client
version - Server version connecting to
Method Detail

getName

public String getName()
Return the name of the Client.

Returns:
String Client name

getURI

public URI getURI()
Return the URI the Client is connected to.

Returns:
URI

getServerVersion

public int getServerVersion()
Return the server version retrieved during logon. If the client has not logged on or is connected to a server whose version is less than 3.8.0.0 this function will return 0. The version uses 2 digits each for major minor maintenance and hotfix i.e., 3.8.1.5 will return 3080105 Versions of AMPS prior to 3.8.0.0 did not return the server version to the client in the logon ack.

Returns:
The version of the server as a long.

getVersionAsInt

public static int getVersionAsInt(String version)
                           throws CommandException
Return the numeric value for the given version string with the pattern: Major.Minor.Maintenance.Hotfix The version uses 2 digits each for major minor maintenance and hotfix i.e., 3.8.1.5 will return 3080105 Version strings passed in can be shortened to not include all levels so 3.8 will return 3080000.

Parameters:
version - The version string to convert.
Returns:
The version as a int.
Throws:
CommandException - The string doesn't represent a valid version.

getTransport

public Transport getTransport()
Return the underlying transport. For advanced users, this method provides direct access to the transport. Care needs to be taken to not modify the underlying transport in ways that are incompatible with the Client.

Returns:
Transport Underlying transport instance

setBookmarkStore

public void setBookmarkStore(BookmarkStore val)
Sets the underlying bookmark store, which is used to track which messages the client has received and which messages have been processed by the program. This method replaces any existing bookmark store for the client, without transferring the state of that store.

Parameters:
val - The new bookmark store.

getBookmarkStore

public BookmarkStore getBookmarkStore()
Returns the underlying bookmark store for this client. The bookmark store is used to track which messages the client has received and which messages have been processed by the program.

Returns:
BookmarkStore The bookmark store for this client.

setPublishStore

public void setPublishStore(Store store)
Sets the underlying publish store, which is used to store published messages until the AMPS instance has acknowledged those messages. This method replaces any existing publish store for the client, without transferring the state of that store.

Parameters:
store - The new publish store.

getPublishStore

public Store getPublishStore()
Returns the underlying publish store for this client. The publish store is used to store published messages until the AMPS instance has acknowledged those messages.

Returns:
Store The publish store for this client.

connect

public void connect(String uri)
             throws ConnectionException
Connects to the AMPS instance through the provided URI. The URI is a String with the format: transport://host:port/protocol Notice that the protocol can be independent of the message type. 60East recommends using the amps protocol, although some installations use one of the legacy protocols such as fix, nvfix or xml. Contact your server administrator for the correct URI for the instance.

Parameters:
uri - The URI string to connect to
Throws:
ConnectionRefusedException - The connection could not be established
AlreadyConnectedException - The connection is already connected
InvalidURIException - The specified URI is invalid
ProtocolException - The protocol is invalid
TransportTypeException - The transport type is invalid
ConnectionException

setDisconnectHandler

public void setDisconnectHandler(ClientDisconnectHandler disconnectHandler_)
Sets the ClientDisconnectHandler. In the event that the Client is disconnected from AMPS, the invoke method from the ClientDisconnectHandler will be invoked.

Parameters:
disconnectHandler_ - The disconnect handler

getDisconnectHandler

public ClientDisconnectHandler getDisconnectHandler()
Returns the current ClientDisconnectHandler set on self.

Returns:
The current disconnect handler.

setUnhandledMessageHandler

public void setUnhandledMessageHandler(MessageHandler messageHandler)
Deprecated. Use setLastChanceMessageHandler instead.

Sets the MessageHandler instance used when no other handler matches.

Parameters:
messageHandler - The message handler used when no other handler matches.

setLastChanceMessageHandler

public void setLastChanceMessageHandler(MessageHandler messageHandler)
Sets the MessageHandler instance used when no other handler matches.

Parameters:
messageHandler - The message handler used when no other handler matches.

setExceptionListener

public void setExceptionListener(ExceptionListener exceptionListener)
Sets the ExceptionListener instance used for communicating absorbed exceptions.

Parameters:
exceptionListener - The exception listener instance to invoke for exceptions.

setSubscriptionManager

public void setSubscriptionManager(SubscriptionManager subscriptionManager)
Sets the SubscriptionManager instance used for recording active subscriptions.

Parameters:
subscriptionManager - The subscription manager invoked when the subscriptions change.

getSubscriptionManager

public SubscriptionManager getSubscriptionManager()
Returns the SubscriptionManager instance used for recording active subscriptions.

Returns:
The current subscription manager.

setDuplicateMessageHandler

public void setDuplicateMessageHandler(MessageHandler messageHandler)
Sets the MessageHandler instance used for duplicate messages.

Parameters:
messageHandler - The message handler to invoke for duplicate messages

setFailedWriteHandler

public void setFailedWriteHandler(FailedWriteHandler handler_)
Sets the FailedWriteHandler instance used to report on failed messages that have been written.

Parameters:
handler_ - The handler to invoke for published duplicates.

addConnectionStateListener

public void addConnectionStateListener(ConnectionStateListener listener_)
Adds a ConnectionStateListener instance that will be invoked when this client connects or disconnects.

Parameters:
listener_ - The instance to invoke.
Since:
4.0.0.0

removeConnectionStateListener

public void removeConnectionStateListener(ConnectionStateListener listener_)
Removes a ConnectionStateListener from being invoked when this client connects or disconnects.

Parameters:
listener_ - The instance to remove.
Since:
4.0.0.0

broadcastConnectionStateChanged

protected void broadcastConnectionStateChanged(int newState_)

disconnect

public void disconnect()
Disconnect from the AMPS server.


close

public void close()
Disconnect from the AMPS server.

Specified by:
close in interface Closeable

allocateMessage

public Message allocateMessage()
Creates a new Message appropriate for this client. This function should be called rarely, since it does allocate a handful of small objects. Users sensitive to garbage collection delays should cache the message object for later usage.

Returns:
A new Message instance

send

public void send(Message message)
          throws DisconnectedException
Send a Message to AMPS via the Transport used in the Client. This method is provided for special cases. In general, you can get the same results with additional error checking by using a Command object with the execute or executeAsync methods.

Parameters:
message - The message to send
Throws:
DisconnectedException - The connection was disconnected at time of send

send

public CommandId send(MessageHandler messageHandler,
                      Message message,
                      long timeout)
               throws AMPSException
Send a Message to AMPS and register the messageHandler for any messages resulting from the command execution. This method is provided for special cases. In general, you can get the same results with additional error checking by using a Command object with the execute or executeAsync methods.

Parameters:
messageHandler - The message handler that'll receive messages for this command
message - The message to send
timeout - The number of milliseconds to wait for command acknowledgment
Returns:
The command identifier assigned to this command, or null if none is assigned.
Throws:
AMPSException - An exception occured while sending or waiting for a response to this Message.

execute

public MessageStream execute(Command command)
                      throws AMPSException
Execute the provided command and return messages received in response in a MessageStream. This method creates a message based on the provided Command, sends the message to AMPS, and receives the results. AMPS sends the message and receives the results on a background thread. That thread populates the MessageStream returned by this method.

Parameters:
command - The Command object containing the command to send to AMPS
Returns:
A MessageStream that provides messages received in response to the command
Throws:
AMPSException
Since:
4.0.0.0

executeAsync

public CommandId executeAsync(Command command,
                              MessageHandler handler)
                       throws AMPSException
Execute the provided command on a background thread and provide messages received in response to the handler provided. This method creates a message based on the provided Command, sends the message to AMPS, and invokes the provided MessageHandler to process messages returned in response to the command. AMPS sends the message and receives the results on a background thread. The MessageHandler runs on the background thread.

Parameters:
command - The Command object containing the command to send to AMPS
handler - The MessageHandler to invoke to process messages received
Returns:
the CommandId for the command
Throws:
AMPSException
Since:
4.0.0.0

setHeartbeat

public void setHeartbeat(int intervalSeconds_,
                         int timeoutSeconds_)
                  throws DisconnectedException
Requests a server heartbeat, and configures the client to close the connection if a heartbeat (or other activity) is not seen on the connection.

Parameters:
intervalSeconds_ - The time (seconds) between beats from the server.
timeoutSeconds_ - The time (seconds) to allow silence on the connection before assuming it is dead.
Throws:
DisconnectedException - The client became disconnected while attempting to send the heartbeat request.

setHeartbeat

public void setHeartbeat(int intervalSeconds_)
                  throws DisconnectedException
Requests a server heartbeat, and configures the client to close the connection if a heartbeat (or other activity) is not seen on the connection after two heartbeat intervals.

Parameters:
intervalSeconds_ - The time (seconds) between beats from the server.
Throws:
DisconnectedException - The client became disconnected while attempting to send the heartbeat request.

publish

public long publish(byte[] topic,
                    int topicOffset,
                    int topicLength,
                    byte[] data,
                    int dataOffset,
                    int dataLength)
             throws AMPSException
Publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - the topic to publish to
topicOffset - the offset in topic where the topic begins
topicLength - the length of the topic in the topic array
data - the data to publish
dataOffset - the offset in data where data begins
dataLength - the length of the data
Returns:
the sequence number for the message when a persistent store is configured for the client, 0 if no store is configured
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

publish

public long publish(String topic,
                    String data)
             throws AMPSException
Publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
data - Data to publish to the topic
Returns:
the sequence number for the message when a persistent store is configured for the client, 0 if no store is configured
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

publish

public long publish(byte[] topic,
                    int topicOffset,
                    int topicLength,
                    byte[] data,
                    int dataOffset,
                    int dataLength,
                    int expiration)
             throws AMPSException
Publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - the topic to publish to
topicOffset - the offset in topic where the topic begins
topicLength - the length of the topic in the topic array
data - the data to publish
dataOffset - the offset in data where data begins
dataLength - the length of the data
expiration - the number of seconds until the message expires
Returns:
the sequence number for the message when a persistent store is configured for the client, 0 if no store is configured
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

publish

public long publish(String topic,
                    String data,
                    int expiration)
             throws AMPSException
Publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
data - Data to publish to the topic
expiration - the number of seconds until the message expires
Returns:
the sequence number for the message when a persistent store is configured for the client, 0 if no store is configured
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

deltaPublish

public void deltaPublish(byte[] topic,
                         int topicOffset,
                         int topicLength,
                         byte[] data,
                         int dataOffset,
                         int dataLength)
                  throws AMPSException
Delta publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
topicOffset - offset into topic array where the topic name begins
topicLength - length of topic array
data - Data to publish to the topic
dataOffset - offset into data array where the data begins
dataLength - length of data array
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

deltaPublish

public void deltaPublish(String topic,
                         String data)
                  throws AMPSException
Delta publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
data - Data to publish to the topic
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

deltaPublish

public void deltaPublish(byte[] topic,
                         int topicOffset,
                         int topicLength,
                         byte[] data,
                         int dataOffset,
                         int dataLength,
                         int expiration)
                  throws AMPSException
Delta publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
topicOffset - offset into topic array where the topic name begins
topicLength - length of topic array
data - Data to publish to the topic
dataOffset - offset into data array where the data begins
dataLength - length of data array
expiration - the number of seconds until the message expires
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

deltaPublish

public void deltaPublish(String topic,
                         String data,
                         int expiration)
                  throws AMPSException
Delta publish a message to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. In this store-and-forward case, the persistent store will notify the user, when requested via callback, of the successful persistence of the record within AMPS.

Parameters:
topic - Topic to publish the data to
data - Data to publish to the topic
expiration - the number of seconds until the message expires
Throws:
DisconnectedException - The client was disconnected at time of publish
StoreException - An error occurred writing to the local HA store.
AMPSException

startTimer

public void startTimer()
                throws AMPSException
Sends a start timer command to AMPS, which can be later stopped with a stop timer command.

Throws:
ConnectionException - A connection error occurred while sending.
AMPSException

stopTimer

public CommandId stopTimer(MessageHandler handler_)
                    throws AMPSException
Sends a stop timer command to AMPS

Returns:
The command identifier.
Throws:
ConnectionException - A connection error occured while sending.
AMPSException

logon

public CommandId logon(long timeout)
                throws ConnectionException
Logs into AMPS with the parameters provided in the connect method.

Parameters:
timeout - The number of milliseconds to wait for the command to exceute.
Returns:
The command identifier.
Throws:
ConnectionException - A connection error occured while logging on.
StoreException - An error occured on the local HA store.

logon

public CommandId logon(long timeout,
                       Authenticator authenticator)
                throws ConnectionException
Logs into AMPS with the parameters provided in the connect method.

Parameters:
timeout - The number of milliseconds to wait for the command to execute
authenticator - The custom authenticator object to authenticate against
Returns:
The command identifier
Throws:
TimedOutException - The command execution exceeded the timeout value
DisconnectedException - The operation failed because the connection was invalid
StoreException - An error occured with the HA PublishStore.
ConnectionException

logon

public CommandId logon()
                throws ConnectionException
Logs into AMPS with the parameters provided in the connect method.

Returns:
The command identifier
Throws:
TimedOutException - The command execution exceeded the timeout value
DisconnectedException - The operation failed because the connection was invalid
StoreException - An error occured writing to the local HA store.
ConnectionException

bookmarkSubscribe

public CommandId bookmarkSubscribe(MessageHandler messageHandler,
                                   String topic,
                                   String filter,
                                   CommandId subId,
                                   String bookmark,
                                   String options,
                                   long timeout)
                            throws AMPSException
Places a bookmark subscription with AMPS. Starts replay at the most recent message reported by the BookmarkStore.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
subId - The subscription ID. You may optionally provide a subscribtion ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the 'replace' option, this is the subscription to be replaced. With a bookmark store, this is the subscription ID used for recovery. So, when using a persistent bookmark store, provide an explicit subscription ID that is consistent across application restarts.
bookmark - The timestamp or bookmark location at which to start the subscription. This parameter can be the bookmark assigned by AMPS to a message, one of the special values in Client.Bookmarks, or a string of the format YYYYmmddTHHMMSS, as described in the AMPS User's guide.
options - A Message.Options value indicating desired options for this subscription. Use Message.Options.None if no options are desired.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

bookmarkDeltaSubscribe

public CommandId bookmarkDeltaSubscribe(MessageHandler messageHandler,
                                        String topic,
                                        String filter,
                                        CommandId subId,
                                        String bookmark,
                                        String options,
                                        long timeout)
                                 throws AMPSException
Places a bookmark delta subscription with AMPS. Starts replay at the most recent message reported by the BookmarkStore.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
subId - The subscription ID. You may wish to supply your own subscription ID to ease recovery scenarios, instead of having the system generate one for you.
bookmark - The timestamp or bookmark location at which to start the subscription. This parameter can be the bookmark assigned by AMPS to a message, one of the special values in Client.Bookmarks, or a string of the format YYYYmmddTHHMMSS, as described in the AMPS User's guide.
options - A Message.Options value indicating desired options for this subscription. Use Message.Options.None if no options are desired.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public CommandId subscribe(MessageHandler messageHandler,
                           String topic,
                           String filter,
                           long timeout)
                    throws AMPSException
Places a subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public CommandId subscribe(MessageHandler messageHandler,
                           String topic,
                           String filter,
                           String options,
                           long timeout)
                    throws AMPSException
Places a subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public CommandId subscribe(MessageHandler messageHandler,
                           String topic,
                           String filter,
                           String options,
                           long timeout,
                           String subId)
                    throws AMPSException
Places a subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
subId - The subscription id to use for the subscription.
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public MessageStream subscribe(String topic)
                        throws AMPSException
Places a subscription with AMPS.

Parameters:
topic - The topic to subscribe to
Returns:
a MessageStream to iterate over.
Throws:
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public MessageStream subscribe(String topic,
                               String filter)
                        throws AMPSException
Places a subscription with AMPS.

Parameters:
topic - The topic to subscribe to
filter - The filter
Returns:
a MessageStream to iterate over.
Throws:
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

subscribe

public CommandId subscribe(MessageHandler messageHandler,
                           String topic,
                           long timeout)
                    throws AMPSException
Places a subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

deltaSubscribe

public CommandId deltaSubscribe(MessageHandler messageHandler,
                                String topic,
                                String filter,
                                String options,
                                long timeout)
                         throws AMPSException
Places a delta subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

deltaSubscribe

public CommandId deltaSubscribe(MessageHandler messageHandler,
                                String topic,
                                String filter,
                                String options,
                                long timeout,
                                String subId)
                         throws AMPSException
Places a delta subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
subId - The subscription id to use for the subscription.
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

deltaSubscribe

public CommandId deltaSubscribe(MessageHandler messageHandler,
                                String topic,
                                String filter,
                                long timeout)
                         throws AMPSException
Places a delta subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

deltaSubscribe

public CommandId deltaSubscribe(MessageHandler messageHandler,
                                String topic,
                                long timeout)
                         throws AMPSException
Places a delta subscription with AMPS.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

unsubscribe

public void unsubscribe(CommandId subscriptionId)
                 throws DisconnectedException
Remove a subscription from AMPS.

Parameters:
subscriptionId - The subscription identifier to remove
Throws:
DisconnectedException - The client was disconnected at the time of execution

unsubscribe

public void unsubscribe()
                 throws DisconnectedException
Remove all of the client's subscriptions from AMPS.

Throws:
DisconnectedException - The client was disconnected at the time of execution

sow

public MessageStream sow(String topic,
                         String filter)
                  throws AMPSException
Synchronously execute a SOW query.

Parameters:
topic - The topic to query
filter - The filter
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public MessageStream sow(String topic)
                  throws AMPSException
Synchronously execute a SOW query.

Parameters:
topic - The topic to query
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public CommandId sow(MessageHandler messageHandler,
                     String topic,
                     String filter,
                     String orderBy,
                     String bookmark,
                     int batchSize,
                     int topN,
                     String options,
                     long timeout)
              throws AMPSException
Executes a SOW query.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
orderBy - The ordering property
bookmark - The timestamp or bookmark location for a historical query. This parameter can be the bookmark assigned by AMPS to a message, one of the special values in Client.Bookmarks, or a string of the format YYYYmmddTHHMMSS, as described in the AMPS User's guide.
batchSize - The batching parameter to use for the results
topN - The maximum number of records the server will return (default is all that match)
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public CommandId sow(MessageHandler messageHandler,
                     String topic,
                     String filter,
                     int batchSize,
                     String options,
                     long timeout)
              throws AMPSException
Executes a SOW query.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public CommandId sow(MessageHandler messageHandler,
                     String topic,
                     String filter,
                     int batchSize,
                     long timeout)
              throws AMPSException
Executes a SOW query.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public CommandId sow(MessageHandler messageHandler,
                     String topic,
                     int batchSize,
                     long timeout)
              throws AMPSException
Executes a SOW query.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
batchSize - The batching parameter to use for the results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sow

public CommandId sow(MessageHandler messageHandler,
                     String topic,
                     long timeout)
              throws AMPSException
Executes a SOW query.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public MessageStream sowAndSubscribe(String topic,
                                     String filter)
                              throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
topic - The topic to subscribe to
filter - The filter
Returns:
A MessageStream to iterate over.
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public MessageStream sowAndSubscribe(String topic)
                              throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
topic - The topic to subscribe to
Returns:
A MessageStream to iterate over.
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 String filter,
                                 String orderBy,
                                 String bookmark,
                                 int batchSize,
                                 int topN,
                                 String options,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
orderBy - The ordering property
bookmark - The timestamp or bookmark location for a historical query. This parameter can be the bookmark assigned by AMPS to a message, one of the special values in Client.Bookmarks, or a string of the format YYYYmmddTHHMMSS, as described in the AMPS User's guide.
batchSize - The batching parameter to use for the SOW query results
topN - The maximum number of records the server will return (default is all that match)
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 String filter,
                                 int batchSize,
                                 String options,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 String filter,
                                 int batchSize,
                                 boolean oofEnabled,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
oofEnabled - Specifies whether or not Out-of-Focus processing is enabled
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 String filter,
                                 int batchSize,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 int batchSize,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
batchSize - The batching parameter to use for the SOW query results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndSubscribe

public CommandId sowAndSubscribe(MessageHandler messageHandler,
                                 String topic,
                                 long timeout)
                          throws AMPSException
Executes a SOW query and places a subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      String filter,
                                      String orderBy,
                                      int batchSize,
                                      int topN,
                                      String options,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
orderBy - The ordering property
batchSize - The batching parameter to use for the SOW query results
topN - The maximum number of records the server will return (default is all that match)
options - A value from Message.Options indicating additional processing options
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      String filter,
                                      int batchSize,
                                      boolean oofEnabled,
                                      boolean sendEmpties,
                                      String options,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
oofEnabled - Specifies whether or not Out-of-Focus processing is enabled
sendEmpties - Specifies whether or not unchanged records are received on the delta subscription
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      String filter,
                                      int batchSize,
                                      boolean oofEnabled,
                                      boolean sendEmpties,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
oofEnabled - Specifies whether or not Out-of-Focus processing is enabled
sendEmpties - Specifies whether or not unchanged records are received on the delta subscription
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      String filter,
                                      int batchSize,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
filter - The filter
batchSize - The batching parameter to use for the SOW query results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      int batchSize,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
batchSize - The batching parameter to use for the SOW query results
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowAndDeltaSubscribe

public CommandId sowAndDeltaSubscribe(MessageHandler messageHandler,
                                      String topic,
                                      long timeout)
                               throws AMPSException
Executes a SOW query and places a delta subscription.

Parameters:
messageHandler - The message handler to invoke with matching messages
topic - The topic to subscribe to
timeout - The maximum time to wait for the subscription to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
SubscriptionAlreadyExistsException - A subscription with this identifier is already registered
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowDelete

public CommandId sowDelete(MessageHandler messageHandler,
                           String topic,
                           String filter,
                           String options,
                           long timeout)
                    throws AMPSException
Executes a SOW delete with filter.

Parameters:
messageHandler - The message handler to invoke with stats and completed acknowledgements
topic - The topic to subscribe to
filter - The filter
options - A value from Message.Options indicating additional processing options.
timeout - The maximum time to wait for the SOW delete to be started to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowDelete

public CommandId sowDelete(MessageHandler messageHandler,
                           String topic,
                           String filter,
                           long timeout)
                    throws AMPSException
Executes a SOW delete with filter.

Parameters:
messageHandler - The message handler to invoke with stats and completed acknowledgements
topic - The topic to subscribe to
filter - The filter
timeout - The maximum time to wait for the SOW delete to be started to be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowDelete

public Message sowDelete(String topic,
                         String filter,
                         long timeout)
                  throws AMPSException
Executes a SOW delete with filter.

Parameters:
topic - The topic to subscribe to
filter - The filter
timeout - The maximum time to wait for the SOW delete to be started to be placed (milliseconds)
Returns:
The stats message returned by this delete.
Throws:
BadFilterException - The provided filter is invalid
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowDeleteByKeys

public CommandId sowDeleteByKeys(MessageHandler messageHandler,
                                 String topic,
                                 String keys,
                                 long timeout)
                          throws AMPSException
Executes a SOW delete using the SowKey assigned by AMPS to specify the messages to delete. When you have the SowKeys for the messages, this method is more efficient than using a filter to delete messages from the SOW. For example, to efficiently delete a message that your program has received from AMPS:

  // DeleteMessageHandler receives a message containing
  // the results of the delete.
  DeleteMessageHandler dmh = new DeleteMessageHandler();

  client.sowDeleteByKeys(dmh, message.getTopic(), message.getSowKey(), 1000); 
 

Parameters:
messageHandler - The message handler to invoke with stats and completed acknowledgements
topic - The topic to execute the SOW delete against
keys - A comma separated list of SOW keys to be deleted
timeout - The maximum time to wait for the SOW delete to be be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
BadRegexTopicException - The topic specified was an invalid regular expression
TimedOutException - The operation took longer than the timeout to execute
DisconnectedException - The client wasn't connected when the operation was executed
AMPSException

sowDeleteByData

public CommandId sowDeleteByData(MessageHandler messageHandler,
                                 String topic,
                                 String data,
                                 long timeout)
                          throws AMPSException
Executes a SOW delete by data. AMPS uses key fields in the data to find and delete a message with the same keys.

Parameters:
messageHandler - The message handler to invoke with stats and completed acknowledgements
topic - The topic to execute the SOW delete against
data - The message to match and delete in the SOW cache
timeout - The maximum time to wait for the SOW delete to be be placed (milliseconds)
Returns:
The command identifier assigned to this command
Throws:
AMPSException - An error occurred while waiting for this command to be processed.

publishFlush

public void publishFlush()
                  throws DisconnectedException,
                         TimedOutException
Clear the queued messages which may be waiting in the transport, publish store or in the AMPS publish queue. Method returns when published messages have been flushed.

Throws:
DisconnectedException
TimedOutException

publishFlush

public void publishFlush(long timeout)
                  throws DisconnectedException,
                         TimedOutException
Return when all published messages have been confirmed to have made it through the publish queue inside the AMPS instnace.

Parameters:
timeout - Number of milliseconds to wait for flush
Throws:
DisconnectedException
TimedOutException

flush

public long flush()
           throws DisconnectedException
Clear the queued messages which may be waiting in the transport

Returns:
long Number of messages or bytes queued after flush is completed or timed out
Throws:
DisconnectedException

flush

public long flush(long timeout)
           throws DisconnectedException
Clear the queued messages which may be waiting in the transport

Parameters:
timeout - Number of milliseconds to wait for flush
Returns:
long Number of messages or bytes queued after flush is completed or timed out
Throws:
DisconnectedException

getVersion

public String getVersion()
Return the build number for the client that is stored in the Manifes.mf of the jar file.

Returns:
String Build version number.

getConnectionInfo

public ConnectionInfo getConnectionInfo()
Assembles a new ConnectionInfo with the state of this client and associated classes.

Returns:
A new ConnectionInfo object.