org.eclipse.ecf.sync
Interface IModelSynchronizationStrategy

All Superinterfaces:

org.eclipse.core.runtime.IAdaptable

public interface IModelSynchronizationStrategy
extends org.eclipse.core.runtime.IAdaptable

Model synchronization strategy contract. Model synchronization strategy instances are used to synchronize replicated instances of an arbitrary model. This is done by creating instances implementing this interface on participating processes, and then using them in the following manner.

First, assume for simplicity that there are two processes (A and B), each with a replica of a given model (a and b). Also assume that prior to using a synchronization strategy that the model is accurately and reliably replicated to A and B (i.e. a == b). Further, assume that for both A and B an instance of IModelSynchronizationStrategy is created (call them Sa and Sb) prior to any changes being made to either a or b.

On process A assume that the user makes a change to a via a (local) editor. Then the expected sequence of activities is as follows:

• Process A should synchronously call registerLocalChange(IModelChange). The IModelChange instance provided must be 1) not null; and 2) Of a type that is appropriate for this synchronization strategy.
• Process A should take the resulting IModelChangeMessage, serialize it (by calling IModelChangeMessage.serialize() and send the message to remote processes (i.e. B).
• Process B should take the received byte array and call deserializeRemoteChange(byte[]) to create an IModelChange instance.
• Process B should then pass the IModelChange instance to transformRemoteChange(IModelChange). The synchronization implementation will then return an array of IModelChange instances (IModelChange []). These IModelChange instance should then be cast to the appropriate type, and applied to the local instance of the model (i.e. b). The transformRemoteChange(IModelChange) metho will take the local changes (previously registered with the synchronization strategy via registerLocalChange(IModelChange)), and the remote changes provided via transformRemoteChange(IModelChange), and transform the changes into a set that will result in a synchronized local copy.

Note that clients should generally call the registerLocalChange(IModelChange) and apply the IModelChanges returned from transformRemoteChange(IModelChange) on the same thread that is responsible for modifying the underlying model. For example, if a document model is modified by an editor (via UI thread) then the UI thread should also synchronously call registerLocalChange(IModelChange), and the changes from transformRemoteChange(IModelChange) should also be applied to the local document from within this same thread.

Since:

2.1

Method Summary

IModelChange	deserializeRemoteChange(byte[] bytes) Deserialization of given byte array to concrete instance of IModelChange object to represent local change to be applied
IModelChangeMessage[]	registerLocalChange(IModelChange localChange) Register local model change with synchronization strategy.
IModelChange[]	transformRemoteChange(IModelChange remoteChange) Transform remote change into a set of local changes to be synchronously applied to the local model.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Method Detail

registerLocalChange

IModelChangeMessage[] registerLocalChange(IModelChange localChange)

Register local model change with synchronization strategy. This method should be synchronously called when a local model change has been made to the underlying model.

Parameters:

localChange - the IModelChange made to the local model. Must be non- null, and must be of type appropriate for the synchronization strategy.

Returns:

IModelChangeMessage[] an array of change message to be delivered to remote participants. If no change message can be created for this local change (e.g. because the localChange is not of the expected type, or because the change is not to be propogated to remotes, then an empty array will be returned).

transformRemoteChange

IModelChange[] transformRemoteChange(IModelChange remoteChange)

Transform remote change into a set of local changes to be synchronously applied to the local model.

Parameters:

remoteChange - the remote model change instance to be transformed by this synchronization strategy.

Returns:

IModelChange[] to apply to local model.

deserializeRemoteChange

IModelChange deserializeRemoteChange(byte[] bytes)
                                     throws SerializationException

Deserialization of given byte array to concrete instance of IModelChange object to represent local change to be applied

Parameters:

bytes - the bytes to be deserialized.

Returns:

IModelChange instance from bytes. Will not be null.

Throws:

SerializationException - thrown if some problem deserializing given bytes.