[ecf-dev] TransactionSharedObject

[Scott Lewis <slewis@xxxxxxxxxxxxx>]

Hi Folks,

I (Scott) have introduced some new API into the org.eclipse.ecf.core 
package hierarchy, to support the creation and use of reliable protocols 
for distributed state update. 

In some applications/parts of applications it's necessary that the 
application be *certain* that a distributed state update was received 
and processed before continuing on a certain path of computation (e.g. 
making sure the authoritative...or all...copies of your bank balance are 
successfully updated before using the local copy in a computation).

Below I describe the some of the org.eclipse.ecf.core.sharedobject.* 
API, and there is more to come.  (javadocs + new and noteworth for 0.5.1 
stable, etc).  Any thoughts/comments are appreciated.

Scott

New API

A note to let you all know that I've completed an initial API and 
implementation for doing reliable messaging within the ECF shared object 
component api. The new API/classes are available in the 
org.eclipse.ecf.core.sharedobject package in the org.eclipse.ecf project.

There's also a little bit of junit test code in 
org.eclipse.ecf.test.AddTransactionSharedObjectTest class.

What this API does is provide the underpinnings for reliable messaging 
in ECF. If an application needs to send a message...and be assured that 
it arrives and is processed before continuing it can implement such 
behavior via this API (either in a *provider code* or in the application 
if desired...my assumption is that providers can/will implement high 
level APIs...like what Boris and Peter have been working on...using 
these primitives).

For example, in the AddTransactionSharedObjectTest code there's a line 
like this:

container.getSharedObjectManager().addSharedObject(id, sharedobject, 
properties));

Iff the class of the sharedobject is a subclass of 
org.eclipse.ecf.core.sharedobject.TransactionSharedObject, then this add 
*blocks* until the given shared object has been successfully 
replicated/added for all other participating containers....or a timeout 
has occurred (the timeout duration is configurable). If a timeout 
occurs, or the replication fails on one or more of the remote 
participants the addSharedObject call with throw an 
SharedObjectAddAbortException (with cause information from remotes) and 
the object will be removed/cleanedup on all participants. This provides
'all or nothing' state distribution.

So immediately *after the addSharedObject call (i.e. if it succeeds), 
the application can have confidence that for the current set of
participants the given object *was* actually created and it's 
initialization code was executed successfully.

This makes possible (even easy) to implement calls that look like this:

adapter.sendMessageSynch(byte [] data, int timeout) throws 
SomeWrapperExceptionForSharedObjectAddAbortException;

The reason the above-described classes are useful is that the 
implementation of sendMessageSynch (or other, similar APIs) can simply:

1) Create a shared object that extends TransactionSharedObject, 'wraps' 
the data (as state for the new object) and sets up the appropriate
timeout value.
2) Add this TransactionSharedObject to the container: and the calling 
thread will block until failed, timeout, or complete in doing the 
replication

Thus making it very easy to implement APIs like the sendMessageSynch 
call above and know that either the message delivery completed
successfully or failed, or timedout..

More to come in terms of junit test code (to test/debug different 
scenarios), but I thought I would initiate a discussion about this
relative to the work that Boris and Peter are doing defining the 
datashare2 API.

Thanks,

Scott