LoggedBookmarkStore implements a sequentially written log of incoming and discarded messages. The store tracks every bookmark processed in a file. An application should periodically call AMPS.Client.LoggedBookmarkStore.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 fall and resume. If your application does not require this fall-and-resume functionality, it is recommended to use a MemoryBookmarkStore. More...

Inheritance diagram for AMPS.Client.LoggedBookmarkStore:

Public Member Functions
	LoggedBookmarkStore (string path)
	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. More...

	LoggedBookmarkStore (string path, int targetNumberOfSubscriptions)
	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. More...

	LoggedBookmarkStore (string path, bool useLastModifiedTime)
	Creates a new `LoggedBookmarkStore` instance with the specified path to the backing bookmark log file and a flag indicating whether to use the last modified time. More...

	LoggedBookmarkStore (string path, RecoveryPointAdapter adapter_, RecoveryPointFactory factory_=null)
	Creates a new `LoggedBookmarkStore` instance with the specified path to the backing bookmark log file, a recovery point adapter, and an optional recovery point factory. This constructor is equivalent to calling `LoggedBookmarkStore(path, 1, false, adapter_, factory_)`. More...

	LoggedBookmarkStore (string path, int targetNumberOfSubscriptions, RecoveryPointAdapter adapter_, RecoveryPointFactory factory_=null)
	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. More...

	LoggedBookmarkStore (string path, int targetNumberOfSubscriptions, bool useLastModifiedTime)
	Constructor for the `LoggedBookmarkStore` class with additional parameters for file-related settings. More...

	LoggedBookmarkStore (string path, int targetNumberOfSubscriptions, bool useLastModifiedTime, RecoveryPointAdapter adapter_, RecoveryPointFactory factory_=null)
	Constructor for the `LoggedBookmarkStore` class with additional parameters for file-related settings. More...

void	prune ()
	Remove outdated entries in the bookmark file. This function creates a temporary file, writes active entries to that file, and then replaces the current file with the temporary file. Called on a LoggedBookmarkStore to keep the file from growing too large; see the Developer Guide for advice on stratgies for when to call this function. If this function is not called, the file can grow indefinitely until it's too large and causes an exception. More...

void	prune (String tmpFileName_)
	Remove outdated entries in the bookmark file. This function creates a temporary file, tmpFileName_, writes active entries to that file, and then replaces the current file with the temporary file. Called on a LoggedBookmarkStore to keep the file from growing too large; see the Developer Guide for advice on stratgies for when to call this function. If this function is not called, the file can grow indefinitely until it's too large and causes an exception. More...

void	_prune (String tmpFileName_)

long	log (Message message)
	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. More...

void	discard (Field subId, long bookmarkSeqNo)
	Discards a bookmark entry associated with a specific subscription and bookmark sequence number. Calling discard with the Message can be faster. More...

void	discard (Message message)
	Discards a bookmark entry based on the information provided in the message. More...

Field	getMostRecent (Field subId, bool useList=true)
	Retrieves the most recent bookmark associated with a subscription identified by the given subId. More...

bool	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. More...

void	persisted (Field subId, long bookmark)
	Deprecated method for setting a persisted bookmark. Use AMPS.Client.LoggedBookmarkStore.persisted(Field, BookmarkField) instead. More...

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. Sets a persisted bookmark for a subscription. More...

long	getOldestBookmarkSeq (Field subId)
	Retrieves the oldest active bookmark sequence number that is not discarded for the given subscription. More...

void	setResizeHandler (BookmarkStoreResizeHandler handler)
	Sets a handler for bookmark store resize events. More...

void	purge ()
	Purges the entire bookmark store, removing all entries. This method truncates the file and all information about any subscriptions is removed. This should not be called if the store is still attached to a connected Client with any active subscriptions. More...

void	purge (Field subId_)
	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. This should not be called if the store is still attached to a connected Client where this subId is still active. This does not reduce the underlying file size. More...

void	setRecoveryPointFactory (RecoveryPointFactory factory_)
	Change the RecoveryPointFactory used by this store for its adapter. More...

void	Dispose ()
	Disposes of the bookmark store resources, including the adapter and file stream. More...

void	close ()
	Closes the bookmark store by disposing of the adapter and file stream. Any IOException during the close operation is caught and rethrown as a StoreException. More...

void	setServerVersion (int version)
	Used internally to change the version of the AMPS server that this bookmark store's client has connected to. More...

int	getServerVersion ()
	Return the server version that was set by the Client. More...

Detailed Description

LoggedBookmarkStore implements a sequentially written log of incoming and discarded messages. The store tracks every bookmark processed in a file. An application should periodically call AMPS.Client.LoggedBookmarkStore.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 fall and resume. If your application does not require this fall-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.

Constructor & Destructor Documentation

◆ LoggedBookmarkStore() [1/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore ( string path )

inline

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.

◆ LoggedBookmarkStore() [2/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		int	targetNumberOfSubscriptions
	)

inline

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 excpected number of subscriptions.

◆ LoggedBookmarkStore() [3/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		bool	useLastModifiedTime
	)

inline

Creates a new LoggedBookmarkStore instance with the specified path to the backing bookmark log file and a flag indicating whether to use the last modified time.

Parameters

path	The path to the backing bookmark log file.
useLastModifiedTime	A flag indicating whether to use the last modified time of the file for the recovery timestamp.

◆ LoggedBookmarkStore() [4/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		RecoveryPointAdapter	adapter_,
		RecoveryPointFactory	factory_ = `null`
	)

inline

Creates a new LoggedBookmarkStore instance with the specified path to the backing bookmark log file, a recovery point adapter, and an optional recovery point factory. This constructor is equivalent to calling LoggedBookmarkStore(path, 1, false, adapter_, factory_).

Parameters

path	The path to the backing bookmark log file.
adapter_	The recovery point adapter used in case the file is deleted.
factory_	Optional: The recovery point factory. If not provided, a default factory is used.

◆ LoggedBookmarkStore() [5/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		int	targetNumberOfSubscriptions,
		RecoveryPointAdapter	adapter_,
		RecoveryPointFactory	factory_ = `null`
	)

inline

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.
adapter_	The recovery point adapter used in case the file is deleted.
factory_	Optional: The recovery point factory. If not provided, a default factory is used.

◆ LoggedBookmarkStore() [6/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		int	targetNumberOfSubscriptions,
		bool	useLastModifiedTime
	)

inline

Constructor for the LoggedBookmarkStore class with additional parameters for file-related settings.

Parameters

path	The path to the backing bookmark log file.
targetNumberOfSubscriptions	The initial capacity for the number of bookmark subscriptions anticipated on the AMPS client instance. It grows as needed if more subscriptions are created than anticipated.
useLastModifiedTime	A flag indicating whether to use the last modified time of the file for recovery timestamp.

◆ LoggedBookmarkStore() [7/7]

AMPS.Client.LoggedBookmarkStore.LoggedBookmarkStore	(	string	path,
		int	targetNumberOfSubscriptions,
		bool	useLastModifiedTime,
		RecoveryPointAdapter	adapter_,
		RecoveryPointFactory	factory_ = `null`
	)

inline

Constructor for the LoggedBookmarkStore class with additional parameters for file-related settings.

Parameters

path	The path to the backing bookmark log file.
targetNumberOfSubscriptions	The initial capacity for the number of bookmark subscriptions anticipated on the AMPS client instance. It grows as needed if more subscriptions are created than anticipated.
useLastModifiedTime	A flag indicating whether to use the last modified time of the file for recovery timestamp.
adapter_	The recovery point adapter used in case the file is deleted.
factory_	Optional: The recovery point factory. If not provided, a default factory is used.

Member Function Documentation

◆ close()

void AMPS.Client.LoggedBookmarkStore.close ( )

inline

Closes the bookmark store by disposing of the adapter and file stream. Any IOException during the close operation is caught and rethrown as a StoreException.

Exceptions

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

◆ discard() [1/2]

void AMPS.Client.LoggedBookmarkStore.discard	(	Field	subId,
		long	bookmarkSeqNo
	)

inline

Discards a bookmark entry associated with a specific subscription and bookmark sequence number. Calling discard with the Message can be faster.

Parameters

subId	The identifier of the subscription.
bookmarkSeqNo	The sequence number of the bookmark entry to discard.

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ discard() [2/2]

void AMPS.Client.LoggedBookmarkStore.discard ( Message message )

inline

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

Parameters

message The message containing information about the bookmark to discard.

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ Dispose()

void AMPS.Client.LoggedBookmarkStore.Dispose ( )

inline

Disposes of the bookmark store resources, including the adapter and file stream.

◆ getMostRecent()

Field AMPS.Client.LoggedBookmarkStore.getMostRecent	(	Field	subId,
		bool	useList = `true`
	)

inline

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

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 as a list or just the single bookmark that was last discarded. A list is the only way to guarantee successful failover and no missed message.

Returns: The most recent bookmark for the specified subscription.

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ getOldestBookmarkSeq()

long AMPS.Client.LoggedBookmarkStore.getOldestBookmarkSeq ( Field subId )

inline

Retrieves the oldest active bookmark sequence number that is not discarded for the given subscription.

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.

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ getServerVersion()

int AMPS.Client.LoggedBookmarkStore.getServerVersion ( )

inline

Return the server version that was set by the Client.

Returns: The server version, represented as an integer

◆ isDiscarded()

bool AMPS.Client.LoggedBookmarkStore.isDiscarded ( Message message )

inline

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.

Parameters

message The message containing the bookmark to check for discarding.

Returns: True if the bookmark has been discarded; false otherwise.

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ log()

long AMPS.Client.LoggedBookmarkStore.log ( Message message )

inline

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.

Parameters

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

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

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ persisted() [1/2]

void AMPS.Client.LoggedBookmarkStore.persisted	(	Field	subId,
		BookmarkField	bookmark
	)

inline

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.

Parameters

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

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ persisted() [2/2]

void AMPS.Client.LoggedBookmarkStore.persisted	(	Field	subId,
		long	bookmark
	)

inline

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

Parameters

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

Exceptions

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

Implements AMPS.Client.BookmarkStore.

◆ prune() [1/2]

void AMPS.Client.LoggedBookmarkStore.prune ( )

inline

Remove outdated entries in the bookmark file. This function creates a temporary file, writes active entries to that file, and then replaces the current file with the temporary file. Called on a LoggedBookmarkStore to keep the file from growing too large; see the Developer Guide for advice on stratgies for when to call this function. If this function is not called, the file can grow indefinitely until it's too large and causes an exception.

◆ prune() [2/2]

void AMPS.Client.LoggedBookmarkStore.prune ( String tmpFileName_ )

inline

Remove outdated entries in the bookmark file. This function creates a temporary file, tmpFileName_, writes active entries to that file, and then replaces the current file with the temporary file. Called on a LoggedBookmarkStore to keep the file from growing too large; see the Developer Guide for advice on stratgies for when to call this function. If this function is not called, the file can grow indefinitely until it's too large and causes an exception.

Parameters

tmpFileName_ The name of the temporary file.

◆ purge() [1/2]

void AMPS.Client.LoggedBookmarkStore.purge ( )

inline

Purges the entire bookmark store, removing all entries. This method truncates the file and all information about any subscriptions is removed. This should not be called if the store is still attached to a connected Client with any active subscriptions.

Implements AMPS.Client.BookmarkStore.

◆ purge() [2/2]

void AMPS.Client.LoggedBookmarkStore.purge ( Field subId_ )

inline

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. This should not be called if the store is still attached to a connected Client where this subId is still active. This does not reduce the underlying file size.

Parameters

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

Implements AMPS.Client.BookmarkStore.

◆ setRecoveryPointFactory()

void AMPS.Client.LoggedBookmarkStore.setRecoveryPointFactory ( RecoveryPointFactory factory_ )

inline

Change the RecoveryPointFactory used by this store for its adapter.

Parameters

factory_ The new RecoveryPointFactory.

Exceptions

AMPSException If one of factory or adapter is null.

◆ setResizeHandler()

void AMPS.Client.LoggedBookmarkStore.setResizeHandler ( BookmarkStoreResizeHandler handler )

inline

Sets a handler for bookmark store resize events.

Parameters

handler The BookmarkStoreResizeHandler to set.

Implements AMPS.Client.BookmarkStore.

◆ setServerVersion()

void AMPS.Client.LoggedBookmarkStore.setServerVersion ( int version )

inline

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

Parameters

version An AMPS server version integer of the form 05030400 for version 5.3.4.0.

Implements AMPS.Client.BookmarkStore.

The documentation for this class was generated from the following file:

AMPS.Client/LoggedBookmarkStore.cs

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LoggedBookmarkStore() [1/7]

◆ LoggedBookmarkStore() [2/7]

◆ LoggedBookmarkStore() [3/7]

◆ LoggedBookmarkStore() [4/7]

◆ LoggedBookmarkStore() [5/7]

◆ LoggedBookmarkStore() [6/7]

◆ LoggedBookmarkStore() [7/7]

Member Function Documentation

◆ close()

◆ discard() [1/2]

◆ discard() [2/2]

◆ Dispose()

◆ getMostRecent()

◆ getOldestBookmarkSeq()

◆ getServerVersion()

◆ isDiscarded()

◆ log()

◆ persisted() [1/2]

◆ persisted() [2/2]

◆ prune() [1/2]

◆ prune() [2/2]

◆ purge() [1/2]

◆ purge() [2/2]

◆ setRecoveryPointFactory()

◆ setResizeHandler()

◆ setServerVersion()