Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2010-2024 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.
* This method involves a resource cleanup since it extends AutoCloseable.
*/
public interface BookmarkStore extends AutoCloseable {
/**
* Called internally by the AMPS 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;
/**
* 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.
*
* @param subId The subscription ID of the bookmark.
* @param bookmarkSeqNo The bookmark sequence number.
* @throws AMPSException Thrown when the specified bookmark cannot be discarded.
*/
void discard(Field subId, long bookmarkSeqNo) throws AMPSException;
/**
* 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.
*
* @param message Message to be marked as discarded.
* @throws AMPSException Thrown when the specified message cannot be discarded.
*/
void discard(Message message) throws AMPSException;
/**
* 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.
*
* @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;
/**
* 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.
*
* @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 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.
*
* @param message Incoming 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;
/**
* 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.
*
* @throws AMPSException Thrown if the store is unable to remove the contents.
*/
void purge() throws AMPSException;
/**
* You can 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).
* This method is more specific as compared to 'purge' method and clears
* data for a particular subscription identified by subId.
*
* @param subId The identifier of the subscription to purge. This tells
* the method which subscription's data to clear.
* @throws AMPSException Thrown if the store is unable to remove information
* for the subscription.
*/
void purge(Field subId) throws AMPSException;
/**
* 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.
*
* @param handler The handler to invoke for the resize.
*/
public void setResizeHandler(BookmarkStoreResizeHandler handler);
/**
* You can 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 Thrown if the operation of retrieving the oldest
* bookmark sequence number encounters an issue or fails.
*/
long getOldestBookmarkSeq(Field subId) throws AMPSException;
/**
* 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.
*
* @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 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.
*
* @param version_ The version of the AMPS server.
*/
void setServerVersion(int version_);
}
