Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorslewis2008-10-14 14:50:37 -0400
committerslewis2008-10-14 14:50:37 -0400
commite44dba77ed36edd8afc495660caec9714daf340e (patch)
tree48477d7e7978657bb437ba1c4133a6064251cc41 /framework/bundles/org.eclipse.ecf.sync
parent6008140826089ffd9b0a155a5bf6e5793c51618b (diff)
downloadorg.eclipse.ecf-e44dba77ed36edd8afc495660caec9714daf340e.tar.gz
org.eclipse.ecf-e44dba77ed36edd8afc495660caec9714daf340e.tar.xz
org.eclipse.ecf-e44dba77ed36edd8afc495660caec9714daf340e.zip
Added documentation for IModelSynchronizationStrategy
Diffstat (limited to 'framework/bundles/org.eclipse.ecf.sync')
-rw-r--r--framework/bundles/org.eclipse.ecf.sync/src/org/eclipse/ecf/sync/IModelSynchronizationStrategy.java49
1 files changed, 46 insertions, 3 deletions
diff --git a/framework/bundles/org.eclipse.ecf.sync/src/org/eclipse/ecf/sync/IModelSynchronizationStrategy.java b/framework/bundles/org.eclipse.ecf.sync/src/org/eclipse/ecf/sync/IModelSynchronizationStrategy.java
index 744f6a5d6..8f0db4a4c 100644
--- a/framework/bundles/org.eclipse.ecf.sync/src/org/eclipse/ecf/sync/IModelSynchronizationStrategy.java
+++ b/framework/bundles/org.eclipse.ecf.sync/src/org/eclipse/ecf/sync/IModelSynchronizationStrategy.java
@@ -1,16 +1,59 @@
package org.eclipse.ecf.sync;
-
+/**
+ * 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.
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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:
+ * </p>
+ * <ul>
+ * <li>Process A should synchronously call {@link #registerLocalChange(IModelChange)}.
+ * The IModelChange instance provided must be 1) not <code>null</code>; and 2) Of a type that is
+ * appropriate for this synchronization strategy.</li>
+ * <li>Process A should take the resulting {@link IModelChangeMessage}, serialize it (by
+ * calling {@link IModelChangeMessage#serialize()} and send the message to remote
+ * processes (i.e. B).
+ * </li>
+ * <li>
+ * Process B should take the received byte array and call {@link #deserializeRemoteChange(byte[])}
+ * to create an IModelChange instance.
+ * </li>
+ * <li>
+ * Process B should then pass the IModelChange instance to {@link #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 {@link #transformRemoteChange(IModelChange)} metho
+ * will take the local changes (previously registered with the synchronization strategy via
+ * {@link #registerLocalChange(IModelChange)}), and the remote changes provided via
+ * {@link #transformRemoteChange(IModelChange)},
+ * and transform the changes into a set that will result in a synchronized local copy.
+ * </li>
+ * </ul>
+ */
public interface IModelSynchronizationStrategy {
/**
* 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.
- * @param localChange the IModelChange made to the local model
+ * @param localChange the IModelChange made to the local model. Must be non-<code>null</code>,
+ * and must be of type appropriate for the synchronization strategy.
* @return IModelChangeMessage[] an array of change message to be
- * delivered to remote participants.
+ * 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).
*/
public IModelChangeMessage[] registerLocalChange(IModelChange localChange);

Back to the top