com.crankuptheamps.client.BookmarkStore Maven / Gradle / Ivy
////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2010-2020 60East Technologies Inc., All Rights Reserved.
//
// This computer software is owned by 60East Technologies Inc. and is
// protected by U.S. copyright laws and other laws and by international
// treaties. This computer software is furnished by 60East Technologies
// Inc. pursuant to a written license agreement and may be used, copied,
// transmitted, and stored only in accordance with the terms of such
// license agreement and with the inclusion of the above copyright notice.
// This computer software or any other copies thereof may not be provided
// or otherwise made available to any other person.
//
// U.S. Government Restricted Rights. This computer software: (a) was
// developed at private expense and is in all respects the proprietary
// information of 60East Technologies Inc.; (b) was not developed with
// government funds; (c) is a trade secret of 60East Technologies Inc.
// for all purposes of the Freedom of Information Act; and (d) is a
// commercial item and thus, pursuant to Section 12.212 of the Federal
// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
// Government's use, duplication or disclosure of the computer software
// is subject to the restrictions set forth by 60East Technologies Inc..
//
////////////////////////////////////////////////////////////////////////////
package com.crankuptheamps.client;
import java.lang.AutoCloseable;
import com.crankuptheamps.client.exception.AMPSException;
import com.crankuptheamps.client.fields.Field;
import com.crankuptheamps.client.fields.BookmarkField;
/**
* Defines the interface for bookmark stores, which are used by the
* {@link com.crankuptheamps.client.Client Client} to provide
* resumable subscriptions and client-side duplicate message handling.
*/
public interface BookmarkStore extends AutoCloseable
{
/**
* Called internally by the Client to log a bookmark to the persistent log.
* @param message The message containing the bookmark to log.
* @return the corresponding bookmark sequence number for this bookmark.
* @throws AMPSException Thrown when the message cannot be logged.
*/
long log(Message message) throws AMPSException;
/**
* 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.
*
* @param subId The subscription ID of the bookmark.
* @param bookmarkSeqNo The bookmark sequence number.
* @throws AMPSException Thrown when the specified bookmark cannot be discareded.
*/
void discard(Field subId, long bookmarkSeqNo) 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.
* @param message Message to be marked as discarded.
* @throws AMPSException Thrown when the specified message cannot be discareded.
*/
void discard(Message message) throws AMPSException;
/**
* 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.
* @param subID The subscription ID of the most recent bookmark.
* @return 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.
*/
Field getMostRecent(Field subID) throws AMPSException;
/**
* 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.
* @param subID The subscription ID of the most recent bookmark.
* @param 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).
* @return 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.
*/
Field getMostRecent(Field subID, boolean useList) throws AMPSException;
/**
* 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.
* @param message Message used to determine if the application has already
* processed and discarded the message.
* @return 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.
*/
boolean isDiscarded(Message message) 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.
* NOTE: This should only be called when there are no active subscriptions
* (i.e. before any subscribe or after all subscriptions are unsubscribed).
*
* @throws AMPSException Thrown if the store is unable to remove the contents.
*/
void purge() 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.
* NOTE: This should only be called when the specified subscription isn't
* active (i.e. before it's subscribed or after it's unsubscribed).
*
* @param subId The identifier of the subscription to purge.
* @throws AMPSException Thrown if the store is unable to remove information for the subscription.
*/
void purge(Field subId) throws AMPSException;
/**
* Called this when you want to set a resize handler that is invoked when the store needs to resize.
* @param handler The handler to invoke for the resize.
*/
public void setResizeHandler(BookmarkStoreResizeHandler handler);
/**
* Call this when you want to retrieve the sequence number of the oldest bookmark in the store.
* @param subId The subscription ID for the oldest bookmark in the store.
* @return The internal sequence number of the oldest bookmark in the store.
* @throws AMPSException The operation could not successfully be completed.
*/
long getOldestBookmarkSeq(Field subId) throws AMPSException;
/**
* 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.
* @param subId The subscription ID for the message.
* @param bookmark The bookmark containing the message.
* @throws AMPSException Thrown if the store is unable to record information in the store.
*/
void persisted(Field subId, BookmarkField bookmark) throws AMPSException;
/**
* Old style of setting a persisted bookmark no longer used.
* @param subId The subscription ID for the message.
* @param bookmarkSeqNo The bookmark sequence number.
* @throws AMPSException Thrown if the store is unable to record information in the store.
* @deprecated use {@link #persisted(Field, BookmarkField)} instead.
*/
@Deprecated
void persisted(Field subId, long bookmarkSeqNo) throws AMPSException;
/**
* Called internally by the 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.
* @param version_ The version of the AMPS server.
*/
void setServerVersion(int version_);
}