com.crankuptheamps.client.RecoveryPointAdapter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of amps-client Show documentation
AMPS Java client by 60East Technologies, Inc.
There is a newer version: 5.3.4.0
///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2010-2022 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;
}