LoggedBookmarkStore (AMPS Java Client (5.3.2.1.6d15937f.540279))

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.

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)` Same as calling LoggedBookmarkStore(path, 1, false).
`LoggedBookmarkStore(java.lang.String path, int targetNumberOfSubscriptions)` Same as 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

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`_purge()`
`void`	`_purge(Field subId_)`
`protected void`	`adapterUpdate(Field subId, BookmarkField bookmark)` Used inernally to update the RecoveryPointAdapter if there is one.
`void`	`close()` Closes the bookmark store.
`void`	`discard(Field subId, long bookmarkSeqNo)` 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.
`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 LoggedBookmarkStore.Subscription`	`find(Field subId)` Finds and returns the Subscription object for the specified subscription id (subId).
`Field`	`getMostRecent(Field subId)` Call this when you want to return the correct recovery point for resubscription of the provided subID from the BookmarkStore.
`Field`	`getMostRecent(Field subId, boolean useList)` Call this when you want to return the correct recovery point for resubscription of the provided subID from the BookmarkStore.
`long`	`getOldestBookmarkSeq(Field subId)` Call this when you want to retrieve the sequence number of the oldest bookmark in the store.
`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)` Called for each arriving message to determine if the application has already processed and discarded this message.
`long`	`log(Message message)` Called internally by the Client to log a bookmark to the persistent log.
`void`	`persisted(Field subId, BookmarkField bookmark)` Called internally by the Client to record the last persisted message in the transaction log of the connected AMPS server to all of its sync replication destinations.
`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_)` Remove all entries in the bookmark store for a subId.
`void`	`setRecoveryPointFactory(RecoveryPointFactory factory_)` Change the RecoveryPointFactory used by this store for its adapter.
`void`	`setResizeHandler(BookmarkStoreResizeHandler handler)` Called this when you want to set a resize handler that is invoked when the store needs to resize.
`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
```
    Same as calling LoggedBookmarkStore(path, 1, false).
    
    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
```
    Same as calling LoggedBookmarkStore(path, targetNumberOfSubscriptions, false).
    
    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 will become proportional 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 will become proportional 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 will become proportional 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 craete 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
```
    Description copied from interface: BookmarkStore
    
    Called internally by the Client to log a bookmark to the persistent log.
    
    Specified by:
    
    log in interface BookmarkStore
    
    Parameters:
    
    message - The message containing the bookmark to log.
    
    Returns:
    
    the corresponding bookmark sequence number for this bookmark.
    
    Throws:
    
    AMPSException - Thrown when the message cannot be logged.
  - discard
```
public void discard(Field subId,
                    long bookmarkSeqNo)
             throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    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 performance.
    
    Specified by:
    
    discard in interface BookmarkStore
    
    Parameters:
    
    subId - The subscription ID of the bookmark.
    
    bookmarkSeqNo - The bookmark sequence number.
    
    Throws:
    
    AMPSException - Thrown when the specified bookmark cannot be discareded.
  - discard
```
public void discard(Message message)
             throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    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 the specified message cannot be discareded.
  - getMostRecent
```
public Field getMostRecent(Field subId)
                    throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    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.
    
    Specified by:
    
    getMostRecent in interface BookmarkStore
    
    Parameters:
    
    subId - The subscription ID of the most recent bookmark.
    
    Returns:
    
    A Field containing the correct recovery point to use for resubscriptions.
    
    Throws:
    
    AMPSException - Thrown when the store cannot produce a recovery point for the specified subID.
  - getMostRecent
```
public Field getMostRecent(Field subId,
                           boolean useList)
                    throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    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.
    
    Specified by:
    
    getMostRecent in interface BookmarkStore
    
    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:
    
    A Field containing the correct recovery point to use for resubscriptions.
    
    Throws:
    
    AMPSException - Thrown when the store cannot produce a recovery point for the specified subID.
  - isDiscarded
```
public boolean isDiscarded(Message message)
                    throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    Called for each arriving message to determine if the application has already processed and discarded this message. Returns 'true' if the bookmark is in the log and marked as discarded and should therefore not be reprocessed. Otherwise, returns 'false'. 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 processed and discarded the message.
    
    Returns:
    
    Whether the message is already in the store and marked as discarded.
    
    Throws:
    
    AMPSException - Thrown when the store cannot determine if the message is discarded.
  - 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.
    
    Specified by:
    
    persisted in interface BookmarkStore
    
    Parameters:
    
    subId - The subscription ID for the message.
    
    bookmark - The bookmark sequence number.
    
    Throws:
    
    AMPSException - Thrown if the store is unable to record information in the store.
  - persisted
```
public void persisted(Field subId,
                      BookmarkField bookmark)
               throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    Called internally by the Client to record the last persisted message in the transaction log of the connected AMPS server to all of its sync replication destinations.
    
    Specified by:
    
    persisted in interface BookmarkStore
    
    Parameters:
    
    subId - The subscription ID for the message.
    
    bookmark - The bookmark containing the message.
    
    Throws:
    
    AMPSException - Thrown if the store is unable to record information in the store.
  - getOldestBookmarkSeq
```
public long getOldestBookmarkSeq(Field subId)
                          throws AMPSException
```
    Description copied from interface: BookmarkStore
    
    Call this when you want to retrieve the sequence number of 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:
    
    The internal sequence number of the oldest bookmark in the store.
    
    Throws:
    
    AMPSException - The operation could not successfully be completed.
  - setResizeHandler
```
public void setResizeHandler(BookmarkStoreResizeHandler handler)
```
    Description copied from interface: BookmarkStore
    
    Called 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.
  - find
```
protected LoggedBookmarkStore.Subscription find(Field subId)
                                         throws java.io.IOException
```
    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.
    
    Throws:
    
    java.io.IOException - For legacy reasons.
  - purge
```
public void purge()
           throws AMPSException
```
    Remove all entries in the bookmark store, completely clearing all record of messages received and discarded.
    
    Specified by:
    
    purge in interface BookmarkStore
    
    Throws:
    
    AMPSException - Thrown if the store is unable to remove the contents.
  - _purge
```
public void _purge()
            throws AMPSException
```
    Throws:
    
    AMPSException
  - purge
```
public void purge(Field subId_)
           throws AMPSException
```
    Remove all entries in the bookmark store for a subId.
    
    Specified by:
    
    purge in interface BookmarkStore
    
    Parameters:
    
    subId_ - The subId to remove from the store.
    
    Throws:
    
    AMPSException - Thrown if the store is unable to remove information for the subscription.
  - _purge
```
public void _purge(Field subId_)
            throws AMPSException
```
    Throws:
    
    AMPSException
  - 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 inernally to update the RecoveryPointAdapter if there is one.
    
    Parameters:
    
    subId - The subId to update.
    
    bookmark - The latest bookmark.
    
    Throws:
    
    java.io.IOException - If there is an exception from the adapter.

Class LoggedBookmarkStore

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LoggedBookmarkStore

LoggedBookmarkStore

LoggedBookmarkStore

LoggedBookmarkStore

LoggedBookmarkStore

Method Detail

prune

prune

log

discard

discard

getMostRecent

getMostRecent

isDiscarded

persisted

persisted

getOldestBookmarkSeq

setResizeHandler

find

purge

_purge

purge

_purge

setRecoveryPointFactory

close

setServerVersion

getServerVersion

adapterUpdate