com.crankuptheamps.client

Interface Store

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

BlockPublishStore, HybridPublishStore, MemoryPublishStore, PublishStore

public interface Store
extends java.lang.AutoCloseable

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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Store.StoreReplayer Replay the messages saved in a store.

Field Summary

Fields

Modifier and Type	Field and Description
static int	SOWDeleteByBookmark
static int	SOWDeleteByBookmarkCancel
static int	SOWDeleteByData
static int	SOWDeleteByFilter
static int	SOWDeleteByKeys

Method Summary

Modifier and Type	Method and Description
void	discardUpTo(long index) Discard all operations up to the index provided.
void	flush() Wait for the store to discard everything that has been stored up to the point in time when flush is called, then return.
void	flush(long timeout) Wait for the store to discard everything that has been stored up to the point in time when flush is called, then return.
boolean	getErrorOnPublishGap() Get whether the Store will throw a PublishGapException from discardUpTo if the sequence number being discarded is less then the current last persisted.
long	getLastPersisted() Return the last persisted index in the store.
long	getLowestUnpersisted() Return the oldest index in the store.
void	replay(Store.StoreReplayer replayer) Replay all operations in the store using the provided StoreReplayer.
boolean	replaySingle(Store.StoreReplayer replayer, long index) Replay the operation at the specified index.
void	setErrorOnPublishGap(boolean errorOnGap) Set whether the Store should throw a PublishGapException from discardUpTo if the sequence number being discarded is less then the current last persisted.
void	setMessage(Message m) Provide the Store with a preallocated Message for use in replay.
void	setResizeHandler(PublishStoreResizeHandler handler) Set the resize handler for the publish store.
void	store(Message m) Store the provided message.
long	unpersistedCount() Return the number of operations in the store.

Methods inherited from interface java.lang.AutoCloseable

close

Field Detail

SOWDeleteByData

static final int SOWDeleteByData

See Also:

Constant Field Values

SOWDeleteByFilter

static final int SOWDeleteByFilter

See Also:

Constant Field Values

SOWDeleteByKeys

static final int SOWDeleteByKeys

See Also:

Constant Field Values

SOWDeleteByBookmark

static final int SOWDeleteByBookmark

See Also:

Constant Field Values

SOWDeleteByBookmarkCancel

static final int SOWDeleteByBookmarkCancel

See Also:

Constant Field Values

Method Detail

store

void store(Message m)
    throws StoreException

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.

Parameters:

m - the message to store

Throws:

StoreException - Thrown if the Store is unable to store the message.

discardUpTo

void discardUpTo(long index)
          throws StoreException

Discard all operations up to the index provided.

Parameters:

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.

replay

void replay(Store.StoreReplayer replayer)
     throws StoreException,
            DisconnectedException

Replay all operations in the store using the provided StoreReplayer.

Parameters:

replayer - the StoreReplayer to use to replay the operations

Throws:

StoreException - Thrown if the Store is unable to replay the operations.

DisconnectedException - Thrown if the Store receives a DisconnectedException while replaying.

replaySingle

boolean replaySingle(Store.StoreReplayer replayer,
                     long index)
              throws StoreException,
                     DisconnectedException

Replay the operation at the specified index.

Parameters:

replayer - the StoreReplayer to use to replay the operations

index - The index of the message to replay within the store

Returns:

Success returns true, false if the index is not in the Store

Throws:

StoreException - Thrown if the Store is unable to replay the operations.

DisconnectedException - Thrown if the Store receives a DisconnectedException while replaying.

unpersistedCount

long unpersistedCount()

Return the number of operations in the store.

Returns:

The number of operations in the store.

getLowestUnpersisted

long getLowestUnpersisted()

Return the oldest index in the store.

Returns:

The lowest sequence number of an operation in the store.

flush

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.

Throws:

TimedOutException - Not thrown from this overload.

flush

void flush(long timeout)
    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.

Parameters:

timeout - the number of milliseconds to wait for the flush

Throws:

TimedOutException - Thrown if the timeout period passes without the messages being discarded.

setResizeHandler

void setResizeHandler(PublishStoreResizeHandler handler)

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.

Parameters:

handler - The handler to install.

getLastPersisted

long getLastPersisted()
               throws StoreException

Return the last persisted index in the store.

Returns:

The sequence number of the last discarded message.

Throws:

StoreException - Thrown if the store is unable to produce the last persisted index.

setMessage

void setMessage(Message m)

Provide the Store with a preallocated Message for use in replay.

Parameters:

m - The message object for the Store to use during replay.

getErrorOnPublishGap

boolean getErrorOnPublishGap()

Get whether the Store will throw a PublishGapException from discardUpTo if the sequence number being discarded is less then the current last persisted.

Returns:

If true, an exception will be thrown during logon if a gap could be created. If false, logon is allowed to proceed.

setErrorOnPublishGap

void setErrorOnPublishGap(boolean errorOnGap)

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.

Parameters:

errorOnGap - If true, an exception will be thrown during logon if a gap could be created. If false, allow the logon to proceed.