com.crankuptheamps.client

Class SOWRecoveryPointAdapter

java.lang.Object

com.crankuptheamps.client.SOWRecoveryPointAdapter

All Implemented Interfaces:

RecoveryPointAdapter, java.lang.AutoCloseable, java.lang.Iterable<RecoveryPoint>, java.util.Iterator<RecoveryPoint>

public class SOWRecoveryPointAdapter
extends java.lang.Object
implements RecoveryPointAdapter

An implementation of the recovery point adapter interface that uses an AMPS SOW (State of the World) topic as an external store to persist recovery point state for bookmark replay subscriptions.

This class allows you to use an AMPS SOW topic as a backup bookmark store for bookmark replay. It serves as a recovery point adapter that serializes and deserializes recovery points to and from the SOW topic. To use this class effectively, you will need to configure your AMPS server to include a SOW topic that matches the expected format used by this adapter.

Server-side configuration for AMPS SOW topics is required for successful integration with this class. Ensure that your AMPS server is properly configured to handle SOW topics, including topics matching the expected format used for recovery points. See the 'Java Developer Guide' for the suggested configuration.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_bookmarkField
protected java.util.regex.Pattern	_bookmarkPattern Regular expression pattern to pull the bookmark string from subscription state saved in the AMPS SOW.
protected Client	_client
protected java.lang.String	_clientNameField
protected boolean	_closeClient
protected Command	_cmd
protected RecoveryPoint	_current
protected java.beans.ExceptionListener	_exceptionListener
protected java.lang.String	_initStr
protected java.util.concurrent.ConcurrentHashMap<Field,BookmarkField>	_lastValue A concurrent hash map of subscription id's (known to this store) mapped to the subscription's most-recent-for-recovery value that was last persisted to the SOW.
protected boolean	_recovering
protected Field	_serializeField
protected int	_serializeStart
protected MessageStream	_stream
protected java.lang.String	_subIdField
protected java.util.regex.Pattern	_subIdPattern Regular expression pattern to pull the subscription id from subscription state saved in the AMPS SOW.
protected boolean	_throwNotListen
protected long	_timeoutMillis
protected java.lang.String	_topic
protected java.lang.String	_trackedName
protected boolean	_useTimestamp
protected Field	EPOCH_FIELD
protected static int	JSON_END
protected static int	JSON_INIT_LEN
protected static int	JSON_LEN
protected static int	JSON_START
protected static int	SUBID_LEN

Constructor Summary

Constructors

Constructor and Description
SOWRecoveryPointAdapter(Client client, java.lang.String trackedClientName, boolean closeClient, boolean useTimestamp, boolean throwExceptions) A recovery point adapter implementation that uses an AMPS SOW topic as an external store to persist recovery point state for bookmark replay subscriptions.
SOWRecoveryPointAdapter(Client client, java.lang.String trackedClientName, boolean closeClient, boolean useTimestamp, boolean throwExceptions, long timeoutMillis, java.lang.String topic, java.lang.String clientNameField, java.lang.String subIdField, java.lang.String bookmarkField) A recovery point adapter implementation that uses an AMPS SOW topic as an external store to persist recovery point state for bookmark replay subscriptions.

Method Summary

Modifier and Type	Method and Description
void	close() Close this adapter making sure all updates are at the server and close the internal client if set up to do so.
protected boolean	deserialize(Message m) Deserializes a JSON string into a RecoveryPoint instance for use by next() during bookmark store creation/initialization.
boolean	hasNext() Implements Iterator.hasNext().
protected void	initSerialization() Initializes the serialization buffer and an initial string for serialization purposes.
java.util.Iterator<RecoveryPoint>	iterator() Implements Iterable.iterator() to return this instance.
RecoveryPoint	next() Implements Iterator.next() for a message stream.
void	purge() Purge all recovery information stored in the SOW.
void	purge(Field subId) Purge all recovery information stored in the SOW.
void	remove() Operation not supported.
protected void	runQuery() Set up the MessageStream for data recovery.
protected boolean	serialize(RecoveryPoint recoveryPoint) Serializes a RecoveryPoint to JSON in the internal buffer for publishing to a JSON SOW topic.
void	setExceptionListener(java.beans.ExceptionListener exceptionListener) Sets the ExceptionListener instance used for communicating absorbed exceptions.
void	update(RecoveryPoint recoveryPoint) Sends an update to the underlying SOW.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Iterator

forEachRemaining

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

_trackedName

protected java.lang.String _trackedName

_topic

protected java.lang.String _topic

_clientNameField

protected java.lang.String _clientNameField

_subIdField

protected java.lang.String _subIdField

_bookmarkField

protected java.lang.String _bookmarkField

_client

protected Client _client

_exceptionListener

protected java.beans.ExceptionListener _exceptionListener

_serializeField

protected Field _serializeField

_timeoutMillis

protected long _timeoutMillis

_closeClient

protected boolean _closeClient

_useTimestamp

protected boolean _useTimestamp

_throwNotListen

protected boolean _throwNotListen

_cmd

protected Command _cmd

_stream

protected MessageStream _stream

_recovering

protected boolean _recovering

JSON_START

protected static final int JSON_START

See Also:

Constant Field Values

JSON_END

protected static final int JSON_END

See Also:

Constant Field Values

JSON_LEN

protected static final int JSON_LEN

See Also:

Constant Field Values

SUBID_LEN

protected static final int SUBID_LEN

See Also:

Constant Field Values

JSON_INIT_LEN

protected static final int JSON_INIT_LEN

See Also:

Constant Field Values

_initStr

protected java.lang.String _initStr

_serializeStart

protected int _serializeStart

_current

protected RecoveryPoint _current

EPOCH_FIELD

protected Field EPOCH_FIELD

_bookmarkPattern

protected java.util.regex.Pattern _bookmarkPattern

Regular expression pattern to pull the bookmark string from subscription state saved in the AMPS SOW.

_subIdPattern

protected java.util.regex.Pattern _subIdPattern

Regular expression pattern to pull the subscription id from subscription state saved in the AMPS SOW.

_lastValue

protected final java.util.concurrent.ConcurrentHashMap<Field,BookmarkField> _lastValue

A concurrent hash map of subscription id's (known to this store) mapped to the subscription's most-recent-for-recovery value that was last persisted to the SOW. By caching the last value, we can prevent unneeded writes to the SOW.

Constructor Detail

SOWRecoveryPointAdapter

public SOWRecoveryPointAdapter(Client client,
                               java.lang.String trackedClientName,
                               boolean closeClient,
                               boolean useTimestamp,
                               boolean throwExceptions)
                        throws StoreException

A recovery point adapter implementation that uses an AMPS SOW topic as an external store to persist recovery point state for bookmark replay subscriptions. See full constructor for details on all options.

Parameters:

client - The internal AMPS client instance used to write bookmark state to the AMPS SOW. This MUST NOT be the client whose registered bookmark store is associated with this recovery point adapter. In other words, it must not be the AMPS client used to place the bookmark replay subscriptions whose recovery state is being persisted by this adapter.

trackedClientName - The unique name of the subscriber AMPS client we're tracking bookmark recovery state for. If your client names change with each run, this should be a unique session name that is stable across application restarts. For example, such a name could be formed by concatenating an application name with a logical functional area (e.g. "MyApp_OrderReplay"). This name will be used as a key in the SOW for tracking the subscriber client's bookmark state. For guidance on choosing stable unique AMPS client names or session names for use with this adapter, please see our support FAQ article entitled Unique Client Naming and AMPS.

closeClient - Indicates whether this adapter instance should close its internal AMPS client when this adapter is closed. Defaults to true. If this flag is true, this adapter considers the internal client passed to it during construction as being owned by this adapter, such that its life-cycle should end when this adapter is closed. If false, this adapter will consider it the responsibility of the caller to close the internal client after this adapter is closed, allowing that client to be shared, possibly among multiple adapters (keeping in mind potential performance impacts of multiple threads publishing using the same AMPS client instance).

useTimestamp - Indicates if the last updated timestamp of each entries should be included in the RecoveryPoint. This is similar to useLastModifiedTime in LoggedBookmarkStore.

throwExceptions - Indicates whether exceptions should be thrown to the caller (usually the bookmark store), or should instead be delivered to this adapter's registered exception listener callback. This flag lets the user decide their error handling strategy for recovery state write failures. The default is false, meaning the exception is absorbed, and sent to the exception listener (if any). A value of true means errors in the update() method throw exceptions. NOTE: Since this adapter implementation publishes to an AMPS SOW and most AMPS publishing failures have asynchronous notification, users should consider registering a FailedWriteHandler and publish store on the internal client passed above.

Throws:

StoreException - If client name and trackedClientName are the same.

See Also:

SOWRecoveryPointAdapter(Client, String, boolean, boolean, boolean, long, String, String, String, String)

SOWRecoveryPointAdapter

public SOWRecoveryPointAdapter(Client client,
                               java.lang.String trackedClientName,
                               boolean closeClient,
                               boolean useTimestamp,
                               boolean throwExceptions,
                               long timeoutMillis,
                               java.lang.String topic,
                               java.lang.String clientNameField,
                               java.lang.String subIdField,
                               java.lang.String bookmarkField)
                        throws StoreException

A recovery point adapter implementation that uses an AMPS SOW topic as an external store to persist recovery point state for bookmark replay subscriptions.

Parameters:

client - The internal AMPS client instance used to write bookmark state to the AMPS SOW. This MUST NOT be the client whose registered bookmark store is associated with this recovery point adapter. In other words, it must not be the AMPS client used to place the bookmark replay subscriptions whose recovery state is being persisted by this adapter.

trackedClientName - The unique name of the subscriber AMPS client we're tracking bookmark recovery state for. If your client names change with each run, this should be a unique session name that is stable across application restarts. For example such a name could be formed by concatenating an application name with a logical functional area (e.g. "MyApp_OrderReplay"). This name will be used as a key in the SOW for tracking the subscriber client's bookmark state. For guidance on choosing stable unique AMPS client names or session names for use with this adapter, please see our support FAQ article entitled Unique Client Naming and AMPS.

closeClient - Indicates whether this adapter instance should close its internal AMPS client when this adapter is closed. Defaults to true. If this flag is true, this adapter considers the internal client passed to it during construction as being owned by this adapter, such that its life-cycle should end when this adapter is closed. If false, this adapter will consider it the responsibility of the caller to close the internal client after this adapter is closed, allowing that client to be shared, possibly among multiple adapters (keeping in mind potential performance impacts of multiple threads publishing using the same AMPS client instance).

useTimestamp - Indicates if the last updated timestamp of each entries should be included in the RecoveryPoint. This is similar to useLastModifiedTime in LoggedBookmarkStore.

throwExceptions - Indicates whether exceptions should be thrown to the caller (usually the bookmark store), or should instead be delivered to this adapter's registered exception listener callback. This flag lets the user decide their error handling strategy for recovery state write failures. The default is false, meaning the exception is absorbed, and sent to the exception listener (if any). A value of true means errors in the update() method throw exceptions. NOTE: Since this adapter implementation publishes to an AMPS SOW and most AMPS publishing failures have asynchronous notification, users should consider registering a FailedWriteHandler and publish store on the internal client passed above.

timeoutMillis - The number of milliseconds to wait for the initial sow query to complete and for publish_flush to complete during close(). The default value is 0, which means no timeout.

topic - The AMPS SOW topic configured to persist bookmark recovery state for this adapter. Usually defaults to "/ADMIN/bookmark_store", but this allows users to customize their usage for non-default SOW configs. NOTE: The message type of this topic in the AMPS config must be "json" unless overriding the operation of this adapter in a subclass.

clientNameField - The name of the SOW topic field we use for persisting the tracked client name or session name. Usually just "clientName", but this allows users to customize their usage for non-default SOW configs. NOTE: This field must be one of two key fields configured on the SOW topic.

subIdField - The name of the SOW topic field we use for persisting the subscription id. Usually just "subId", but this allows users to customize their usage for non-default SOW configs. NOTE: This field must be one of two key fields configured on the SOW topic.

bookmarkField - The name of the SOW topic field we use for persisting the bookmark. Usually just "bookmark", but this allows users to customize their usage for non-default SOW configs.

Throws:

StoreException - If client name and trackedClientName are the same.

Method Detail

setExceptionListener

public void setExceptionListener(java.beans.ExceptionListener exceptionListener)

Sets the ExceptionListener instance used for communicating absorbed exceptions.

Parameters:

exceptionListener - The exception listener instance to invoke for internal exceptions.

update

public void update(RecoveryPoint recoveryPoint)
            throws java.lang.Exception

Sends an update to the underlying SOW.

Specified by:

update in interface RecoveryPointAdapter

Parameters:

recoveryPoint - The recovery state to persist in the SOW.

Throws:

java.lang.Exception - StoreException wrapper of exception thrown while clearing the SOW of recovery information.

purge

public void purge()
           throws StoreException

Purge all recovery information stored in the SOW.

Specified by:

purge in interface RecoveryPointAdapter

Throws:

StoreException - Wrapper of exception thrown while clearing the SOW of recovery information.

See Also:

BookmarkStore.purge()

purge

public void purge(Field subId)
           throws StoreException

Purge all recovery information stored in the SOW.

Specified by:

purge in interface RecoveryPointAdapter

Parameters:

subId - The subId of the subscription to remove.

Throws:

StoreException - Wrapper of exception thrown while clearing the SOW of recovery information.

See Also:

BookmarkStore.purge(com.crankuptheamps.client.fields.Field)

close

public void close()
           throws java.lang.Exception

Close this adapter making sure all updates are at the server and close the internal client if set up to do so.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception

runQuery

protected void runQuery()

Set up the MessageStream for data recovery.

hasNext

public boolean hasNext()

Implements Iterator.hasNext().

Specified by:

hasNext in interface java.util.Iterator<RecoveryPoint>

next

public RecoveryPoint next()

Implements Iterator.next() for a message stream.

Specified by:

next in interface java.util.Iterator<RecoveryPoint>

remove

public void remove()

Operation not supported. Implements Iterator.remove() to throw UnsupportedOperationException.

Specified by:

remove in interface java.util.Iterator<RecoveryPoint>

iterator

public java.util.Iterator<RecoveryPoint> iterator()

Implements Iterable.iterator() to return this instance.

Specified by:

iterator in interface java.lang.Iterable<RecoveryPoint>

serialize

protected boolean serialize(RecoveryPoint recoveryPoint)
                     throws java.lang.Exception

Serializes a RecoveryPoint to JSON in the internal buffer for publishing to a JSON SOW topic. Used by the update(RecoveryPoint) method. This method provides an override point where a recovery point can be serialized another message type into the buffer.

Parameters:

recoveryPoint - The recovery point to serialize.

Returns:

true upon successful serialization

Throws:

java.lang.Exception - If an error occurs during serialization.

deserialize

protected boolean deserialize(Message m)
                       throws java.lang.Exception

Deserializes a JSON string into a RecoveryPoint instance for use by next() during bookmark store creation/initialization. This method provides an override point where another message type can be deserialized into a RecoveryPoint. This method is only called via recover() during bookmark store creation/initialization by a single thread.

Parameters:

m - The `sow` Message from the server to deserialize.

Returns:

true if the Message was successfully deserialized into the _current RecoveryPoint.

Throws:

java.lang.Exception - If an error occurs during deserialization.

initSerialization

protected void initSerialization()
                          throws java.lang.Exception

Initializes the serialization buffer and an initial string for serialization purposes. This method prepares the serialization buffer and an initial JSON-like string for later serialization tasks. It handles buffer initialization, ensures sufficient space, and populates the initial string if necessary.

Throws:

java.lang.Exception - if there is an issue during initialization.