com.crankuptheamps.client

Class RingBookmarkStore

java.lang.Object

com.crankuptheamps.client.RingBookmarkStore

All Implemented Interfaces:

BookmarkStore, java.lang.AutoCloseable

public class RingBookmarkStore
extends java.lang.Object
implements BookmarkStore

RingBookmarkStore is an implementation of BookmarkStore that stores state on disk and in memory. This BookmarkStore implementation is designed for use when messages will be strictly discarded in the order in which they are received. Discarding messages out of order may result in duplicate or missed messages on failover. For stores that support out of order discard, see (links) LoggedBookmarkStore or MemoryBookmarkStore. ( For each subscription, RingBookmarkStore keeps the most recent bookmark B for which all messages prior to B have been discard()ed by the subscriber. As messages are logged and discarded, an in-memory array is used to track when a new bookmark can be logged.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	RingBookmarkStore.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
RingBookmarkStore(java.lang.String path) Initializes a `RingBookmarkStore` object with the provided file path.
RingBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions) Initializes a `RingBookmarkStore` object with a specified file path and a target number of subscriptions.

Method Summary

Modifier and Type	Method and Description
void	close() In order to unmap the memory used to store the state, this method closes the mapped byte buffer.
void	discard(Field subId, long bookmarkSeqNo) Marks the message specified by the Subscription ID and bookmark sequence number as discarded, indicating that the application has completed processing the message.
void	discard(Message message) Call this when you want to mark the provided message as discarded, indicating that the application has completed processing the message.
protected RingBookmarkStore.Subscription	find(Field subId) Finds and returns the `Subscription` object associated with the specified subscription ID (`subId`).
Field	getMostRecent(Field subId) Call this when you want to return to the most recent bookmark from the log that should be used for (re-)subscriptions based on the provided subscription ID.
Field	getMostRecent(Field subId, boolean useList) Call this when you want to return to the most recent bookmark from the log that should be used for (re-)subscriptions based on the provided subscription ID.
long	getOldestBookmarkSeq(Field subId) Call this when you want to retrieve the sequence number for the oldest bookmark in the store.
int	getServerVersion() Called internally by the Client to return the server version detected upon logon.
boolean	isDiscarded(Message message) Called for each arriving message to determine if the application has already processed and discarded the message.
long	log(Message message) This method is called internally by the AMPS Client to log a bookmark to the persistent log.
void	persisted(Field subId, BookmarkField bookmark) Called internally by the Client to mark the message as safely persisted by AMPS to all of its sync replication destinations.
void	persisted(Field subId, long bookmark) Deprecated. use persisted(Field, BookmarkField) instead.
void	purge() Call this when you want to purge the contents of this store.
void	purge(Field subId_) Call this when you want to purge the contents of this store for a given Subscription Id.
void	setResizeHandler(BookmarkStoreResizeHandler handler) Call this when you want to set a resize handler that is invoked when the store needs to resize.
void	setServerVersion(int version) Called internally by the Client when connected to an AMPS server to indicate what version the server is.

Methods inherited from class java.lang.Object

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

Constructor Detail

RingBookmarkStore

public RingBookmarkStore(java.lang.String path)
                  throws AMPSException

Initializes a `RingBookmarkStore` object with the provided file path. It internally calls another constructor with a default target number of subscriptions (`targetNumberOfSubscriptions` set to 1).

Parameters:

path - The path to the file.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

RingBookmarkStore

public RingBookmarkStore(java.lang.String path,
                         int targetNumberOfSubscriptions)
                  throws AMPSException

Initializes a `RingBookmarkStore` object with a specified file path and a target number of subscriptions. It creates a random access file, initializes the subscription pool (`_pool`), and calls the `init()` method to set up the object. If any I/O errors occur during initialization, an `AMPSException` is thrown with details of the error.

Parameters:

path - The path to the file.

targetNumberOfSubscriptions - The target number of subscriptions.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

Method Detail

log

public long log(Message message)
         throws AMPSException

This method is called internally by the AMPS Client to log a bookmark to the persistent log. It takes an `AMPS Message` as an argument and returns a bookmark to be logged. If a subscription is not associated with the message, it attempts to find or create one using the message's subscription ID. The method logs the bookmark and assigns a sequence number to it. If any operation on the store fails, it throws an `AMPSException` with details of the failure.

Specified by:

log in interface BookmarkStore

Parameters:

message - The AMPS Message.

Returns:

Returns bookmark to be logged.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

discard

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

Marks the message specified by the Subscription ID and 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. This method is intended for internal use by the AMPS Client to manage message processing. Application code typically does not need to call this method directly.

Specified by:

discard in interface BookmarkStore

Parameters:

subId - The subscription ID of the message.

bookmarkSeqNo - The bookmark sequence number.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

discard

public void discard(Message message)
             throws AMPSException

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 that the message will not be replayed when the subscription resumes.

Specified by:

discard in interface BookmarkStore

Parameters:

message - Message to be marked as discarded.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

getMostRecent

public Field getMostRecent(Field subId)
                    throws AMPSException

Call this when you want to return to the most recent bookmark from the log that should be used for (re-)subscriptions based on the provided subscription ID.

Specified by:

getMostRecent in interface BookmarkStore

Parameters:

subId - Subscription Id

Returns:

Returns most recent bookmark.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

getMostRecent

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

Call this when you want to return to the most recent bookmark from the log that should be used for (re-)subscriptions based on the provided subscription ID.

Specified by:

getMostRecent in interface BookmarkStore

Parameters:

subId - Subscription Id

useList - Ignored by this type of store.

Returns:

Returns most recent bookmark.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

isDiscarded

public boolean isDiscarded(Message message)
                    throws AMPSException

Called for each arriving message to determine if the application has already processed and discarded the message. Generally isDiscarded is called by the Client however, if needed it can be called by the application as well.

Specified by:

isDiscarded in interface BookmarkStore

Parameters:

message - Message used to determine if the application has already

Returns:

Returns 'true' if the bookmark is in the log and marked as discarded. Otherwise, returns 'false'.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

find

protected RingBookmarkStore.Subscription find(Field subId)
                                       throws AMPSException

Finds and returns the `Subscription` object associated with the specified subscription ID (`subId`). If the `subId` exists in the store, it returns the existing `Subscription` object. If the `subId` is not found, it checks if there is space available to create a new `Subscription` object and adds it to the store.

Parameters:

subId - The subscription ID for which to find or create a Subscription.

Returns:

The Subscription associated with the specified subId.

Throws:

AMPSException - Thrown when there is an error in the bookmark store or when there is insufficient space to create a new Subscription.

persisted

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

Called internally by the Client to mark the message as safely persisted by AMPS to all of its sync replication destinations. On this store, this method has no effect.

Specified by:

persisted in interface BookmarkStore

Parameters:

subId - The subscription ID for the message.

bookmark - The bookmark containing the message.

Throws:

AMPSException - Not thrown by this implementation.

persisted

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

Deprecated. use persisted(Field, BookmarkField) instead.

Old style of setting a persisted bookmark no longer used. destinations. On this store, this method has no effect.

Specified by:

persisted in interface BookmarkStore

Parameters:

subId - The subscription ID for the message.

bookmark - The bookmark number.

Throws:

AMPSException - Not thrown by this implementation.

getOldestBookmarkSeq

public long getOldestBookmarkSeq(Field subId)
                          throws AMPSException

Call this when you want to retrieve the sequence number for the oldest bookmark in the store.

Specified by:

getOldestBookmarkSeq in interface BookmarkStore

Parameters:

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

Returns:

Returns the oldest bookmark sequence number in the store.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

setResizeHandler

public void setResizeHandler(BookmarkStoreResizeHandler handler)

Call this when you want to set a resize handler that is invoked when the store needs to resize.

Specified by:

setResizeHandler in interface BookmarkStore

Parameters:

handler - The handler to invoke for the resize.

purge

public void purge()
           throws AMPSException

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.

Specified by:

purge in interface BookmarkStore

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

purge

public void purge(Field subId_)
           throws AMPSException

Call this when you want to purge the contents of this store for a given Subscription Id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

Specified by:

purge in interface BookmarkStore

Parameters:

subId_ - The identifier of the subscription to purge.

Throws:

AMPSException - Thrown when an operation on the store fails. The exception will contain details of the failure.

setServerVersion

public void setServerVersion(int version)

Called internally by the Client when connected to an AMPS server to indicate what version the server is.

Specified by:

setServerVersion in interface BookmarkStore

Parameters:

version - Version number

getServerVersion

public int getServerVersion()

Called internally by the Client to return the server version detected upon logon.

Returns:

The server version.

close

public void close()
           throws java.lang.Exception

In order to unmap the memory used to store the state, this method closes the mapped byte buffer.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception - Thrown when an operation on the store fails. The exception will contain details of the failure.