updated documentation about IEngineAddon interface

contributes to
eclipse-gemoc/gemoc-studio-modeldebugging#151

Signed-off-by: Didier Vojtisek <[email protected]>

docs/org.eclipse.gemoc.studio.doc/src/main/asciidoc/dev/DevelopingNewAddons.asciidoc

@@ -20,6 +20,7 @@ Basically, it uses Eclipse plugin extension point in order to provide additional
 The main extension point is `org.eclipse.gemoc.gemoc_language_workbench.engine_addon` which allows to declare a new class that implements the `IEngineAddon` interface.
 
 
+===== Create an Addon
 
 Minimal steps to get an addons:
 
@@ -39,43 +40,83 @@ image::images/dev/New_Extension_4_Engine_Addon_screenshot.png["New Extension for
 .EngineAddon extension point details screenshot
 image::images/dev/EngineAddon_extension_point_details_screenshot.png["EngineAddon extension point details screenshot"]
 
-[NOTE]
+[TIP]
 ====
-The calls from the engine to the methods of IEngineAddons block the model execution. Thus, except if this is the expected behavior, the addons  should avoid to do complex/long running/blocking task directly in the  
-====   
+An Engine addon may be generic and apply to any language, but it can also be 
+language specific. In that case, you should prefer to add its code in the project 
+containing the dsl file of the language and declare it in the plugin.xml.
 
 
-[NOTE]
-====
-For a given notification to IEngineAddon (for example aboutToExecuteStep), the order of calls to all registered addons is currently not ensured. 
+This way, the addon will be available only for this specific language.
 
-Help is welcome in order to implement a way to specify partial order between addons as it might be useful when several collaborating addons must react on the same notification. 
-====  
+[[img-add_engine_addons_on_dsl]]
+.Add language specific Engine Addon on DSL 
+image::images/dev/New_Extension_4_Engine_Addon_in_dsl_screenshot.png["Add language specific Engine Addon on DSL", 700]
 
+This can be useful in order to create language specific GUI (with input/output) 
+and complex model animation. (see <<define-animation-representation-using-engine-addon-section>>)
+====
 
 [TIP]
 ====
 In the extension declaration, setting _Default_ to _true_ will activate the addon by default when creating a new launch configuration. The user is still able to disable the addon manually.
 ==== 
 
-[TIP]
+
+===== Controling call to addon
+
+[NOTE]
 ====
-See <<devguide-gemoc-frameworks>> for more details about the extension point and other supported features.
-==== 
+The calls from the engine to the methods of IEngineAddons block the model execution. Thus, except if this is the expected behavior, the addons  should avoid to do complex/long running/blocking task directly in the  
+====   
+
+
+
+For a given notification to _IEngineAddon_ (for example aboutToExecuteStep), the order of calls to all registered addons is by default not ensured.
+
+However,  an addon can declare some _EngineAddonSortingRule_ in order to indicate if the addon mus be called before or after another addon for a given _EngineEvent_.
+
+The other addon can be identified either via its id or any tag that has been associated to it. 
 
 [TIP]
 ====
-An Engine addon may be generic and apply to any language, but it can also be 
-language specific. In that case, you should prefer to add its code in the project 
-containing the dsl file of the language and declare it in the plugin.xml.
+When starting a model execution the console logs some informations about which addon has been enabled and when each addon will be called compared to other addons.
+==== 
 
 
-This way, the addon will be available only for this specific language.
+The implicit GemocDebug addon is in charge to lock the execution when it receives a pause command.
+Addons that displays some information on the UI may wish to be called before it in order to make sure to provide
+updated information.
+
+This snippet show how to add a rule that enforce this.
+[source,java]
+----
+
+public class MyAddon implements IEngineAddon {
+
+	@Override
+	public void aboutToExecuteStep(IExecutionEngine<?> engine, Step<?> logicalStepToApply) {
+		// do some refresh action 
+	}
+	
+	@Override
+	public List<EngineAddonSortingRule> getAddonSortingRules() {  <1>
+		ArrayList<EngineAddonSortingRule> sortingRules = new ArrayList<EngineAddonSortingRule>();
+		sortingRules.add(new EngineAddonSortingRule( this,
+				EngineAddonSortingRule.EngineEvent.aboutToExecuteStep,
+				EngineAddonSortingRule.Priority.BEFORE,
+				Arrays.asList(IGemocDebugger.GROUP_TAG))); <2>
+		return sortingRules;
+	}
+}
+----
+<1> create a rule to ensure good behavior with GemocDebugger. The debugger addon will stop the execution in this event, this make sure to be called before it in order to properly do the task (refresh the view, save info, etc)
+<2> use the group tag so this rule will work with any GemocDebugger implementation.
+
 
-[[img-add_engine_addons_on_dsl]]
-.Add language specific Engine Addon on DSL 
-image::images/dev/New_Extension_4_Engine_Addon_in_dsl_screenshot.png["Add language specific Engine Addon on DSL", 700]
 
-This can be useful in order to create language specific GUI (with input/output) 
-and complex model animation. (see <<define-animation-representation-using-engine-addon-section>>)
-====
+[TIP]
+====
+See <<devguide-gemoc-frameworks>> for more details about the extension point and other supported features.
+==== 
+