Skip to content

Commit 1ca7e5b

Browse files
AxelRICHARDAxelRICHARD
committed
[doc] Add ADR about services organization
Signed-off-by: Axel RICHARD <axel.richard@obeo.fr>
1 parent f2f3ed1 commit 1ca7e5b

3 files changed

Lines changed: 105 additions & 4 deletions

File tree

‎CHANGELOG.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
- https://github.com/eclipse-syson/syson/issues/1581[#1581] [diagrams] Display inherited ports as border nodes in diagrams.
88

9+
=== Architectural decision records
10+
11+
- [ADR-002] Services organization
12+
913
=== Breaking changes
1014

1115
=== Dependency update

‎doc/adrs/001_support_direct_edit_in diagrams.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,6 @@ It will be used to create grammars dedicated to parse these complex cases.
3232
The first use case will be the direct edit of all `Usage` elements (`AttributeUsage`, `PartUsage`, `PortUsage`, ...) that are represented as compartment nodes inside node containers.
3333
Other use cases (unknown at the moment) may also use the same grammar or new ones depending on the context.
3434

35-
== Status
36-
37-
To be reviewed.
38-
3935
== Consequences
4036

4137
`syson-diagram-general-view` will depend on `antlr4-runtime` as maven dependency.
@@ -45,3 +41,7 @@ SysON will keep its version of ANTLR synchronized with the Sirius Web one.
4541
== References
4642

4743
- https://www.antlr.org/
44+
45+
== Status
46+
47+
Accepted.

‎doc/adrs/002_services_organization.adoc‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
= ADR-002 - Services organization
2+
3+
== Context
4+
5+
In SysON, we have a lot of services that are used in different places.
6+
Some services query the model, some other services modify the model.
7+
Some services query the diagram/table, some other services modify the diagram/table.
8+
Some services are a mix of both querying/modifying.
9+
Some services are called by AQL expressions, some other services are called by Java code.
10+
Some services classes are spring @Service, some other services classes are not.
11+
12+
With many contributors since the beginning of the project, and not a clear and precise guide on how to add new services, the services are not always in the right place, and there are many services classes everywhere in the code base.
13+
14+
All those points make it difficult to find a service, to know where to add a new service, to know where to find a service that does something similar to what we want to do.
15+
16+
== Decision
17+
18+
At this point, we need to organize all these services in a more logical way.
19+
The decision is to create a clear organization of the services in packages and classes.
20+
The main idea is to have services grouped by their purpose and usage.
21+
22+
- Services that query/mutate the model will be located in the new module `syson-sysml-metamodel-services`.
23+
- this module will depend on `syson-sysml-metamodel`.
24+
- all services in this module won't depend on Spring, Sirius-Web or any diagram/table related code.
25+
- Services that query/mutate the model through Sirius-Web services will be located in the new module `syson-model-services`.
26+
- all services in this module will be allowed to depend on Sirius-Web
27+
- for example, services that query the model through `IObjectSearchService`.
28+
- Services that query/mutate a diagram will be located in the new module `syson-diagram-services`.
29+
- all services in this module will be allowed to depend on Sirius-Web.
30+
- Services that query/mutate a table will be located in the new module `syson-table-services`.
31+
- all services in this module will be allowed to depend on Sirius-Web.
32+
- Services that query/mutate a tree will be located in the new module `syson-tree-services`.
33+
- all services in this module will be allowed to depend on Sirius-Web.
34+
- Services that query/mutate a form will be located in the new module `syson-form-services`.
35+
- all services in this module will be allowed to depend on Sirius-Web.
36+
- Services that query/mutate and are transversal/common to any representation will be located in the new module `syson-representation-services`.
37+
- all services in this module will be allowed to depend on Sirius-Web.
38+
- will contain services that can be used in all representations
39+
40+
- Services will be grouped in classes by their purpose and usage.
41+
- a service that query the model will be in a class named `SomethingQueryService`.
42+
- a service that mutate the model will be in a class named `SomethingMutationService`.
43+
- a service that query the diagram will be in a class named `DiagramQueryService`.
44+
- a service that mutate the diagram will be in a class named `DiagramMutationService`.
45+
- a service querying label of diagram elements will be in a class named `DiagramLabelQueryService`.
46+
- a service modifying the label of diagram elements will be in a class named `DiagramLabelMutationService`.
47+
- a service querying label of diagram elements will be in a class named `LabelDiagramQueryService`.
48+
- a service modifying the label of elements will be in a class named `LabelDiagramMutationService`.
49+
- `SomethingQueryService` and `SomethingMutationService` classes can be split in smaller classes if they contain too many services.
50+
51+
- Only two services classes per module will be the entry points for services that are intended to be called from AQL expressions
52+
- these classes will contain services that are intended to be called from AQL expressions.
53+
- they will be suffixed by _AQLService_.
54+
- their only role will be to expose services from other service classes.
55+
- other service classes won't be suffixed by _AQLService_ and will contain services that are intended to be called from Java code or by _AQLService_ classes.
56+
57+
- The initial categories of services could be (initial list to be defined and refined later):
58+
- `syson-sysml-metamodel-services`
59+
- Usage
60+
- Definition
61+
- Any other category needed in the future like Part, Action...
62+
- `syson-model-services`
63+
- Create
64+
- Delete
65+
- Move
66+
- DragAndDrop
67+
- `syson-diagram-services`
68+
- GeneralView
69+
- InterconnectionView
70+
- ActionFlowView
71+
- StateTransitionView
72+
- Label
73+
- DirectEdit
74+
- Node
75+
- Edge
76+
- `syson-table-services`
77+
- RequirementsView
78+
- Row
79+
- Column
80+
- Cell
81+
- `syson-tree-services`
82+
- Tree
83+
- TreeItem
84+
- `syson-form-services`
85+
- Widget
86+
- `syson-representation-services`
87+
- Expose
88+
89+
Finally, the development guidelines will be updated to explain this new organization and how to add new services following this organization.
90+
README files will be added in each module to explain the purpose of the module and how to add new services in it.
91+
92+
== Consequences
93+
94+
A lot of services will be moved from their current location to the new ones.
95+
The breaking changes section of the changelog will be updated to inform users of these changes.
96+
All new services will have to follow this organization.
97+

0 commit comments

Comments
 (0)