com.neeve.ods
Interface IStoreBinding

All Superinterfaces:

IEventSource

All Known Implementing Classes:

StoreBinding

public interface IStoreBinding
extends 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 directly using StoreBinding or using the StoreBindingFactory for advanced use.

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.Operation Enumerates the various operations that can be performed on a store 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.
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)
IStoreCommitCompletionEvent	commit(long transactionId, long stableTransactionId, IStoreObject[] messages, int messageCount, IStoreCommitCompletionEvent completionEvent, int flags) Commit changes made to store since last commit.
IStoreCommitCompletionEvent	createCommitCompletionEvent() Create a new commit completion event.
int	createSavepoint() Creates a savepoint in the current store transaction.
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.
int	getLastSavepoint() Get the last savepoint created for the current transaction.
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.
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.
void	processMemberControlEvent(IStoreMemberControlEvent event) Process a member control event
IStoreBinding	put(IStoreObject object) Add an object to a store.
<T> void	recordFieldUpdate(IStoreObject object, IStoreField<T> field, T oldValue, T newValue) Record 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	rollback(int savepoint) Rollback changes made to a store up through a given savepoint.
IStoreBinding	send(IStoreObject object) Send a message object.
int	size() Get the number of objects in a store.
int	sizeUnprotected() 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(Map<IStoreBinding.StartupExpectation,Enum<?>> expectations)
          throws OdsException

Open a store binding with expectations.

Note that IStoreBinding.StartupExpectation

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

open

void open()
          throws OdsException

Open a store binding with no expectations.

This method invokes open(null)

Throws:

OdsException

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.

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.

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.

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.

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.IStoreObject[], int, com.neeve.ods.IStoreCommitCompletionEvent, int)

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

sizeUnprotected

int sizeUnprotected()

Get the number of objects in a store.

This method differs from size() in that it is guaranteed not to block, but its accuracy is not guaranteed.

Returns:

the number of objects in the 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 reliable in a state other than IStoreBinding.State.Open

size

int size()

Get the number of objects in a store.

Returns:

the number of objects in the 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.

processMemberControlEvent

void processMemberControlEvent(IStoreMemberControlEvent event)

Process a member control event

Parameters:

event - The event to process

This method should be invoked in response when the following events are received from the store binding. - IStoreMemberFoundEvent - IStoreMemberConnectEvent - IStoreMemberHandshakeStartReadyEvent - IStoreMemberHandshakePrimaryHelloEvent - IStoreMemberHandshakeBackupHelloEvent - IStoreMemberInitReadyEvent - IStoreMemberLostEvent The method should be invoked serialized with the invocation of other binding 'action' methods. Users of the StoreBinding do not have to invoke this method since the StoreBinding automatically invokes this method. This method only needs to be invoked by users who want to control the scheduling of the above event with other user events.

recordFieldUpdate

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

Record 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 that can be used to access the field value. If the field is not supplied it will not be indexed even if the store supports indexing.

oldValue - The old field value.

newValue - The new field value.

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.IStoreObject[], int, 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.

commit

IStoreCommitCompletionEvent commit(long transactionId,
                                   long stableTransactionId,
                                   IStoreObject[] messages,
                                   int messageCount,
                                   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(long transactionId,
                                   long stableTransactionId,
                                   IStoreCommitCompletionEvent completionEvent,
                                   int flags)
                                   throws OdsException

Throws:

OdsException

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

createSavepoint

int createSavepoint()

Creates a savepoint in the current store transaction.

A savepoint serves as a delimiter that can used to partially rollback a transaction. A subsequent call to rollback(int) with the returned savepoint version will roll the transaction back to the state at the time of this call.

Returns:

The new savepoint.

getLastSavepoint

int getLastSavepoint()

Get the last savepoint created for the current transaction.

Returns the savepoint version created by the last call to createSavepoint() or the transaction's initial savepoint (0) if no savepoint has been created.

Returns:

the current savepoint.

rollback

IStoreBinding rollback()

Rollback changes made to a store.

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.

Returns:

Returns this object for invocation chaining.

Throws:

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

Threading:

This method is safe for concurrent access by multiple threads.

rollback

IStoreBinding rollback(int savepoint)

Rollback changes made to a store up through a given savepoint.

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

This method preserves the savepoint marker passed in, i.e. after this call getLastSavepoint() will return the provided savepoint, and all subseqeuent savepoints are discarded.

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.

Parameters:

savepoint - The savepoint to roll back to.

Returns:

Returns this object for invocation chaining.

Throws:

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

IllegalArgumentException - if the savepoint is greater than the current savepoint or less than 0.

See Also:

createSavepoint()

Threading:

This method is safe for concurrent access 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.