asciidoc/Developer-documentation.asciidoc

@@ -11,7 +11,7 @@ is for you.
 
 When invoking the Generator, it will (roughly) perform the following actions:
 
-[#invocation_workflow]
+[[invocation_workflow]]
 .Basic invocation workflow
 image::invocation_workflow.png[width=90%, align=center, link={imagesdir}/invocation_workflow.png]
 
@@ -144,9 +144,10 @@ To solve this issue, the _EMF_ types need to be mapped to their Java-equivalents
 `EmfTypeTranslator` should be used for. Its `getSClassFromEmf` method will provide the matching
 types for all _EMF_ wrappers and nothing for all other classes.
 
-=== Modifying `SModel` instances
+=== Modifying `SModel` instances [[modifying_instances]]
 
-To change the contents of a `SModel`, the whole _ACR_ implements the _Visitor pattern_footnote:[https://en.wikipedia.org/wiki/Visitor_pattern].
+To change the contents of a `SModel`, the whole _ACR_ implements the
+__Visitor pattern__footnote:[https://en.wikipedia.org/wiki/Visitor_pattern].
 This approach is used by the whole <<invocation_workflow,Generator workflow>>.
 
 More precisely the following __Visitor__s are predefined:
@@ -160,4 +161,40 @@ More precisely the following __Visitor__s are predefined:
 
 == Preparing a model for synchronization
 
+When creating JVM bytecode for _EMF_ models, the Generator cannot just convert the model to Scala
+code and compile it. Instead, it has to make various preparations as the resulting (compiled) Scala
+code has to meet a number of requirements. These are necessary to make the code runnable in a
+_Synchronization context_ and work as expected, i.e. synchronize its state with a number of other
+models.
+
+These requirements are:
+
+* each synchronized instance has to extend the `PlayerSync` class
+* when any constructor is invoked, it has to call the `buildClass` method. This method takes care
+  of notifying the _Synchronization context_ and setting up the necessary roles. It is provided
+  by the `PlayerSync` class
+* every time a _Setter_ is called, it has to notify the _Synchronization context_ about the change
+  performed
+
+An _EMF_ model will usually not meet any of them as it was generated without synchronization in
+mind. Furthermore some difficulties are introduced by Scala as the target programming language:
+
+* Scala provides a special notation for _Getters_ and _Setters_. However in the current reference
+  implementation of the Synchronization this is not used. Instead fields are accessed by _Getters_
+  and _Setters_ in the usual Java-way.
+* The same goes for constructors - there are multiple ways of defining constructors and different
+  notations have to be used. Again we do not consider these and only create one full constructor.
+
+The necessary preparations will be carried out through the visitors mentioned in
+<<modifying_instances>>. In short there are two visitors used: the
+`GetterSetterGeneratingVisitor` for general setup and the `SyncEnhancingVisitor` for the
+modifications specific to synchronization. It is important to run the general visitor first to
+ensure that all classes contain setter methods. These will than be augmented by the second visitor.
+
+WARNING: The Synchronization demo also expects some configuration classes for the model (namely
+`DisplayableModel` instances for the models as well as a `ModelSyncProvider`). These are currently
+not generated automatically. Thus they need to be added to the JAR manually.
+
+NOTE: Generating these classes is currently being worked on.
+
 == Writing to the File system [[compilation]]