com.crankuptheamps.client.Store 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 com.crankuptheamps.client.exception.DisconnectedException;
import com.crankuptheamps.client.exception.StoreException;
import com.crankuptheamps.client.exception.TimedOutException;
/**
* Represents a message store. The AMPS client uses message stores for
* recovery purposes. The store is responsible for maintaining the state
* of published messages and recovering that state in the event of a
* disconnection. Optionally, the store may persist message state and
* recover that state if the application restarts.
*/
public interface Store extends AutoCloseable
{
/**
* Replay the messages saved in a store. Provided to the
* {@link Store#replay} or {@link Store#replaySingle} methods
* to replay stored operations. The StoreReplayer is responsible for
* publishing the operations to AMPS.
*/
interface StoreReplayer
{
/**
* Replay the specified operation.
* @param m the message to replay
* @throws DisconnectedException Thrown when the client is not connected when attempting to replay the message.
*/
void execute(Message m) throws DisconnectedException;
}
int SOWDeleteByData = 1;
int SOWDeleteByFilter = 2;
int SOWDeleteByKeys = 4;
int SOWDeleteByBookmark = 8;
int SOWDeleteByBookmarkCancel = 16;
/**
* Store the provided message. The sequence of the message is a key
* that the client can later use to replay the operation or remove
* the operation from the store. Implementations may assume that the
* sequence increases monotonically.
*
* @param m the message to store
* @throws StoreException Thrown if the Store is unable to store the message.
*/
void store(Message m) throws StoreException;
/**
* Discard all operations up to the index provided.
* @param index the index number to keep -- all previous index numbers will be discarded
* @throws StoreException Thrown if the Store is unable to discard the messages.
*/
void discardUpTo(long index) throws StoreException;
/**
* Replay all operations in the store using the provided StoreReplayer.
* @param replayer the StoreReplayer to use to replay the operations
* @throws StoreException Thrown if the Store is unable to replay the operations.
* @throws DisconnectedException Thrown if the Store receives a DisconnectedException while replaying.
*/
void replay(StoreReplayer replayer)
throws StoreException, DisconnectedException;
/**
* Replay the operation at the specified index.
* @return Success returns true, false if the index is not in the Store
* @param replayer the StoreReplayer to use to replay the operations
* @param index The index of the message to replay within the store
* @throws StoreException Thrown if the Store is unable to replay the operations.
* @throws DisconnectedException Thrown if the Store receives a DisconnectedException while replaying.
*/
boolean replaySingle(StoreReplayer replayer, long index)
throws StoreException, DisconnectedException;
/**
* Return the number of operations in the store.
* @return The number of operations in the store.
*/
long unpersistedCount();
/**
* Return the oldest index in the store.
* @return The lowest sequence number of an operation in the store.
*/
long getLowestUnpersisted();
/**
* Wait for the store to discard everything that has been stored
* up to the point in time when flush is called, then
* return.
*
* @throws TimedOutException Not thrown from this overload.
*/
void flush() throws TimedOutException;
/**
* Wait for the store to discard everything that has been stored
* up to the point in time when flush is called, then
* return. Throw an exception if this is not completed in the number of
* milliseconds specified by the timeout.
* @param timeout the number of milliseconds to wait for the flush
* @throws TimedOutException Thrown if the timeout period passes without the messages being discarded.
*/
void flush(long timeout) throws TimedOutException;
/**
* Set the resize handler for the publish store. An implementation can
* call the resize handler in the event that it needs to grow the
* size of the publish store.
* @param handler The handler to install.
*/
void setResizeHandler(PublishStoreResizeHandler handler);
/**
* Return the last persisted index in the store.
* @return The sequence number of the last discarded message.
* @throws StoreException Thrown if the store is unable to produce the last persisted index.
*/
public long getLastPersisted() throws StoreException;
/**
* Provide the Store with a preallocated Message for use in replay.
* @param m The message object for the Store to use during replay.
*/
void setMessage(Message m);
/**
* Get whether the Store will throw a PublishGapException from discardUpTo if the
* sequence number being discarded is less then the current last persisted.
* @return If true, an exception will be thrown during logon if a gap could be
* created. If false, logon is allowed to proceed.
*/
boolean getErrorOnPublishGap();
/**
* Set whether the Store should throw a PublishGapException from discardUpTo if the
* sequence number being discarded is less then the current last persisted. This can
* occur if the client fails over to a server that has not been synchronously replicated
* to by its previous server, which lead to the new server having a gap in messages from
* this client.
* @param errorOnGap If true, an exception will be thrown during logon if a gap could be
* created. If false, allow the logon to proceed.
*/
void setErrorOnPublishGap(boolean errorOnGap);
}