Defines the interface for bookmark stores, which are used by the AMPS.Client.Client to provide resumable subscriptions and client-side duplicate message handling. More...

Inheritance diagram for AMPS.Client.BookmarkStore:

Public Member Functions
long	log (Message mesage)
	Called internally by the AMPS Client to log a bookmark to the persistent log. More...

void	discard (Field subId, long bookmarkSeqNo)
	Log a discard-bookmark entry to the persistent log based on a bookmark sequence number. You can call this when you want to mark the message specified by the subscription ID and the bookmark sequence number as discarded, indicating that the application has completed processing the message. Marking a message as discarded means that the message will not be replayed when the subscription resumes. Recommended to use discard(Message) instead for better performance. It is more efficient because it operates directly on a message object, eliminating the need to specify a subscription ID and bookmark sequence number separately. More...

void	discard (Message message)
	You can call this when you want to mark the provided message as discarded, indicating that the application has completed processing the message. Marking a message as discarded means the message will not be replayed when the subscription resumes which helps in preventing redundant processing of messages. For optimum performance, it is critical to discard every message once its processing is complete. If a message is never discarded, it remains in the bookmark store. Log a discard-bookmark entry to the persistent log based on a Message. More...

Field	getMostRecent (Field subId, bool useList=true)
	You can call this when you want to return the correct recovery point for resubscription of the provided subID from the BookmarkStore. This is a single bookmark or (more often) a comma-delimited list of bookmarks. The useList parameter is a boolean flag. When set to true (which is the default), it affects how the recovery point is determined when the store hasn't received any persisted acknowledgments (acks). Specifically, if set to true, the method will build a list of bookmarks based on the last discarded message for each publisher. If set to false, it won't consider this additional information. This option can be useful when persisted acks are not available, allowing you to make more informed decisions about where to resume message processing. More...

bool	isDiscarded (Message message)
	Called internally by the AMPS Client. This method is called for each arriving message to determine if the application has already processed and discarded this message. This step is crucial to avoid processing the same message multiple times.Returns 'true' if the bookmark is in the log and marked as discarded and should therefore not be reprocessed.Otherwise, returns 'false' indicating that the message is new or hasn't been marked as discarded yet. Generally, isDiscarded is called by the AMPS Client however, there might be situations where the application needs to manually check if a message has been discarded.In such cases, the application can call this method to make that determination. More...

void	purge (Field subId)
	You can call this when you want to purge the contents of this store for a given subId. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well. NOTE: This should only be called when there are no ongoing or active subscriptions(i.e.before any subscribe or after all subscriptions are unsubscribed). Purging while subscriptions are active can disrupt those processes. More...

void	purge ()
	You can call this when you want to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well. NOTE: This should only be called when there are no ongoing or active subscriptions(i.e.before any subscribe or after all subscriptions are unsubscribed). Purging while subscriptions are active can disrupt those processes. More...

void	setResizeHandler (BookmarkStoreResizeHandler handler)
	You can call this when you want to set a resize handler that is invoked when the store needs to resize.This method allows you to set a custom function that gets called when a bookmark store needs to resize, giving you control and flexibility over how your application responds to this event. More...

long	getOldestBookmarkSeq (Field subId)
	You can call this when you want to retrieve the sequence number of the oldest bookmark in the store. More...

void	persisted (Field subId, BookmarkField bookmark)
	Called internally by the AMPS Client to record the last persisted message in the transaction log of the connected AMPS server to all of its sync replication destinations. More...

void	persisted (Field subId, long bookmarkSeqNo)
	Old style of setting a persisted bookmark no longer used. More...

void	setServerVersion (int version)
	Called internally by the AMPS Client when connected to an AMPS server to indicate what version the server is. A bookmark store can modify behavior based on the version of the server. More...

Detailed Description

Defines the interface for bookmark stores, which are used by the AMPS.Client.Client to provide resumable subscriptions and client-side duplicate message handling.

Member Function Documentation

◆ discard() [1/2]

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

Log a discard-bookmark entry to the persistent log based on a bookmark sequence number. You can call this when you want to mark the message specified by the subscription ID and the bookmark sequence number as discarded, indicating that the application has completed processing the message. Marking a message as discarded means that the message will not be replayed when the subscription resumes. Recommended to use discard(Message) instead for better performance. It is more efficient because it operates directly on a message object, eliminating the need to specify a subscription ID and bookmark sequence number separately.

Parameters

subId	The subscription ID of the bookmark.
bookmarkSeqNo	The bookmark sequence number.

Implemented in AMPS.Client.DefaultBookmarkStore, AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, and AMPS.Client.LoggedBookmarkStore.

◆ discard() [2/2]

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

You can call this when you want to mark the provided message as discarded, indicating that the application has completed processing the message. Marking a message as discarded means the message will not be replayed when the subscription resumes which helps in preventing redundant processing of messages. For optimum performance, it is critical to discard every message once its processing is complete. If a message is never discarded, it remains in the bookmark store. Log a discard-bookmark entry to the persistent log based on a Message.

Parameters

message Message to be marked as discarded.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ getMostRecent()

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

You can call this when you want to return the correct recovery point for resubscription of the provided subID from the BookmarkStore. This is a single bookmark or (more often) a comma-delimited list of bookmarks. The useList parameter is a boolean flag. When set to true (which is the default), it affects how the recovery point is determined when the store hasn't received any persisted acknowledgments (acks). Specifically, if set to true, the method will build a list of bookmarks based on the last discarded message for each publisher. If set to false, it won't consider this additional information. This option can be useful when persisted acks are not available, allowing you to make more informed decisions about where to resume message processing.

Parameters

subId	The subscription ID of the most recent bookmark.
useList	In the case where the store has not received any persisted acks, it will build a list of bookmarks based on the last discarded for each publisher if true (default).

Returns: Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

Implemented in AMPS.Client.DefaultBookmarkStore, AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, and AMPS.Client.LoggedBookmarkStore.

◆ getOldestBookmarkSeq()

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

You can call this when you want to retrieve the sequence number of the oldest bookmark in the store.

Parameters

subId The subscription ID for the oldest bookmark in the store.

Returns: The internal sequence number of the oldest bookmark in the store.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ isDiscarded()

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

Called internally by the AMPS Client. This method is called for each arriving message to determine if the application has already processed and discarded this message. This step is crucial to avoid processing the same message multiple times.Returns 'true' if the bookmark is in the log and marked as discarded and should therefore not be reprocessed.Otherwise, returns 'false' indicating that the message is new or hasn't been marked as discarded yet. Generally, isDiscarded is called by the AMPS Client however, there might be situations where the application needs to manually check if a message has been discarded.In such cases, the application can call this method to make that determination.

Parameters

message Incoming message used to determine if the application has already processed and discarded the message.

Returns: Whether the message is already in the store and marked as discarded.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ log()

long AMPS.Client.BookmarkStore.log ( Message mesage )

Called internally by the AMPS Client to log a bookmark to the persistent log.

Parameters

mesage The message containing the bookmark to log.

Returns: The corresponding bookmark sequence number for thisbookmark.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ persisted() [1/2]

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

Called internally by the AMPS Client to record the last persisted message in the transaction log of the connected AMPS server to all of its sync replication destinations.

Parameters

subId	The subscription ID for the message.
bookmark	The bookmark containing the message.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ persisted() [2/2]

void AMPS.Client.BookmarkStore.persisted	(	Field	subId,
		long	bookmarkSeqNo
	)

Old style of setting a persisted bookmark no longer used.

Parameters

subId	The subscription ID for the message.
bookmarkSeqNo	The bookmark sequence number.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ purge() [1/2]

void AMPS.Client.BookmarkStore.purge ( )

You can call this when you want to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well. NOTE: This should only be called when there are no ongoing or active subscriptions(i.e.before any subscribe or after all subscriptions are unsubscribed). Purging while subscriptions are active can disrupt those processes.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ purge() [2/2]

void AMPS.Client.BookmarkStore.purge ( Field subId )

You can call this when you want to purge the contents of this store for a given subId. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well. NOTE: This should only be called when there are no ongoing or active subscriptions(i.e.before any subscribe or after all subscriptions are unsubscribed). Purging while subscriptions are active can disrupt those processes.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ setResizeHandler()

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

You can call this when you want to set a resize handler that is invoked when the store needs to resize.This method allows you to set a custom function that gets called when a bookmark store needs to resize, giving you control and flexibility over how your application responds to this event.

Parameters

handler The handler to invoke for the resize.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

◆ setServerVersion()

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

Called internally by the AMPS Client when connected to an AMPS server to indicate what version the server is. A bookmark store can modify behavior based on the version of the server.

Parameters

version The version of the AMPS server.

Implemented in AMPS.Client.RingBookmarkStore, AMPS.Client.MemoryBookmarkStore, AMPS.Client.LoggedBookmarkStore, and AMPS.Client.DefaultBookmarkStore.

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

AMPS.Client/BookmarkStore.cs

Public Member Functions

Detailed Description

Member Function Documentation

◆ discard() [1/2]

◆ discard() [2/2]

◆ getMostRecent()

◆ getOldestBookmarkSeq()

◆ isDiscarded()

◆ log()

◆ persisted() [1/2]

◆ persisted() [2/2]

◆ purge() [1/2]

◆ purge() [2/2]

◆ setResizeHandler()

◆ setServerVersion()