plugins/doc/org.eclipse.papyrus.siriusdiag.doc/src/site/mediawiki/siriusdiag-devDoc.mediawiki - papyrus/org.eclipse.papyrus-sirius - Git at Google

 =Papyrus-Sirius Developer Guides=
 Basically, the developement rules are the same than for Papyrus.
 ==Java Code Style==
 The recommendation are almost the same than for Papyrus. We reuse its Code Style configurations for '''Clean Up''' and '''Formatter'''.
 Concerning the '''Code Templates''', we did these changes:
 * Comment > Files : we register the Papyrus default file header
 * Comment > Types : we removed the @{user}
 * Comment > Modules : we removed the @{user}
 * Code > Constructor, we removed the todo

 These 3 templates files are stored into the git org.eclipse.papyrus-sirius, into the folder '''releng-sirius/templates'''.

 ==Plug-in Preferences==
 We provide pre-configured preferences files to copy in the .settings folder (it is a hidden folder by default) in each new plugin. There are 6 files to copy:
 * org.eclipse.core.resources.prefs
 * org.eclipse.core.runtime.prefs
 * org.eclipse.jdt.core.prefs
 * org.eclipse.jdt.ui.prefs
 * org.eclipse.pde.api.tools.prefs
 * org.eclipse.pde.prefs
 These preferences files can be copied from '''releng-sirius/preferences''' into the '''.setting''' folder of your new plugin.

 ==Eclipse.ini==
 Add your user name as vmargs argument like that in order to get a nice file header for the new creted file:


 ''-vmargs''

 ''-Duser.name=John Doe (Company) <john.doe@company.com>''

 ==Manifest.ini==
 Rules:
 *we avoid to use '''Import Package'''
 *each dependency is defined with a min and max values
 *the dependencies are sorted by alphabetical order


 = Architecture of Papyrus-SiriusDiag =
 This framework has been developed to be used only when a sirius diagram is opened.

 ==Git Architecture==
 *'''plugins/infra/siriusdiag'''
 **'''modelexplorer''':contains code allowing to display and use sirius diagram in the papyrus model explorer
 **'''properties''': contains code to visualize the properties of sirius diagrams
 **'''representation''': contains the code to create sirius diagram views
 **'''representation.architecture''': contains the code to create specific sirius diagram
 **'''representation.edit''': plugin defining sirius diagram prototype
 **'''sirius''': plugin containing sirius services to handle session
 **'''siriusdiag.ui''': plugin handling sirius diagram views and session management

 *'''plugins\uml\sirius'''
 **'''clazz.diagram''': contains class diagram description and services
 **'''common.diagram''': contains all the common services that can be used by all diagrams
 **'''diagram.architecture''': contains all the common services that can be used by all diagrams
 **'''sequence.diagram''': contains sequence diagram description and services
 **'''statemachine.diagram''': contains statemachine diagram description and services
 **'''xtext.integration.ui''': contains customization to add xtext on label edition

 = odesign file conception rules =
 To ease development and review, we decided to follow conception rules for odesign file:
 *structure of the odesign:
 **all elements are organized by alphabetical order (following the label displayed in the odesign editor)

 *''id'' field rules:
 ** doesn't contents space
 ** contains the name of the semantic element
 ** tool for creation must be named following this pattern ''CreateXXXTool''
 ** tool for semantic drop must be named following this pattern ''SemanticXXXDrop''
 ** tool for graphical drop must be named following this pattern ''GraphicalXXXDrop''
 ** mapping representing a label node must be suffixed with ''LabelNode''
 ** mapping representing a compartment node must be named like this: ''parentMappingName'' + ''ElementNames''(plural form) + ''Compartment'', example: '''CD_ClassAttributesCompartment'''

 *''node'' rules:
 ** all nodes containing objects must have compartments
 ** all nodes must be described at the root of the layer: we avoid defining nodes inside another nodes (this rule is not applicable for bordered nodes.

 *''palette'' rules:
 ** the palette will contains 2 folders, one for nodes, named '''Nodes''', one for edges, named '''Edges'''.
 ** in these folder, the tools will be sorted by alphabetical order

 *''icon'' rules:
 **the path of the icon of semantic UML element must be something like '''/org.eclipse.uml2.uml.edit/icons/full/obj16/xxx.yyy''' each time it exists. We must avoid to duplicate icons when it is not necessary.

 *''validation'' rules:
 **the *.odesign files must be valid (using EMF Validation)

 = Sirius viewpoint =

 Each new diagram contribution is added in a new plugin, which contains the description of the mapping, the filters and the tools available for this diagram.

 For more information about viewpoint description, you can have a look at the sirius documentation available here:
 https://www.eclipse.org/sirius/doc/specifier/general/Specifying_Viewpoints.html

 Note that each viewpoint shall reuse:
 * The common layer which is a mandatory layer defining the common concept of all diagrams (Bendpoint for example).
 * The common tool, for deletion, etc.
 * Common and specific java services.

 = Adding a new diagram to the architecture file =

 The editor provided to edit the DocumentStructureTemplate metamodel is not exactly the version generated by EMF. We customized it in order to use a TransactionalEditingDomain (to ease the Papyrus integration).

 When we add a new Sirius diagram, we shall create a new Sirius diagram prototype:

 [[File:../../../image/dev/1_ViewCreation.png]]

 Once the Sirius Diagram Prototype has been created, it shall be defined as in the following picture:

 [[File:../../../image/dev/5_DefineRepresentation.png]]

 To be able to reference the corresponding Diagram Description, it shall first be loaded in order to reference it. This can be done as in the following image:

 [[File:../../../image/dev/2_LoadViewpoint.png]]

 And select the corresponding *.odesign file using the Browse Workspace:

 [[File:../../../image/dev/2_SelectOdesign.png]]

 Once the Sirius Diagram Prototype has been created. We shall select on which viewpoint this representation shall be allowed. To do this, select the viewpoint and add a Representation Kinds:

 [[File:../../../image/dev/4_AddRespresentation.png]]

 And simply select the diagram prototype that was created on the previous step.

 [[File:../../../image/dev/3_RegisterRepresentation.png]]

 This shall be done for both Analysis and Design viewpoint.

 == Adding the creation command==

 In the org.eclipse.papyrus.infra.siriusdiag.representation.architecture plugin, a new class extending the AbstractCreateSiriusDiagramEditorCommand shall be created. This class will manage the condition of the creation of the diagram and the action to execute before creating it depending on the context.

 For example, a sequence diagram can be created directly under an interaction without prior action, but if we want to create it under a Model, an interaction shall be created before and defined as the root of the diagram.

 = Sirius session management =

 To use the same transactional editing domain than other papyrus services, we had to override the default sirius session and creation. This is done by the PapyrusSessionFactory which allows to create PapyrusSession (which are just sirius session with the right TransactionalEditingDomain).

 For new services using session, it is recommanded to use the SessionService provided in the org.eclipse.papyrus.infra.siriusdiag.ui plugin.

 = API To find creatable Sirius Diagram Prototype =
 From a selected EObject, we want to find all SiriusDiagramViewPrototype and store them into a list:

 <source>
 List<ViewPrototype> data = new ArrayList<>();
 for (final ViewPrototype proto : PolicyChecker.getFor(selection).getPrototypesFor(selection)) {
 	if (proto instanceof SiriusDiagramViewPrototype && proto.getRepresentationKind() instanceof SiriusDiagramPrototype) {
 		final SiriusDiagramViewPrototype siriusPrototype = (SiriusDiagramViewPrototype) proto;

 		//additional check not yet done by the PolicyChecker
 		if (siriusPrototype.canInstantianteOn(selection)) {
 			data.add(proto);
 		}
 	}
 }</source>


 = Common Diagram =

 == Common concepts ==

 === Bendpoints ===

 Benpoints mapping is used to draw a Benpoint node at the intersection of edges when the Benpoints filter is activated.

 === Refresh provider ===

 In some sirius diagrams, for several purpose (region management, bendpoints and sequence diagram reorder), the post refresh behavior of sirius diagrams have been overriden.

 To override this behavior, we have used the following extension point org.eclipse.sirius.refreshExtensionProvider.

 === Common services ===

 * PapyrusSiriusTabbarContributor allows to enable or deactivate tools in the sirius tabbar.

 [[File:../../../image/dev/6_SiriusTabbar.png]]

 * AbstractDiagramServices is used to manage Label node label, node creation and node drag and drop tools.

 * AddElementToDiagramServices handles precondition for creation tool.

 * LabelServices handles direct edition of labels.

 * TooltipServices helps to provide a tooltip for each tools of the palette.

 * DeleteFromModelHandler handles the deletion of semantic element.

 = Class Diagram =

 The class diagram code is located in the
 org.eclipse.papyrus.uml.sirius.clazz.diagram plugin.

 == Services==

 * ClassDiagramServices handles services used by tools of the class diagram for creation, reconnection, etc.

 == Description ==

 The diagram description is located in the papyrus_class.odesign:

 The Class layer defines all the mapping and tools specific to the class diagram:
 * NodeContainer, Node, Edge and BorderedNode mapping.
 * The style of each node
 * The Nodes tool section define the Nodes palette tools behavior, which are mostly creation tools.
 * The Edges tool section define the Edges palette tools behavior, which are mostly creation tools.
 * The Features tool section define the drag and drop from model and from representations, tools for the label edition and tools for deletion.
 * The Relationships tool section define the reconnection tools and some deletion tools.

 = State Machine Diagram =

 The State Machine diagram code is located in the
 org.eclipse.papyrus.uml.sirius.statemachine.diagram plugin.

 == Services ==

 To handle the specific behavior of Region, since both VerticalStack or HorizontalStack children presentations could not handle the mixed behavior of region (sometimes vertical and sometimes horizontal). Hence, the Freeform children presentation is used combined to a manageRegionPresentation and setChildRepresentation method that allows to chose between either horizontal and vertical.

 == Description ==

 The diagram description is located in the papyrus_statemachine.odesign:

 The State Machine layer defines all the mapping and tools specific to the state machine diagram:
 * NodeContainer, Node, Edge and BorderedNode mapping.
 * The style of each node.
 * The Nodes tool section define the Nodes palette tools behavior (mostly creation tools), drag and drop from model or from representation tools, label edition tools and deletion tools.
 * The Edges tool section define the Edges palette tools behavior (mostly creation tools) and reconnection tools.

 = Sequence Diagram =

 The Sequence diagram code is located in the
 org.eclipse.papyrus.uml.sirius.sequence.diagram plugin.

 == Services ==

 * Each services available in org.eclipse.papyrus.uml.sirius.sequence.diagram.services refers to one kind of element and handles the creation, reconnection and precondition for tools linked to this element.

 * ReorderSequenceRegistry, ReorderService and RefreshSequenceExtensionProvider are used to handle the reordering of all the diagram when moving elements.

 == Description ==

 The diagram description is located in the papyrus_sequence.odesign:

 The Sequence layer defines all the mapping and tools specific to the Sequence diagram:
 * InstanceRole, NodeContainer, Node, Edge, BorederedNode, Execution, State, CombinedFragment, InteractionUse and ObservationPoint mapping.
 * The style of each mapping.
 * The Nodes tool section define the Nodes palette tools behavior (mostly creation tools) and label edition tools.
 * The Edges tool section define the Edges palette tools behavior (mostly creation tools).
 * The Tools tool section define reconnection tools, reodering tools, label edition tools and deletion tools.

 = Xtext integration =

 Code in org.eclipse.papyrus.uml.sirius.xtext.integration.ui override classic editpart to add an xtext parser on each label edition.

 = Test coverage =

 The common method to create new tests for sirius diagram is located in org.eclipse.papyrus.siriusdiag.junit.utils. In this plugin, the SiriusDiagramEditorFixture provide all the method to load model, ope session, tests tools that will be used in the several test case.

 Each specific diagram is tested in a specific plugin. Those tests include:
 * Diagram creation
 * Diagram deletion
 * Creation tools tests
 * Drag and Drop tools tests
 * Deletion
	=Papyrus-Sirius Developer Guides=
	Basically, the developement rules are the same than for Papyrus.
	==Java Code Style==
	The recommendation are almost the same than for Papyrus. We reuse its Code Style configurations for '''Clean Up''' and '''Formatter'''.
	Concerning the '''Code Templates''', we did these changes:
	* Comment > Files : we register the Papyrus default file header
	* Comment > Types : we removed the @{user}
	* Comment > Modules : we removed the @{user}
	* Code > Constructor, we removed the todo

	These 3 templates files are stored into the git org.eclipse.papyrus-sirius, into the folder '''releng-sirius/templates'''.

	==Plug-in Preferences==
	We provide pre-configured preferences files to copy in the .settings folder (it is a hidden folder by default) in each new plugin. There are 6 files to copy:
	* org.eclipse.core.resources.prefs
	* org.eclipse.core.runtime.prefs
	* org.eclipse.jdt.core.prefs
	* org.eclipse.jdt.ui.prefs
	* org.eclipse.pde.api.tools.prefs
	* org.eclipse.pde.prefs
	These preferences files can be copied from '''releng-sirius/preferences''' into the '''.setting''' folder of your new plugin.

	==Eclipse.ini==
	Add your user name as vmargs argument like that in order to get a nice file header for the new creted file:


	''-vmargs''

	''-Duser.name=John Doe (Company) <john.doe@company.com>''

	==Manifest.ini==
	Rules:
	*we avoid to use '''Import Package'''
	*each dependency is defined with a min and max values
	*the dependencies are sorted by alphabetical order


	= Architecture of Papyrus-SiriusDiag =
	This framework has been developed to be used only when a sirius diagram is opened.

	==Git Architecture==
	*'''plugins/infra/siriusdiag'''
	**'''modelexplorer''':contains code allowing to display and use sirius diagram in the papyrus model explorer
	**'''properties''': contains code to visualize the properties of sirius diagrams
	**'''representation''': contains the code to create sirius diagram views
	**'''representation.architecture''': contains the code to create specific sirius diagram
	**'''representation.edit''': plugin defining sirius diagram prototype
	**'''sirius''': plugin containing sirius services to handle session
	**'''siriusdiag.ui''': plugin handling sirius diagram views and session management

	*'''plugins\uml\sirius'''
	**'''clazz.diagram''': contains class diagram description and services
	**'''common.diagram''': contains all the common services that can be used by all diagrams
	**'''diagram.architecture''': contains all the common services that can be used by all diagrams
	**'''sequence.diagram''': contains sequence diagram description and services
	**'''statemachine.diagram''': contains statemachine diagram description and services
	**'''xtext.integration.ui''': contains customization to add xtext on label edition

	= odesign file conception rules =
	To ease development and review, we decided to follow conception rules for odesign file:
	*structure of the odesign:
	**all elements are organized by alphabetical order (following the label displayed in the odesign editor)

	*''id'' field rules:
	** doesn't contents space
	** contains the name of the semantic element
	** tool for creation must be named following this pattern ''CreateXXXTool''
	** tool for semantic drop must be named following this pattern ''SemanticXXXDrop''
	** tool for graphical drop must be named following this pattern ''GraphicalXXXDrop''
	** mapping representing a label node must be suffixed with ''LabelNode''
	** mapping representing a compartment node must be named like this: ''parentMappingName'' + ''ElementNames''(plural form) + ''Compartment'', example: '''CD_ClassAttributesCompartment'''

	*''node'' rules:
	** all nodes containing objects must have compartments
	** all nodes must be described at the root of the layer: we avoid defining nodes inside another nodes (this rule is not applicable for bordered nodes.

	*''palette'' rules:
	** the palette will contains 2 folders, one for nodes, named '''Nodes''', one for edges, named '''Edges'''.
	** in these folder, the tools will be sorted by alphabetical order

	*''icon'' rules:
	**the path of the icon of semantic UML element must be something like '''/org.eclipse.uml2.uml.edit/icons/full/obj16/xxx.yyy''' each time it exists. We must avoid to duplicate icons when it is not necessary.

	*''validation'' rules:
	*the .odesign files must be valid (using EMF Validation)

	= Sirius viewpoint =

	Each new diagram contribution is added in a new plugin, which contains the description of the mapping, the filters and the tools available for this diagram.

	For more information about viewpoint description, you can have a look at the sirius documentation available here:
	https://www.eclipse.org/sirius/doc/specifier/general/Specifying_Viewpoints.html

	Note that each viewpoint shall reuse:
	* The common layer which is a mandatory layer defining the common concept of all diagrams (Bendpoint for example).
	* The common tool, for deletion, etc.
	* Common and specific java services.

	= Adding a new diagram to the architecture file =

	The editor provided to edit the DocumentStructureTemplate metamodel is not exactly the version generated by EMF. We customized it in order to use a TransactionalEditingDomain (to ease the Papyrus integration).

	When we add a new Sirius diagram, we shall create a new Sirius diagram prototype:

	[[File:../../../image/dev/1_ViewCreation.png]]

	Once the Sirius Diagram Prototype has been created, it shall be defined as in the following picture:

	[[File:../../../image/dev/5_DefineRepresentation.png]]

	To be able to reference the corresponding Diagram Description, it shall first be loaded in order to reference it. This can be done as in the following image:

	[[File:../../../image/dev/2_LoadViewpoint.png]]

	And select the corresponding *.odesign file using the Browse Workspace:

	[[File:../../../image/dev/2_SelectOdesign.png]]

	Once the Sirius Diagram Prototype has been created. We shall select on which viewpoint this representation shall be allowed. To do this, select the viewpoint and add a Representation Kinds:

	[[File:../../../image/dev/4_AddRespresentation.png]]

	And simply select the diagram prototype that was created on the previous step.

	[[File:../../../image/dev/3_RegisterRepresentation.png]]

	This shall be done for both Analysis and Design viewpoint.

	== Adding the creation command==

	In the org.eclipse.papyrus.infra.siriusdiag.representation.architecture plugin, a new class extending the AbstractCreateSiriusDiagramEditorCommand shall be created. This class will manage the condition of the creation of the diagram and the action to execute before creating it depending on the context.

	For example, a sequence diagram can be created directly under an interaction without prior action, but if we want to create it under a Model, an interaction shall be created before and defined as the root of the diagram.

	= Sirius session management =

	To use the same transactional editing domain than other papyrus services, we had to override the default sirius session and creation. This is done by the PapyrusSessionFactory which allows to create PapyrusSession (which are just sirius session with the right TransactionalEditingDomain).

	For new services using session, it is recommanded to use the SessionService provided in the org.eclipse.papyrus.infra.siriusdiag.ui plugin.

	= API To find creatable Sirius Diagram Prototype =
	From a selected EObject, we want to find all SiriusDiagramViewPrototype and store them into a list:

	<source>
	List<ViewPrototype> data = new ArrayList<>();
	for (final ViewPrototype proto : PolicyChecker.getFor(selection).getPrototypesFor(selection)) {
	if (proto instanceof SiriusDiagramViewPrototype && proto.getRepresentationKind() instanceof SiriusDiagramPrototype) {
	final SiriusDiagramViewPrototype siriusPrototype = (SiriusDiagramViewPrototype) proto;

	//additional check not yet done by the PolicyChecker
	if (siriusPrototype.canInstantianteOn(selection)) {
	data.add(proto);
	}
	}
	}</source>


	= Common Diagram =

	== Common concepts ==

	=== Bendpoints ===

	Benpoints mapping is used to draw a Benpoint node at the intersection of edges when the Benpoints filter is activated.

	=== Refresh provider ===

	In some sirius diagrams, for several purpose (region management, bendpoints and sequence diagram reorder), the post refresh behavior of sirius diagrams have been overriden.

	To override this behavior, we have used the following extension point org.eclipse.sirius.refreshExtensionProvider.

	=== Common services ===

	* PapyrusSiriusTabbarContributor allows to enable or deactivate tools in the sirius tabbar.

	[[File:../../../image/dev/6_SiriusTabbar.png]]

	* AbstractDiagramServices is used to manage Label node label, node creation and node drag and drop tools.

	* AddElementToDiagramServices handles precondition for creation tool.

	* LabelServices handles direct edition of labels.

	* TooltipServices helps to provide a tooltip for each tools of the palette.

	* DeleteFromModelHandler handles the deletion of semantic element.

	= Class Diagram =

	The class diagram code is located in the
	org.eclipse.papyrus.uml.sirius.clazz.diagram plugin.

	== Services==

	* ClassDiagramServices handles services used by tools of the class diagram for creation, reconnection, etc.

	== Description ==

	The diagram description is located in the papyrus_class.odesign:

	The Class layer defines all the mapping and tools specific to the class diagram:
	* NodeContainer, Node, Edge and BorderedNode mapping.
	* The style of each node
	* The Nodes tool section define the Nodes palette tools behavior, which are mostly creation tools.
	* The Edges tool section define the Edges palette tools behavior, which are mostly creation tools.
	* The Features tool section define the drag and drop from model and from representations, tools for the label edition and tools for deletion.
	* The Relationships tool section define the reconnection tools and some deletion tools.

	= State Machine Diagram =

	The State Machine diagram code is located in the
	org.eclipse.papyrus.uml.sirius.statemachine.diagram plugin.

	== Services ==

	To handle the specific behavior of Region, since both VerticalStack or HorizontalStack children presentations could not handle the mixed behavior of region (sometimes vertical and sometimes horizontal). Hence, the Freeform children presentation is used combined to a manageRegionPresentation and setChildRepresentation method that allows to chose between either horizontal and vertical.

	== Description ==

	The diagram description is located in the papyrus_statemachine.odesign:

	The State Machine layer defines all the mapping and tools specific to the state machine diagram:
	* NodeContainer, Node, Edge and BorderedNode mapping.
	* The style of each node.
	* The Nodes tool section define the Nodes palette tools behavior (mostly creation tools), drag and drop from model or from representation tools, label edition tools and deletion tools.
	* The Edges tool section define the Edges palette tools behavior (mostly creation tools) and reconnection tools.

	= Sequence Diagram =

	The Sequence diagram code is located in the
	org.eclipse.papyrus.uml.sirius.sequence.diagram plugin.

	== Services ==

	* Each services available in org.eclipse.papyrus.uml.sirius.sequence.diagram.services refers to one kind of element and handles the creation, reconnection and precondition for tools linked to this element.

	* ReorderSequenceRegistry, ReorderService and RefreshSequenceExtensionProvider are used to handle the reordering of all the diagram when moving elements.

	== Description ==

	The diagram description is located in the papyrus_sequence.odesign:

	The Sequence layer defines all the mapping and tools specific to the Sequence diagram:
	* InstanceRole, NodeContainer, Node, Edge, BorederedNode, Execution, State, CombinedFragment, InteractionUse and ObservationPoint mapping.
	* The style of each mapping.
	* The Nodes tool section define the Nodes palette tools behavior (mostly creation tools) and label edition tools.
	* The Edges tool section define the Edges palette tools behavior (mostly creation tools).
	* The Tools tool section define reconnection tools, reodering tools, label edition tools and deletion tools.

	= Xtext integration =

	Code in org.eclipse.papyrus.uml.sirius.xtext.integration.ui override classic editpart to add an xtext parser on each label edition.

	= Test coverage =

	The common method to create new tests for sirius diagram is located in org.eclipse.papyrus.siriusdiag.junit.utils. In this plugin, the SiriusDiagramEditorFixture provide all the method to load model, ope session, tests tools that will be used in the several test case.

	Each specific diagram is tested in a specific plugin. Those tests include:
	* Diagram creation
	* Diagram deletion
	* Creation tools tests
	* Drag and Drop tools tests
	* Deletion