com.crankuptheamps.client

Class LoggedBookmarkStore

java.lang.Object

com.crankuptheamps.client.LoggedBookmarkStore

All Implemented Interfaces:

BookmarkStore, java.lang.AutoCloseable

public class LoggedBookmarkStore
extends java.lang.Object
implements BookmarkStore

LoggedBookmarkStore implements a sequentially written log of incoming and discarded messages. This store tracks every bookmark processed in a file. An application should periodically call prune() to manage the size of the file by removing outdated entries. When using LoggedBookmarkStore, it is important to note that this store is intended to provide the ability for the application to fail and resume. If your application does not require this fail-and-resume functionality, it is recommended to use a MemoryBookmarkStore. Usage: The LoggedBookmarkStore is automatically set on the returned client when `createFileBacked` is called. This store is responsible for tracking and managing bookmarks associated with the client's state.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	LoggedBookmarkStore.Subscription The Subscription object is used to represent internal bookmark state for the messages received and discarded on a specific subscription within the bookmark store.

Constructor Summary

Constructors

Constructor and Description
LoggedBookmarkStore(java.lang.String path) This constructor is equivalent to calling `LoggedBookmarkStore(path, 1, false)`.
LoggedBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions) This constructor is equivalent to calling `LoggedBookmarkStore(path, targetNumberOfSubscriptions, false)`.
LoggedBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions, boolean useLastModifiedTime) A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e.
LoggedBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions, boolean useLastModifiedTime, RecoveryPointAdapter adapter) A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e.
LoggedBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions, boolean useLastModifiedTime, RecoveryPointAdapter adapter, RecoveryPointFactory factory) A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e.

Method Summary

Modifier and Type	Method and Description
void	_purge() Removes all entries in the bookmark store and clears all records of messages received and discarded.
void	_purge(Field subId_) Removes all entries in the bookmark store associated with a specific subscription ID (subId_).
protected void	adapterUpdate(Field subId, BookmarkField bookmark) Used internally to update the RecoveryPointAdapter if there is one.
void	close() Closes the bookmark store.
void	discard(Field subId, long bookmarkSeqNo) Discards a bookmark entry associated with a specific subscription and bookmark sequence number.
void	discard(Message message) Discards a bookmark entry based on the information provided in the message.
protected LoggedBookmarkStore.Subscription	find(Field subId) Finds and returns the Subscription object for the specified subscription id (subId).
Field	getMostRecent(Field subId) Retrieves the most recent bookmark associated with a subscription identified by the given subId.
Field	getMostRecent(Field subId, boolean useList) Retrieves the most recent bookmark associated with a subscription identified by the given subId.
long	getOldestBookmarkSeq(Field subId) Retrieves the oldest bookmark sequence number associated with a subscription.
int	getServerVersion() Called by Client when connected to an AMPS server in order to retrieve the version number of the server.
boolean	isDiscarded(Message message) This method is called internally by the client to determine whether a message's bookmark received from the amps server has already been discarded OR already been delivered to the subscriber during this run.
long	log(Message message) This is a method the Client calls and is not for customer user.
void	persisted(Field subId, BookmarkField bookmark) This method is called by the client and it is used to process persisted acknowledgements that track a safe recovery point in the txlog.
void	persisted(Field subId, long bookmark) Deprecated. Use persisted(Field, BookmarkField) instead.
void	prune() Remove outdated entries in the bookmark store.
void	prune(java.lang.String tmpFileName_) Remove outdated entries in the bookmark store.
void	purge() Remove all entries in the bookmark store, completely clearing all record of messages received and discarded.
void	purge(Field subId_) Removes all entries in the bookmark store associated with a specific subscription ID (subId_).
void	setRecoveryPointFactory(RecoveryPointFactory factory_) Change the RecoveryPointFactory used by this store for its adapter.
void	setResizeHandler(BookmarkStoreResizeHandler handler) Sets a handler for bookmark store resize events.
void	setServerVersion(int version) Used to change the version of the AMPS server that this bookmark store's client has connected to.

Methods inherited from class java.lang.Object

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

Constructor Detail

LoggedBookmarkStore

public LoggedBookmarkStore(java.lang.String path)
                    throws java.io.IOException

This constructor is equivalent to calling `LoggedBookmarkStore(path, 1, false)`. Creates a new `LoggedBookmarkStore` instance with the specified path to the backing bookmark log file and default settings.

Parameters:

path - The path to the backing bookmark log file.

Throws:

java.io.IOException - If there is a problem creating, reading, or writing the backing file.

See Also:

LoggedBookmarkStore(String, int, boolean)

LoggedBookmarkStore

public LoggedBookmarkStore(java.lang.String path,
                           int targetNumberOfSubscriptions)
                    throws java.io.IOException

This constructor is equivalent to calling `LoggedBookmarkStore(path, targetNumberOfSubscriptions, false)`. Creates a new `LoggedBookmarkStore` instance with the specified path to the backing bookmark log file and an initial capacity for subscriptions.

Parameters:

path - The path to the backing bookmark log file.

targetNumberOfSubscriptions - The initial capacity for the number.

Throws:

java.io.IOException - If there is a problem creating, reading, or writing the backing file.

See Also:

LoggedBookmarkStore(String, int, boolean)

LoggedBookmarkStore

public LoggedBookmarkStore(java.lang.String path,
                           int targetNumberOfSubscriptions,
                           boolean useLastModifiedTime)
                    throws java.io.IOException

A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e. out-of-order discards) and fail-over to a replicated server. All messages must eventually be discarded, otherwise memory usage and disk space used will increase in proportion to the number of messages received on a bookmark subscription since the first undiscarded message. This implementation requires that the prune() method be called periodically to removed unneeded discarded bookmarks from the backing-file, otherwise it will continue to grow without bound. The prune() method is thread-safe and can be called from any thread.

Parameters:

path - The path to the backing bookmark log file.

targetNumberOfSubscriptions - The initial capacity for the number of bookmark subscriptions you anticipate creating on the AMPS client instance that this bookmark store is registered on. This will grow as needed if more subscriptions are created than anticipated.

useLastModifiedTime - Indicates whether the recovery timestamp feature should be used. If true, the last-modified time of the backing file is included (as an AMPS timestamp bookmark in a comma-separated list of bookmarks) when getMostRecent() is called after recovering from a bookmark file. This feature could be useful if you have an infrequently run process that is run on a schedule that is longer than the AMPS server keeps messages in its transaction log. When this process is started and recovers a bookmark log full of old bookmarks that are no longer available using the MOST_RECENT bookmark indicator, the recovery timestamp will cause the bookmark subscription to begin at the start of the transaction log (e.g. EPOCH), rather than its tail (e.g. NOW).

Throws:

java.io.IOException - If there is a problem creating, reading, or writing the backing file.

LoggedBookmarkStore

public LoggedBookmarkStore(java.lang.String path,
                           int targetNumberOfSubscriptions,
                           boolean useLastModifiedTime,
                           RecoveryPointAdapter adapter)
                    throws java.io.IOException

A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e. out-of-order discards) and fail-over to a replicated server. All messages must eventually be discarded, otherwise memory usage and disk space used will increase in proportion to the number of messages received on a bookmark subscription since the first undiscarded message. This implementation requires that the prune() method be called periodically to removed unneeded discarded bookmarks from the backing-file, otherwise it will continue to grow without bound. The prune() method is thread-safe and can be called from any thread. The store also has a backup RecoveryPointAdapter used in case the file is deleted.

Parameters:

path - The path to the backing bookmark log file.

targetNumberOfSubscriptions - The initial capacity for the number of bookmark subscriptions you anticipate creating on the AMPS client instance that this bookmark store is registered on. This will grow as needed if more subscriptions are created than anticipated.

useLastModifiedTime - Indicates whether the recovery timestamp feature should be used. If true, the last-modified time of the backing file is included (as an AMPS timestamp bookmark in a comma-separated list of bookmarks) when getMostRecent() is called after recovering from a bookmark file. This feature could be useful if you have an infrequently run process that is run on a schedule that is longer than the AMPS server keeps messages in its transaction log. When this process is started and recovers a bookmark log full of old bookmarks that are no longer available using the MOST_RECENT bookmark indicator, the recovery timestamp will cause the bookmark subscription to begin at the start of the transaction log (e.g. EPOCH), rather than its tail (e.g. NOW).

adapter - The RecoveryPointAdapter backing up the store. The adapter will be sent FixedRecoveryPoints.

Throws:

java.io.IOException - If there is a problem creating, reading, or writing the backing file.

LoggedBookmarkStore

public LoggedBookmarkStore(java.lang.String path,
                           int targetNumberOfSubscriptions,
                           boolean useLastModifiedTime,
                           RecoveryPointAdapter adapter,
                           RecoveryPointFactory factory)
                    throws java.io.IOException

A file-backed bookmark store implementation that fully supports discarding messages in an order different from the order they arrived (i.e. out-of-order discards) and fail-over to a replicated server. All messages must eventually be discarded, otherwise memory usage and disk space used will increase in proportion to the number of messages received on a bookmark subscription since the first undiscarded message. This implementation requires that the prune() method be called periodically to removed unneeded discarded bookmarks from the backing-file, otherwise it will continue to grow without bound. The prune() method is thread-safe and can be called from any thread. The store also has a backup RecoveryPointAdapter used in case the file is deleted.

Parameters:

path - The path to the backing bookmark log file.

targetNumberOfSubscriptions - The initial capacity for the number of bookmark subscriptions you anticipate creating on the AMPS client instance that this bookmark store is registered on. This will grow as needed if more subscriptions are created than anticipated.

useLastModifiedTime - Indicates whether the recovery timestamp feature should be used. If true, the last-modified time of the backing file is included (as an AMPS timestamp bookmark in a comma-separated list of bookmarks) when getMostRecent() is called after recovering from a bookmark file. This feature could be useful if you have an infrequently run process that is run on a schedule that is longer than the AMPS server keeps messages in its transaction log. When this process is started and recovers a bookmark log full of old bookmarks that are no longer available using the MOST_RECENT bookmark indicator, the recovery timestamp will cause the bookmark subscription to begin at the start of the transaction log (e.g. EPOCH), rather than its tail (e.g. NOW).

adapter - The RecoveryPointAdapter backing up the store.

factory - The RecoveryPointFactory used to create RecoveryPoints that are sent to the adapter.

Throws:

java.io.IOException - If there is a problem creating, reading, or writing the backing file.

Method Detail

prune

public void prune()
           throws java.io.IOException,
                  StoreException

Remove outdated entries in the bookmark store. This function creates a temporary file, copies current entries to that file, and then replaces the current file with the temporary file.

Throws:

java.io.IOException - Thrown when an operation on the file fails.

StoreException - Thrown when any other operation fails with details on the failure.

prune

public void prune(java.lang.String tmpFileName_)
           throws java.io.IOException,
                  StoreException

Remove outdated entries in the bookmark store. This function creates a temporary file, copies current entries to that file, and then replaces the current file with the temporary file.

Parameters:

tmpFileName_ - The name of the temporary file.

Throws:

java.io.IOException - Thrown when an operation on the file fails.

StoreException - Thrown when any other operation fails with details on the failure.

log

public long log(Message message)
         throws AMPSException

This is a method the Client calls and is not for customer user. Logs a message's bookmark to the bookmark store and updates the message's bookmark sequence number.

Specified by:

log in interface BookmarkStore

Parameters:

message - The message to log, containing the bookmark to be stored.

Returns:

The index at which the bookmark is stored in the subscription.

Throws:

AMPSException - If an error occurs while logging to the bookmark store.

discard

public void discard(Field subId,
                    long bookmarkSeqNo)
             throws AMPSException

Discards a bookmark entry associated with a specific subscription and bookmark sequence number.

Specified by:

discard in interface BookmarkStore

Parameters:

subId - The identifier of the subscription.

bookmarkSeqNo - The sequence number of the bookmark entry to discard.

Throws:

AMPSException - If an error occurs while discarding from the bookmark store.

discard

public void discard(Message message)
             throws AMPSException

Discards a bookmark entry based on the information provided in the message.

Specified by:

discard in interface BookmarkStore

Parameters:

message - The message containing information about the bookmark to discard.

Throws:

AMPSException - If an error occurs while discarding from the bookmark store.

getMostRecent

public Field getMostRecent(Field subId)
                    throws AMPSException

Retrieves the most recent bookmark associated with a subscription identified by the given subId.

Specified by:

getMostRecent in interface BookmarkStore

Parameters:

subId - The identifier of the subscription for which to retrieve the most recent bookmark.

Returns:

The most recent bookmark for the specified subscription.

Throws:

AMPSException - If an error occurs while retrieving the most recent bookmark or if the store is not open.

getMostRecent

public Field getMostRecent(Field subId,
                           boolean useList)
                    throws AMPSException

Retrieves the most recent bookmark associated with a subscription identified by the given subId.

Specified by:

getMostRecent in interface BookmarkStore

Parameters:

subId - The identifier of the subscription for which to retrieve the most recent bookmark.

useList - A flag indicating whether to retrieve the most recent bookmark list or a single bookmark.

Returns:

The most recent bookmark for the specified subscription.

Throws:

AMPSException - If an error occurs while retrieving the most recent bookmark or if the store is not open.

isDiscarded

public boolean isDiscarded(Message message)
                    throws AMPSException

This method is called internally by the client to determine whether a message's bookmark received from the amps server has already been discarded OR already been delivered to the subscriber during this run.

Specified by:

isDiscarded in interface BookmarkStore

Parameters:

message - The message containing the bookmark to check for discarding.

Returns:

True if the bookmark has been discarded; false otherwise.

Throws:

AMPSException - If an error occurs while checking if the bookmark is discarded or if the store is not open.

persisted

@Deprecated
public void persisted(Field subId,
                                  long bookmark)
                           throws AMPSException

Deprecated. Use persisted(Field, BookmarkField) instead.

Deprecated method for setting a persisted bookmark. Use persisted(Field, BookmarkField) instead.

Specified by:

persisted in interface BookmarkStore

Parameters:

subId - The identifier of the subscription for which to set the persisted bookmark.

bookmark - The persisted bookmark value to set.

Throws:

AMPSException - If an error occurs while setting the persisted bookmark or if the store is not open.

persisted

public void persisted(Field subId,
                      BookmarkField bookmark)
               throws AMPSException

This method is called by the client and it is used to process persisted acknowledgements that track a safe recovery point in the txlog. Sets a persisted bookmark for a subscription.

Specified by:

persisted in interface BookmarkStore

Parameters:

subId - The identifier of the subscription for which to set the persisted bookmark.

bookmark - The persisted bookmark value to set.

Throws:

AMPSException - If an error occurs while setting the persisted bookmark or if the store is not open.

getOldestBookmarkSeq

public long getOldestBookmarkSeq(Field subId)
                          throws AMPSException

Retrieves the oldest bookmark sequence number associated with a subscription.

Specified by:

getOldestBookmarkSeq in interface BookmarkStore

Parameters:

subId - The identifier of the subscription for which to retrieve the oldest bookmark sequence number.

Returns:

The oldest bookmark sequence number for the specified subscription.

Throws:

AMPSException - If an error occurs while retrieving the oldest bookmark sequence number or if the store is not open.

setResizeHandler

public void setResizeHandler(BookmarkStoreResizeHandler handler)

Sets a handler for bookmark store resize events.

Specified by:

setResizeHandler in interface BookmarkStore

Parameters:

handler - The handler to set for resize events.

find

protected LoggedBookmarkStore.Subscription find(Field subId)

Finds and returns the Subscription object for the specified subscription id (subId).

Parameters:

subId - The subId to find or create a Subscription for.

Returns:

The Subscription associated with the subId.

purge

public void purge()
           throws AMPSException

Remove all entries in the bookmark store, completely clearing all record of messages received and discarded. This should NOT be called on store that has active subscriptions or as there is a chance of creating an inconsistency between the file and the current state.

Specified by:

purge in interface BookmarkStore

Throws:

AMPSException - Thrown if the store is unable to remove the contents.

_purge

public void _purge()
            throws AMPSException

Removes all entries in the bookmark store and clears all records of messages received and discarded. This method is used to purge the entire bookmark store, effectively resetting it to an empty state. It acquires necessary locks to ensure safe access to shared resources.

Throws:

AMPSException - If an error occurs during the purging process.

purge

public void purge(Field subId_)
           throws AMPSException

Removes all entries in the bookmark store associated with a specific subscription ID (subId_). This method is used to clear messages received and discarded for a particular subscription. It also acquires necessary locks to ensure safe access to shared resources.

Specified by:

purge in interface BookmarkStore

Parameters:

subId_ - The subscription ID for which to remove entries from the store.

Throws:

AMPSException - If an error occurs during the purging process.

_purge

public void _purge(Field subId_)
            throws AMPSException

Removes all entries in the bookmark store associated with a specific subscription ID (subId_). This method is used to clear messages received and discarded for a particular subscription. It also acquires necessary locks to ensure safe access to shared resources.

Parameters:

subId_ - The subscription ID for which to remove entries from the store.

Throws:

AMPSException - If an error occurs during the purging process.

setRecoveryPointFactory

public void setRecoveryPointFactory(RecoveryPointFactory factory_)
                             throws AMPSException

Change the RecoveryPointFactory used by this store for its adapter.

Parameters:

factory_ - The new RecoveryPointFactory

Throws:

AMPSException - If one of factory or adapter is null.

close

public void close()
           throws AMPSException

Closes the bookmark store. If it is already closed, a StoreException is thrown.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

StoreException - If there is an error closing the file backing in the store, or the store already closed.

AMPSException

setServerVersion

public void setServerVersion(int version)

Used to change the version of the AMPS server that this bookmark store's client has connected to.

Specified by:

setServerVersion in interface BookmarkStore

Parameters:

version - An AMPS server version integer of the form 03080000 for version 3.8.0.0.

getServerVersion

public int getServerVersion()

Called by Client when connected to an AMPS server in order to retrieve the version number of the server. Returns retrieved version number.

Returns:

the server version, represented as an integer

adapterUpdate

protected void adapterUpdate(Field subId,
                             BookmarkField bookmark)
                      throws java.io.IOException

Used internally to update the RecoveryPointAdapter if there is one. This method is used for internal bookkeeping and communication with the RecoveryPointAdapter, which is responsible for handling recovery points associated with the bookmark store.

Parameters:

subId - The subId to update.

bookmark - The latest bookmark.

Throws:

java.io.IOException - If there is an exception from the adapter.