com.neeve.ods
Interface IStoreBinding

All Superinterfaces:

com.neeve.event.IEventSource

All Known Implementing Classes:

RogStore, com.neeve.ods.impl.StoreBindingBase

public interface IStoreBinding
extends com.neeve.event.IEventSource

Represents a binding to an ODS store.

A store binding serves as an interface to an ODS store. It provides the mechanism by which a user stores and retrieves objects in an ODS store. A user creates store bindings using StoreBindingFactory.

Threading:

A store binding is safe for concurrent access by multiple threads.

Nested Class Summary

static class	IStoreBinding.InterClusterReplicationRole Enumerates the different inter-cluster replication roles of a binding.
static class	IStoreBinding.Role Enumerates the different roles of a binding in a store cluster.
static class	IStoreBinding.StartupExpectation Enumerates the set of startup expectations that can be requested.
static class	IStoreBinding.State Enumerates the different binding states

Field Summary

static int	CLOSE_ICR_AS_FAIL Specifies that ICR sender/receiver should be closed with failure.
static int	NO_COMMIT_COMPLETIONS Specifies that commit completion events should not be dispatched on close.
static int	SUPPRESS_COMPLETION_EVENT_DISPATCH_IF_SYNC_COMPLETION Specifies that the commit operation should not dispatch the commit completion event if the commit completed synchronously i.e. within the commit call itself.

Method Summary

IStoreQueryRepository	asQueryRepository() Returns a view of this IStoreBinding as a IStoreQueryRepository.
IStoreBinding	clear() Remove all objects from the store.
void	close(int flags) Close a store binding.
IStoreCommitCompletionEvent	commit(IStoreCommitCompletionEvent completionEvent) Commits changes made to the store since last commit without a transaction id.
IStoreCommitCompletionEvent	commit(long transactionId, long stableTransactionId, IStoreCommitCompletionEvent completionEvent, int flags) Commit changes made to store since last commit.
IStoreCommitCompletionEvent	createCommitCompletionEvent() Create a new commit completion event.
void	fail(Exception e) Force fail a store binding.
IStoreObject	get(com.eaio.uuid.UUID id) Get an object from a store
StoreDescriptor	getDescriptor() Get the descriptor used to created a store binding.
IStoreEventHandler	getEventHandler() Get a binding's event handler.
IStoreSender	getICRSender() Get a binding's ICR sender
IStoreBinding.InterClusterReplicationRole	getInterClusterReplicationRole() Get a binding's inter-cluster replication role.
IStoreMember	getMember() Get the member represented by a store binding.
int	getMemberCount() Get a store's member count.
IStorePersister	getPersister() Get a binding's persister.
IStoreQueryEngine	getQueryEngine() Get a binding's IStoreQueryEngine.
IStoreBinding.Role	getRole() Get a binding's role.
IStoreBinding.State	getState() Get a binding's state.
IStoreBindingStats	getStats() Get a binding's statistics object.
boolean	getThreaded() Get the user's threading model.
IStoreTransactionLog	getTransactionLog() Get a binding's transaction log.
boolean	isPersistenceQuorumMet() Get whether membership is at or above persistence quorum.
void	open() Open a store binding with no expectations.
void	open(Map<IStoreBinding.StartupExpectation,Enum<?>> expectations) Open a store binding with expectations
IStoreBinding	put(IStoreObject object) Add an object to a store.
<T> void	recordFieldUpdate(IStoreObject object, int fieldId, T oldValue, T newValue) Records a field update for the given object in the store's transaction log and updates store indexes.
<T> void	recordFieldUpdate(IStoreObject object, IStoreField<T> field, T oldValue, T newValue) Records a field update for the given object in the store's transaction log and updates store indexes.
IStoreBinding	remove(IStoreObject object) Remove an object from a store.
IStoreBinding	rollback() Rollback changes made to a store.
IStoreBinding	send(IStoreObject object) Send a message object.
void	setThreaded(boolean val) Set the user's threading model.
int	size() Get the number of objects in a store.

Methods inherited from interface com.neeve.event.IEventSource

getName

Field Detail

NO_COMMIT_COMPLETIONS

static final int NO_COMMIT_COMPLETIONS

Specifies that commit completion events should not be dispatched on close.

By default, commit completion events are dispatched for incomplete commits when a store binding is closed. The user should specify this flag to the close(int) method to suppress the dispatch of these events.

See Also:

Constant Field Values

CLOSE_ICR_AS_FAIL

static final int CLOSE_ICR_AS_FAIL

Specifies that ICR sender/receiver should be closed with failure.

Specifying this flag indicates that the ICR sender/receiver should be closed indicating a failure. Closing with failure causes the ICR sender/receiver to close the underlying messaging bindings in a manner to not explictly leave joined channels i.e. leave subscriptions open.

See Also:

Constant Field Values

SUPPRESS_COMPLETION_EVENT_DISPATCH_IF_SYNC_COMPLETION

static final int SUPPRESS_COMPLETION_EVENT_DISPATCH_IF_SYNC_COMPLETION

Specifies that the commit operation should not dispatch the commit completion event if the commit completed synchronously i.e. within the commit call itself.

See Also:

Constant Field Values

Method Detail

open

void open()
          throws OdsException

Open a store binding with no expectations.

This method invokes open(null)

Throws:

OdsException

open

void open(Map<IStoreBinding.StartupExpectation,Enum<?>> expectations)
          throws OdsException

Open a store binding with expectations

Parameters:

expectations - The set of expectations to open the store with. This method will throw an exception if any of the expectations specified are not met.

Throws:

OdsException

setThreaded

void setThreaded(boolean val)

Set the user's threading model.

Parameters:

val - A value of true indicates that the user will be concurrently accessing the store and transaction log using multiple threads. A value of false indicates that there can be at most one user thread operating on the store and/or the transaction log at any point in time.

This method can be invoked on a binding in any state.

getThreaded

boolean getThreaded()

Get the user's threading model.

getMember

IStoreMember getMember()

Get the member represented by a store binding.

Threading:

This method is safe for concurrent access by multiple threads.

A binding to a store essentially represents a member of the store. This method returns the member represented by a binding.

This method can be invoked on a binding in any state.

getDescriptor

StoreDescriptor getDescriptor()

Get the descriptor used to created a store binding.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a binding in any state.

getEventHandler

IStoreEventHandler getEventHandler()

Get a binding's event handler.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a binding in any state.

getState

IStoreBinding.State getState()

Get a binding's state.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a binding in any state.

getStats

IStoreBindingStats getStats()

Get a binding's statistics object.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a binding in any state.

getRole

IStoreBinding.Role getRole()

Get a binding's role.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be only be invoked on a binding in any state other than the closed state.

getInterClusterReplicationRole

IStoreBinding.InterClusterReplicationRole getInterClusterReplicationRole()

Get a binding's inter-cluster replication role.

Returns:

Returns the ICR role. A value of null is returned if the binding is not configured for inter-cluster replication

Threading:

This method is safe for concurrent access by multiple threads.

This method can be only be invoked on a binding in any state.

getMemberCount

int getMemberCount()

Get a store's member count.

Threading:

This method is safe for concurrent access by multiple threads.

This method returns the number of members in a store including the member represented by the binding on which this method is called e.g. a value of 1 returned by this method implies there are no additional members in the store.

This method can be invoked on a binding in the opening or open state.

isPersistenceQuorumMet

boolean isPersistenceQuorumMet()

Get whether membership is at or above persistence quorum.

This method can be invoked on a binding in the opening or open state.

getTransactionLog

IStoreTransactionLog getTransactionLog()

Get a binding's transaction log.

Returns:

The binding's transaction log

Threading:

This method is safe for concurrent access by multiple threads.

A binding's transaction log records operations performed on store objects by the binding. This method returns a binding's transaction log.

This method can be only be invoked on a binding in a post open state.

recordFieldUpdate

<T> void recordFieldUpdate(IStoreObject object,
                           int fieldId,
                           T oldValue,
                           T newValue)

Records a field update for the given object in the store's transaction log and updates store indexes.

Parameters:

object - The object being updated.

fieldId - The id of the field being updated

oldValue - The old field value.

newValue - The new field value.

recordFieldUpdate

<T> void recordFieldUpdate(IStoreObject object,
                           IStoreField<T> field,
                           T oldValue,
                           T newValue)

Records a field update for the given object in the store's transaction log and updates store indexes.

Parameters:

object - The object being updated.

field - The field being updated.

oldValue - The old field value.

newValue - The new field value.

getQueryEngine

IStoreQueryEngine getQueryEngine()

Get a binding's IStoreQueryEngine.

A binding's IStoreQueryEngine allows the store to be queried.

This method can be only be invoked on a binding in a post open state.

Returns:

The binding's query engine.

Threading:

This method is safe for concurrent access by multiple threads.

asQueryRepository

IStoreQueryRepository asQueryRepository()

Returns a view of this IStoreBinding as a IStoreQueryRepository.

A binding configured for query provides this view to its IStoreQueryEngine.

This method can be only be invoked on a binding in a post open state.

Returns:

The IStoreQueryRepository for this engine or null, if it is not configured for query.

Threading:

This method is safe for concurrent access by multiple threads.

getPersister

IStorePersister getPersister()

Get a binding's persister.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be only be invoked on a binding in any state other than failed or closed states.

getICRSender

IStoreSender getICRSender()

Get a binding's ICR sender

Threading:

This method is safe for concurrent access by multiple threads.

This method can be only be invoked on a binding in any state other than failed or closed states.

createCommitCompletionEvent

IStoreCommitCompletionEvent createCommitCompletionEvent()

Create a new commit completion event.

Threading:

This method is safe for concurrent access by multiple threads.

This method creates a new commit completion for use with commit(long, long, com.neeve.ods.IStoreCommitCompletionEvent, int)

This method can be invoked on a binding in any state.

put

IStoreBinding put(IStoreObject object)

Add an object to a store.

Parameters:

object - The object to be added to the store.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalArgumentException - Thrown if the specified object is null or the object is already in a store.

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

This method adds a new object to a store. This method will throw an exception in an object with the same id as the object being added already exists in the store.

An object put into a store is immediately visible to any thread of control accessing the store using the binding that put the object into the store. With regard to visibility to other store members (bindings), an object put into a store is not visible to other store members (bindings) until the next commit(long, long, com.neeve.ods.IStoreCommitCompletionEvent, int).

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent acess by multiple threads.

send

IStoreBinding send(IStoreObject object)

Send a message object.

Parameters:

object - The object sent via the store.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalArgumentException - Thrown if the specified object is null or the object is already in a store.

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

This method sends an object as a message through the store. Messages sent using this method are enqueued in the store until the next commit or rollback. While enqueued, the messages are invisible to get(com.eaio.uuid.UUID) and remove(com.neeve.ods.IStoreObject) but field updates are recorded in the transaction log. At the next commit, the enqueued messages are transmitted (along with other store updates) to the peer members and the message records removed from the store. On rollback, the message records are just removed from the store. A message can only be sent once per commit i.e. a subsequent send of the same message before a commit will throw an exception. Upon completion of a commit or rollback, messages sent in the committed/rolled back transaction can be resent.

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent acess by multiple threads.

get

IStoreObject get(com.eaio.uuid.UUID id)

Get an object from a store

Parameters:

id - The object's id

Throws:

IllegalArgumentException - Thrown if the specified id is null.

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

This method retrieves an object with the specified id from a store. A value of null is returned if there is no object with the specified id in the store visible to the binding used to perform the get.

This method can be only be invoked on a binding in the initializing or open state.

This method cannot be invoked on a primary member from within an event handler. Doing so can result in a deadlock. On a backup member, this method can be called only from the IStoreObjectAddedEvent, the IStoreObjectUpdatedEvent and IStoreObjectRemovedEvent event handlers. It should not be called from elsewhere.

Threading:

This method is safe for concurrent acess by multiple threads.

remove

IStoreBinding remove(IStoreObject object)

Remove an object from a store.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalArgumentException - Thrown if the specified object is null or the object is not in the store.

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

Isolation semantics for removal are the same as for object addition (see put(com.neeve.ods.IStoreObject)

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent acess by multiple threads.

clear

IStoreBinding clear()

Remove all objects from the store.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

This method clears all objects from the store. This operation is not bracketed within the ongoing transaction. The clear operation implicitly commits the current transaction and then clears the store of all entries.

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent acess by multiple threads.

size

int size()

Get the number of objects in a store.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a binding in any state, though its accuracy is not guaranteed in a state other than IStoreBinding.State.Open

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

commit

IStoreCommitCompletionEvent commit(long transactionId,
                                   long stableTransactionId,
                                   IStoreCommitCompletionEvent completionEvent,
                                   int flags)
                                   throws OdsException

Commit changes made to store since last commit.

Parameters:

transactionId - A user supplied transaction id that will be set in each of the objects committed by this method. This id is not interpreted by ODS. It is only accepted here to set in objects in the transaction to tie the objects committed by the store with other objects in the same transaction.

stableTransactionId - A user supplied stable transaction id that will be set in each of the objects committed by this method. This id is not interpreted by ODS. It is only accepted here to set in objects in the transaction to tie the objects committed by the store with other objects in the same transaction.

completionEvent - The completion event that will be used to communicate the completion of and replication status for the commit operation. A value of null indicates the caller is not interested in the results of the commit operation.

flags - Flags that qualify the commit operation. The following flags are permitted for use:
- SUPPRESS_COMPLETION_EVENT_DISPATCH_IF_SYNC_COMPLETION

Returns:

Returns the commit completion event object supplied to the commit method.

Throws:

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

OdsException - Thrown if and only if an error is encountered before the replication phse of the the commit process. In such as case, it is guaranteed that the state of the store and transaction log is restored to pre-commit state before the exception is thrown.

This method commits all changes made to a store via a binding using the calling thread since the last commit. The commit operation essentially consists of replicating changes recorded in a store's transaction log to other (backup) store members. When invoked, this method first prepares for the replication process. Any failure in this pre-replication phase is reported to the user via an exception thrown by this method. If the replication preparation completes successfully, the commit kicks off the replication and returns to the caller. Any failure in the replication is now reported to the user via the commit completion event object supplied to this method (the user should not modify the completion event until the commit has completed). Upon completion of the replication, the ODS runtime sets a commit completion status in the completion event (see IStoreCommitCompletionStatus) and notifies the user of the completion. The notification is performed using the the notification mode set by the user in the completion event object.

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent access by multiple threads.

commit

IStoreCommitCompletionEvent commit(IStoreCommitCompletionEvent completionEvent)
                                   throws OdsException

Commits changes made to the store since last commit without a transaction id.

This method invokes commit(0, completionEvent)

Throws:

OdsException

rollback

IStoreBinding rollback()

Rollback changes made to a store.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalStateException - Thrown if the binding is not open or if the binding has the backup role.

This method rolls back changes made to the store since the last commit. The rollback operation plays back and undoes all operations recorded in the calling thread's transaction log. The transaction log is then cleared.

This method can be only be invoked on a binding in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is safe for concurrent acess by multiple threads.

fail

void fail(Exception e)

Force fail a store binding.

Parameters:

e - The exception that describes the failures. This exception object will be attached to the binding failed event dispatched to the user as a consequence of this method.

Throws:

IllegalStateException - Thrown if the binding is not open.

This method force fails a binding. The method will trigger the binding's failure handling machinery. This will result in the dispatch of the IStoreBindingFailedEvent just as if the binding actually failed. The principal purpose of this method is to simulate binding failures for fault tolerance testing purposes. The user typically has no use for this method and should use close(int) when done with the binding.

A binding implictly closes itself (although it leaves its state as IStoreBinding.State.Failed) when it fails. Therefore, there is is not necessary to call close() after a binding fails although it is permissible to do so.

This method can be invoked on bindings in the open state.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.

Threading:

This method is not safe for concurrent access by multiple threads.

close

void close(int flags)

Close a store binding.

Parameters:

flags - Flags that qualify the close operation. The following are the permissible flags that can be used with this method:
- NO_COMMIT_COMPLETIONS - CLOSE_ICR_AS_FAIL

Threading:

This method is not safe for concurrent access by multiple threads.

This method closes a store binding. Closing a store binding will remove it from the store (other member will receive a 'member down' event). Commit operations pending completion are discarded

This method can be invoked on bindings in any state. It is safe to invoke the method multiple times.

This method cannot be invoked from within an event handler. Doing so can result in a deadlock.