com.crankuptheamps.client

Class HAClient

java.lang.Object

com.crankuptheamps.client.Client

com.crankuptheamps.client.HAClient

All Implemented Interfaces:

java.lang.AutoCloseable

public class HAClient
extends Client

A highly-available AMPS Client object that automatically reconnects and re-subscribes to AMPS instances upon disconnect. Most production applications use the HAClient rather than Client.

An HAClient object provides failover and resubscription functionality by default. For reliable publish, set a PublishStore for the HAClient (and, in most cases, set a FailedWriteHandler as well so the application can detect any failed publishes). For managing transaction log replays, set a BookmarkStore.

To connect to AMPS, you must provide a ServerChooser implementation to the HAClient. By default, the HAClient provides a ExponentialDelayStrategy with the default delay and backoff behavior for that class.

By default, an HAClient object has the reconnect and resubscribe functionality provided by the MemorySubscriptionManager and the HAClient.HADisconnectHandler classes. It is typically not necessary to replace the disconnect handler or subscription manager provided by default. Notice that replacing either of these defaults will change the failover, resubscription, and/or republish behavior of the HAClient.

See the Developer Guide for more information on using the HAClient.

Example usage of the HAClient for publishing a JSON message:

 

 public class ConsolePublisher{

   // The location of the AMPS server.
   private static final String uri_ = "tcp://127.0.0.1:9007/amps/json";
   
   public static void main(String[] args) {
      System.out.println("Starting the console publisher.");
 
      try (HAClient client = new HAClient("ConsolePublisher");) {
      // wait a bit to give a subscriber time to listen
      Thread.sleep(2000L);
 
      // Create a custom server chooser
      DefaultServerChooser serverChooser = new DefaultServerChooser();
      serverChooser.add(uri_);
   
      // Set the server chooser for the HAClient
      client.setServerChooser(serverChooser);
      // connect to the AMPS server and logon
      client.connectAndLogon();
      System.out.println("Publisher Connected");
   

      client.publish("messages", "{\"message\" : \"Hello, World!\"}");
     }
     catch (Exception e)
     {
     System.err.println(e.getLocalizedMessage());
     e.printStackTrace(System.err);
     }

   }

 }
 
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HAClient.HADisconnectHandler Class used to handle disconnects for highly-available AMPS Clients.

Nested classes/interfaces inherited from class com.crankuptheamps.client.Client

Client.Bookmarks, Client.ClientHandler, Client.GlobalCommandTypeHandlers, Client.Version

Field Summary

Fields inherited from class com.crankuptheamps.client.Client

_lastFailedConnectionVersion, exceptionListener, lock, MIN_MULTI_BOOKMARK_VERSION, MIN_PERSISTED_BOOKMARK_VERSION

Constructor Summary

Constructors

Constructor and Description
HAClient() Default constructor that creates a client without a name.
HAClient(java.lang.String name) Constructs a new HAClient.

Method Summary

Modifier and Type	Method and Description
void	connect()
void	connect(java.lang.String uri) Connects to the AMPS instance through the provided URI.
void	connectAndLogon() Connects to the next server chosen for us by our ServerChooser.
static HAClient	createFileBacked(java.lang.String name, java.lang.String publishLog, int initialPublishCapacity, java.lang.String subscribeLog) Creates a new highly available client backed by disk.
static HAClient	createFileBacked(java.lang.String name, java.lang.String publishLog, java.lang.String subscribeLog) Creates a new highly available client backed by disk.
static HAClient	createMemoryBacked(java.lang.String name) Creates a new memory-backed highly-available client.
void	disconnect() Disconnect from the AMPS server.
ConnectionInfo	getConnectionInfo() Assembles a new ConnectionInfo with the state of this client and associated classes.
java.lang.String	getLogonOptions() Returns the current logon options string.
ReconnectDelayStrategy	getReconnectDelayStrategy() Returns the ReconnectDelayStrategy used to control sleeping behavior before connecting to a server.
ServerChooser	getServerChooser() Returns the current ServerChooser for this client.
int	getTimeout() Returns the timeout used for logging on and resubscribing, once a connection is re-established.
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 and the logon correlation id, if any, that is set.
CommandId	logon(long timeout, Authenticator authenticator) Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.
CommandId	logon(long timeout, Authenticator authenticator, java.lang.String options) Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.
CommandId	logon(long timeout, java.lang.String options) Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.
CommandId	logon(java.lang.String options) Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.
void	setLogonOptions(java.lang.String options_) Sets a logon options string for self.
void	setReconnectDelay(int reconnectInterval) Sets the time delay between reconnect events.
HAClient	setReconnectDelayStrategy(ReconnectDelayStrategy delayStrategy_) Sets the ReconnectDelayStrategy used to control sleeping behavior before connecting to a server.
void	setServerChooser(ServerChooser serverChooser_) Sets a ServerChooser for self.
void	setTimeout(int timeout_) Sets the timeout used for logging on and resubscribing, once a connection is re-established.

Methods inherited from class com.crankuptheamps.client.Client

_ack, _ack, _ack, ack, ack, ack, ack, ack, ack, addConnectionStateListener, addHttpPreflightHeader, addHttpPreflightHeader, addMessageHandler, allocateMessage, bookmarkSubscribe, broadcastConnectionStateChanged, clearHttpPreflightHeaders, close, deltaPublish, deltaPublish, deltaPublish, deltaPublish, deltaSubscribe, deltaSubscribe, deltaSubscribe, deltaSubscribe, execute, executeAsync, flush, flush, flushAcks, getAckBatchSize, getAckTimeout, getAutoAck, getBookmarkStore, getDefaultMaxDepth, getDisconnectHandler, getDuplicateMessageHandler, getExceptionListener, getFailedWriteHandler, getHeartbeatInterval, getHttpPreflightHeaders, getLogonCorrelationData, getName, getNameHash, getPublishStore, getReadTimeout, getRetryOnDisconnect, getServerVersion, getServerVersionInfo, getSubscriptionManager, getThreadCreatedHandler, getTransport, getTransportDisconnectHandler, getTransportFilter, getTransportMessageHandler, getURI, getVersion, getVersionAsInt, publish, publish, publish, publish, publishFlush, publishFlush, publishFlush, publishFlush, removeConnectionStateListener, removeMessageHandler, send, send, setAckBatchSize, setAckTimeout, setAutoAck, setBookmarkStore, setDefaultMaxDepth, setDisconnectHandler, setDuplicateMessageHandler, setExceptionListener, setFailedWriteHandler, setFailedWriteHandler, setGlobalCommandTypeMessageHandler, setGlobalCommandTypeMessageHandler, setGlobalCommandTypeMessageHandler, setHeartbeat, setHeartbeat, setHttpPreflightHeaders, setLastChanceMessageHandler, setLogonCorrelationData, setName, setPublishStore, setRetryOnDisconnect, setSubscriptionManager, setThreadCreatedHandler, setTransportFilter, setUnhandledMessageHandler, sow, sow, sow, sow, sow, sow, sow, sowAndDeltaSubscribe, sowAndDeltaSubscribe, sowAndDeltaSubscribe, sowAndDeltaSubscribe, sowAndDeltaSubscribe, sowAndDeltaSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowAndSubscribe, sowDelete, sowDelete, sowDelete, sowDeleteByData, sowDeleteByKeys, startTimer, stopTimer, subscribe, subscribe, subscribe, subscribe, subscribe, subscribe, unsubscribe, unsubscribe

Methods inherited from class java.lang.Object

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

Constructor Detail

HAClient

public HAClient()

Default constructor that creates a client without a name. This constructor exists for use with frameworks that require managed objects to have a default constructor. The client MUST still be assigned a name using Client.setName(String) before connecting.

See Also:

HAClient(String), Client.setName(String)

HAClient

public HAClient(java.lang.String name)

Constructs a new HAClient.

Parameters:

name - The client name, passed to the server to uniquely identify this client across sessions. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets.

Method Detail

setReconnectDelay

public void setReconnectDelay(int reconnectInterval)

Sets the time delay between reconnect events. Calling this method creates and installs a new FixedDelayStrategy in this client.

Parameters:

reconnectInterval - The time waited between reconnect events, in milliseconds.

setTimeout

public void setTimeout(int timeout_)

Sets the timeout used for logging on and resubscribing, once a connection is re-established.

Parameters:

timeout_ - The timeout value, in milliseconds, where 0 indicates no timeout.

getTimeout

public int getTimeout()

Returns the timeout used for logging on and resubscribing, once a connection is re-established.

Returns:

The timeout value in milliseconds.

getServerChooser

public ServerChooser getServerChooser()

Returns the current ServerChooser for this client.

Returns:

The current ServerChooser.

setServerChooser

public void setServerChooser(ServerChooser serverChooser_)

Sets a ServerChooser for self.

Parameters:

serverChooser_ - The ServerChooser that will be used by self to reconnect.

getLogonOptions

public java.lang.String getLogonOptions()

Returns the current logon options string.

Returns:

The current String.

setLogonOptions

public void setLogonOptions(java.lang.String options_)

Sets a logon options string for self.

Parameters:

options_ - The String that will be used by self during logon.

createMemoryBacked

public static HAClient createMemoryBacked(java.lang.String name)
                                   throws StoreException

Creates a new memory-backed highly-available client. This client will automatically reconnect and re-subscribe, and uses memory to ensure messages are not lost and duplicates are processed appropriately. This convenience method is equivalent to creating an HAClient and setting a MemoryBookmarkStore and MemoryPublishStore for that client. The MemoryPublishStore has a capacity of 10000 blocks. If your application will not be both publishing to AMPS and using a bookmark replay, it is recommended that you construct an HAClient and then set the appropriate stores.

Parameters:

name - The client name, passed to the server to uniquely identify this client across sessions. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters or square brackets.

Returns:

A new memory-backed HAClient instance.

Throws:

StoreException - Thrown when an operation fails with details of the failure.

createFileBacked

public static HAClient createFileBacked(java.lang.String name,
                                        java.lang.String publishLog,
                                        int initialPublishCapacity,
                                        java.lang.String subscribeLog)
                                 throws java.io.IOException,
                                        StoreException

Creates a new highly available client backed by disk. This client will automatically reconnect and re-subscribe, and uses disk to ensure messages are not lost and duplicates are processed appropriately. This convenience method is equivalent to creating an HAClient and setting a LoggedBookmarkStore and PublishStore for that client. If your application will not be both publishing to AMPS and using a bookmark replay, it is recommended that you construct an HAClient and then set the appropriate stores.

Parameters:

name - The client name, passed to the server to uniquely identify this client across sessions. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets.

publishLog - The path to a file used to store outgoing messages. This file will be created if it does not exist.

initialPublishCapacity - The initial size (in 2k blocks) of the publish store. Choosing an optimal value of initialPublishCapacity can prevent costly resizes, when servers or networks slow down.

subscribeLog - The path to a file used to log incoming message bookmarks. This file will be created if it does not exist.

Returns:

A new HAClient instance.

Throws:

java.io.IOException - Thrown if file creation fails.

StoreException - Thrown when an operation fails with details of the failure.

createFileBacked

public static HAClient createFileBacked(java.lang.String name,
                                        java.lang.String publishLog,
                                        java.lang.String subscribeLog)
                                 throws java.io.IOException,
                                        StoreException

Creates a new highly available client backed by disk. This client will automatically reconnect and re-subscribe, and uses disk to ensure messages are not lost and duplicates are processed appropriately. This convenience method is equivalent to creating an HAClient and setting a LoggedBookmarkStore and PublishStore that client. If your application will not be both publishing to AMPS and using a bookmark replay, it is recommended that you construct an HAClient and then set the appropriate stores.

Parameters:

name - The client name, passed to the server to uniquely identify this client across sessions. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets.

publishLog - The path to a file used to store outgoing messages. This file will be created if it does not exist.

subscribeLog - The path to a file used to log incoming message bookmarks. This file will be created if it does not exist.

Returns:

A new HAClient instance.

Throws:

java.io.IOException - Thrown when creating either the publish store or the bookmark store results in an IOException.

StoreException - Thrown for any other failure. The exception will contain details of the operation that failed.

connectAndLogon

public void connectAndLogon()
                     throws ConnectionException

Connects to the next server chosen for us by our ServerChooser. Will continue attempting to connect and logon to each successive server returned by the ServerChooser until the connection succeeds or the ServerChooser returns an empty URI.

Throws:

ConnectionException - An exception indicating no AMPS instance could be connected to.

connect

public void connect()
             throws ConnectionException

Throws:

ConnectionException

connect

public void connect(java.lang.String uri)
             throws ConnectionException

Description copied from class: Client

Connects to the AMPS instance through the provided URI.

The URI is a String with the format: transport://user:password@host:port/protocol

• transport -- the network transport used for the connection
• user -- the userId used to authenticate the connection
• password -- the password used to authenticate the connection
• host -- the hostname or IP address of the host where AMPS is running
• port -- the port to connect to
• protocol -- the protocol used for the connection

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.

Authentication is optional if the system is using the default authentication provided with AMPS. This default authentication allows all users to authenticate, regardless of the user or password provided. If your AMPS installation uses custom authentication, use the Authenticator appropriate for that authentication mechanism.

Overrides:

connect in class Client

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

logon

public CommandId logon(long timeout)
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.

Overrides:

logon in class Client

Parameters:

timeout - The number of milliseconds to wait for the client to receive and consume a processed ack for this command, where 0 indicates to wait indefinitely

Returns:

The command identifier.

Throws:

ConnectionException - A connection error occurred while logging on.

logon

public CommandId logon(java.lang.String options)
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.

Overrides:

logon in class Client

Parameters:

options - The options string to pass with the logon command

Returns:

The command identifier.

Throws:

ConnectionException - A connection error occurred while logging on.

logon

public CommandId logon(long timeout,
                       java.lang.String options)
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.

Overrides:

logon in class Client

Parameters:

timeout - The number of milliseconds to wait for the client to receive and consume a processed ack for this command, where 0 indicates to wait indefinitely

options - The options string to pass with the logon command

Returns:

The command identifier.

Throws:

ConnectionException - A connection error occurred while logging on.

logon

public CommandId logon(long timeout,
                       Authenticator authenticator)
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.

Overrides:

logon in class Client

Parameters:

timeout - The number of milliseconds to wait for the client to receive and consume a processed ack for this command, where 0 indicates to wait indefinitely

authenticator - The custom authenticator object to authenticate against

Returns:

The command identifier

Throws:

ConnectionException - A connection error occurred while logging on.

logon

public CommandId logon(long timeout,
                       Authenticator authenticator,
                       java.lang.String options)
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method and the logon correlation id, if any, that is set.

Overrides:

logon in class Client

Parameters:

timeout - The number of milliseconds to wait for the client to receive and consume a processed ack for this command, where 0 indicates to wait indefinitely

authenticator - The custom authenticator object to authenticate against

options - The options string to pass with the logon command

Returns:

The command identifier

Throws:

ConnectionException - A connection error occurred while logging on.

logon

public CommandId logon()
                throws ConnectionException

Description copied from class: Client

Logs into AMPS with the parameters provided in the connect method.

Overrides:

logon in class Client

Returns:

The command identifier

Throws:

ConnectionException - A connection error occurred while logging on.

disconnect

public void disconnect()

Description copied from class: Client

Disconnect from the AMPS server.

Overrides:

disconnect in class Client

getConnectionInfo

public ConnectionInfo getConnectionInfo()

Assembles a new ConnectionInfo with the state of this client and associated classes.

Overrides:

getConnectionInfo in class Client

Returns:

A new ConnectionInfo object.

setReconnectDelayStrategy

public final HAClient setReconnectDelayStrategy(ReconnectDelayStrategy delayStrategy_)

Sets the ReconnectDelayStrategy used to control sleeping behavior before connecting to a server.

Parameters:

delayStrategy_ - The delay strategy to use for connecting.

Returns:

Self.

getReconnectDelayStrategy

public ReconnectDelayStrategy getReconnectDelayStrategy()

Returns the ReconnectDelayStrategy used to control sleeping behavior before connecting to a server.

Returns:

The delay strategy to use for connecting.