com.crankuptheamps.client.RecoveryPointAdapter Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////
//
// 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 java.lang.Iterable;
import java.util.Iterator;
import com.crankuptheamps.client.fields.Field;
/**
* An instance of this interface that can optionally be provided to {@link
* MemoryBookmarkStore} when it's constructed to persist recovery bookmark
* state for each bookmark replay subscription. The adapter can persist this
* state to an external store and retrieve it on application restart so that
* bookmark replay subscriptions can be continued approximately where they
* left off (with the possible delivery of some duplicate messages).
*
* Typically the constructor of any implementation class will take resources
* needed to connect to / authenticate with the external store and a unique
* AMPS client name or session name (that stays consistent across application
* runs) that identifies the AMPS client whose bookmark replay subscriptions
* want to have their recovery state persisted by this adapter.
*/
public interface RecoveryPointAdapter extends Iterator, Iterable, AutoCloseable {
/**
* This method should be implemented to write the passed in recovery point
* to the external store for the specified subscription. Only the latest
* recovery point needs to be kept for any given subscription id. When
* this adapter is registered directly with a bookmark store, this method
* is called by a bookmark store subscription (with its lock held) whenever
* the MOST_RECENT state of the subscription has potentially changed. If the
* associated bookmark store has multiple subscriptions, it's possible for
* this method to be called concurrently by each one, so this method should
* be implemented in a thread-safe manner. If this adapter is a delegate
* wrapped by a {@link ConflatingRecoveryPointAdapter}, then this method
* is only called by the conflating adapter's update thread periodically
* (never concurrently by multiple threads) without the subscription lock
* held.
*
* @param recoveryPoint The latest recovery point.
* @throws Exception Should be thrown for any error writing recovery
* state to the external store.
*/
void update(RecoveryPoint recoveryPoint) throws Exception;
/**
* This method is called by the associated bookmark store's purge(subId)
* method (with the bookmark store lock held) with the expectation that
* the adapter will delete any recover point data stored for the
* specified subscription id. Because the bookmark store lock is held
* when this is called, this method will only be invoked by one thread
* at a time.
*
* @param subId The id of the subscription being purged.
* @throws Exception Should be thrown for any error deleting recovery
* state from the external store.
*
* @see BookmarkStore#purge(com.crankuptheamps.client.fields.Field)
*/
void purge(Field subId) throws Exception;
/**
* This method is called by the associated bookmark store's purge()
* method (with the bookmark store lock held) with the expectation that
* the adapter will delete all recover point data stored for all
* subscriptions known to this adapter. Because the bookmark store lock is
* held when this is called, this method will only be invoked by one thread
* at a time.
*
* @throws Exception Should be thrown for any error deleting recovery
* state from the external store.
*
* @see BookmarkStore#purge()
*/
void purge() throws Exception;
}