Copyright © 2008, 2020 Obeo – All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0
Authors Stéphane Thibaudeau, Vincent Richard
Contacts [email protected], [email protected]
SOA Designer permet de modéliser des composants métiers, avec leurs services et les structure de données qu’ils manipulent (Data Transfer Objects).
SOA Designer apporte le point de vue SOA Views qui permet de :
- Modéliser les composants et les liens entre eux,
- Modéliser les contrats des composants (interfaces et services),
- Modéliser les DTOs, leur structure et les relations entre eux,
- Organiser les DTOs en packages,
- Modéliser l’exposition REST des services et gérer le format Open API (Swagger).
Un assistant permet la création de modèles SOA. Cet assistant est accessible via le menu :
File > New > Other … > SOA Model (Catégorie IS Designer) :
Cet assistant permet de définir
- le nom de la ressource (fichier) à créer,
- le projet ou répertoire de destination pour cette nouvelle ressource :
Une fois l’assistant validé, un modèle vide est créé, et les représentations SOA Diagram, DTO Namespaces Hierarchy et DTO Physical Names sont créées.
Les représentations SOA Diagram et DTO Namespaces Hierarchy sont ouvertes afin de commencer l’édition :
Lorsqu’un modèle soa est créé à l’aide de ce wizard, les points de vues SOA Views, SOA (Safr@n Consolidated view) et Environment View sont activés.
- Le point de vue SOA Views est décrit dans la section suivante,
- Le point de vue SOA (Safr@n Consolidated view) est décrit dans la section de documentation Obeo Network – SOA,
- Le point de vue Environment Views fournit les vues de propriétés EEF communes avec d’autres designers tel que pour le Namespace par exemple.
Le point de vue SOA Views fourni par SOA Designer est dédié à la modélisation des composants métier. Il permet de visualiser et modifier un modèle SOA au travers de différents types de diagrammes et vues de propriétés.
L’ouverture d’une session de travail sur un modèle SOA se fait par l’une des manières classiques à un Modeling Project :
- En ouvrant le Modeling Project contenant le modèle,
- En double-cliquant sur un fichier *.aird existant,
- En faisant un glisser/déposer d’un fichier *.soa dans un Modeling Project sur la vue Model Explorer,
- En convertissant un projet contenant le modèle SOA en un Modeling Project.
L’ouverture de l’assistant Viewpoints Selection permet de vérifier que le point de vue SOA Views est bien activé.
Cet assistant est accessible dans le menu contextuel du Modeling Project sous l’entrée de menu :
Viewpoint Selection
Une fois le point de vue SOA Views activé il est possible de créer ou visualiser les diagrammes SOA Views.
Chaque type de diagramme est rattaché à un concept SOA précis. Par exemple, un DTO Diagram est rattaché à un Namespace.
Pour créer un diagramme d’un certain type, sélectionner l’élément du modèle auquel rattacher le diagramme dans la vue Model Explorer puis, avec un clic droit, sélectionner le menu :
New… > #Nom du diagramme#
Renseigner le nom du diagramme et valider.
Par exemple sur l’élément racine Components, deux types de représentation peuvent être créés comme le montre la capture d’écran suivante :
Une fois créé, le diagramme apparaît dans l’arbre de la vue Model Explorer sous l’élément sur lequel il a été créé, et l’éditeur de diagramme est ouvert prêt à modéliser.
Si il est fermé, un diagramme peut être ouvert en double-cliquant sur le noeud correspondant dans la vue Model Explorer.
Attention, bien qu’ils continuent d’exister et qu’ils soient bien sauvegardés, les diagrammes des points de vues non activés sont filtrés de la vue Model Explorer. Celle-ci ne présente que les diagrammes des points de vue activés sur le Modeling Project.
Le SOA Diagram offre une vue de haut niveau sur un modèle SOA, il peut être créé sur l’objet racine Components.
Il permet de modéliser les composants métiers, les services qu’ils fournissent, les services qu’ils requièrent ainsi que des liens entre les composants. Ces liens créés entre services requis et services fournis expriment qu’un service fourni par un composant réponds à un besoin de service requis par un autre composant.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Component : composant métier,
- Provided Service : service métier fourni par un composant,
- Required Service : service métier dont un composant a besoin pour fonctionner,
- Les liens entre services fournis et services requis.
Les outils fournis par la palette sont :
 |
Création d’un composant métier. |
 |
Création d’un service métier fourni par un composant. |
 |
Création d’un service métier requis par un composant. |
 |
Création d’un lien depuis un service requis vers un service fourni. Permet d’indiquer quel composant fournit les services nécessaires au fonctionnement d’un autre composant. |
 |
Ajout d’un composant externe sur le diagramme. Permet de faire apparaitre un composant défini dans un autre modèle SOA pour créer des relations avec les composants affichés. Cet outil est disponible par l’activation du calque External Components |
Il est possible de naviguer depuis ce diagramme vers un diagramme Component Contract (décrit ci-après) par l’une des actions suivantes :
- Action New > Component Contract du menu contextuel sur un Component : crée et ouvre un nouveau diagramme Component Contract,
- Action Open > #Nom d’un diagramme# du menu contextuel sur un Component : ouvre un diagramme Component Contract existant,
- Double-clic sur un Component : ouvre le premier diagramme Component Contract trouvé si il existe, propose la création d’un diagramme Component Contract sinon.
Le Component Contract Diagram permet de modéliser le détail d’un Component, il peut être créé sur un Component.
Il permet de modéliser :
- les services métiers fournis et requis par le composant,
- les opérations définies par les services,
- les paramètres d’entrée, de sortie et d’erreur des services.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Provided Service : service métier fourni par le composant,
- Required Service : service métier dont le composant a besoin pour fonctionner,
- Operation : opération d’un service,
- Input Parameter : paramètre d’entrée d’une opération
- Output Parameter : paramètre de sortie d’une opération
- Fault Parameter : cas d’erreur pour une opération
Les outils fournis par la palette sont :
 |
Création d’un service métier fourni par un composant. |
 |
Création d’un service métier requis par un composant. |
 |
Création d’une opération d’un service. |
 |
Création d’un paramètre d’entrée d’une opération. |
 |
Création d’un paramètre de sortie d’une opération. |
 |
Création d’un cas d’erreur d’une opération. |
Les DTO sont organisés en Namespaces (autrement appelés packages).
Le diagramme DTO Namespaces Hierarchy est destiné à gérer l’ensemble de cette hierarchie de Namespaces et peut être créé sur l’objet racine Components.
Il permet de créer, modifier ou supprimer des packages ainsi que d’accéder facilement (par double clic ou menu contextuel sur les Namespaces) aux diagrammes de DTOs d’un package.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- Namespace : chaque Namespace contenu dans l’élément racine est affiché. Les Namespaces contenus par d’autres sont représentés à l’intérieur de leur Namespace parent. L’icône d’un Namespace est en noir et blanc si le Namespace est vide, en couleur sinon.
- Dépendance : l’affichage des dépendances peut être activé ou désactivé via le layer Dependencies. Les dépendances entre Namespaces sont représentées par des liens pouvant être fléchés à une ou deux extrémités. Les dépendances sont calculées à partir du contenu de chacun des Namespace. Une dépendance est identifiée entre deux Namespaces si il existe un lien d’héritage, une référence ou l’utilisation d’une Enumeration pour typer un attribut entre un DTO d’un Namespace et un autre. Si il est non nul, le nombre de dépendances identifiées est indiqué sur l’extrémité du lien correspondant, et cette extrémité est décoré d’une flèche. Les dépendances entre les packages d’une même lignée de contenance ne sont pas affichées. L’affichage des dépendances peut être activé ou désactivé via le layer Dependencies. Les namespaces dits “externes” sont également affichés dans ce layer. Un namespace externe est un namespace contenant une entité externe liée à une entité présente dans un namespace affiché par le diagramme (voir External DTO dans la section Diagramme de DTOs ci-après).
Les outils fournis par la palette sont :
 |
Création d’un Namespace. Un Namespace peut être créé sur le fond du diagramme ou à l’intérieur d’un autre Namespace. |
Il est possible de naviguer depuis ce diagramme vers des diagrammes DTO Diagram par l’une des actions suivantes :
- Action New > DTO Diagram du menu contextuel sur un Namespace : crée et ouvre un nouveau DTO Diagram,
- Action Open > #Nom d’un diagramme# du menu contextuel sur un Namespace : ouvre un DTO Diagram existant,
- Double-clic sur un Namespace : ouvre le premier DTO Diagram trouvé si il existe, propose la création d’un DTO Diagram sinon.
Un diagramme de DTOs (DTO Diagram) permet de gérer les DTOs d’un Namespace, il peut être créé sur un Namespace.
Le diagramme permet d’afficher et manipuler les éléments suivants :
- DTO : Data Transfer Object, type de donnée destiné à être utilisé par les services, il es représenté par un conteneur rectangulaire.
- Attribute : attribut d’un DTO, un attribut porte notamment un type et une multiplicité. Le type qu’il porte peut être un type primitif ou une enumération (et non pas un autre DTO). Il est représenté comme élément de liste à l’intérieur de la représentation d’un DTO.
- Relation : relation entre deux DTOs. Permet de structurer le modèle de données représenté par les DTO. Les types de relations supportées sont relation unidirectionelle, bidirectionelle, de composition. Une relation est représentée par un lien pouvant être décoré d’une flèche ouverte dans le cas d’une relation directionelle, et d’un losange dans le cas d’une relation de composition.
- Inheritance : relation de spécialisation d’un DTO par un autre. Une relation de spécialisation est représentée par un lien décoré d’une flèche fermée pointant vers le DTO spécialisé. Une seule relation de spécialisation peut être définie par DTO.
- Enumeration : Type de donnée pouvant servir au typage d’un attribut ou d’un paramètre de service. Une Enumeration prends sa valeur dans un ensemble fini de literaux qui lui sont propres. Une Enumeration est représentée par un conteneur rectangulaire.
- Literal : Literal d’une Enumeration_. Il fait partie de la définition de l’_Enumeration et représente l’une des valeurs que peut prendre l’_Enumeration_. Un Literal est représenté comme élément de liste à l’intérieur de la représentation d’une Enumeration.
- Namespace : Namespaces contenus directement dans le Namespace contextuel au DTO Diagram.
Les outils fournis par la palette sont :
 |
Création d’un sous-Namespace. |
 |
Création d’un DTO. |
 |
Création de DTOs à partir d’entités (cf. description ci-dessous). |
 |
Création d’un attribut de DTO. |
 |
Création d’une énumération. |
 |
Création d’une valeur d’énumération. |
 |
Création d’une relation simple. |
 |
Création d’une relation de composition. |
 |
Création d’un lien d’héritage. |
 |
Création d’une relation simple bidirectionnelle. |
 |
Création d’une relation de contenance bidirectionnelle. |
 |
Ajout d’un DTO externe au Namespace courant. Permet de faire figurer sur le DTO Diagram un DTO défini dans un autre Namespace_, donnant la possibilité de créer des relations inter-_Namsepace. Cet outil est activable via le calque External DTOs |
L’outil de création de DTOs à partir d’entités permet de créer un modèle de DTO conformément à tout ou partie d’un modèle d’entités (voir Obeo Network – Entity Designer ).
Cet outil affiche la boîte de dialogue suivante permettant la sélection des entités et relations à prendre en compte :
La validation de cette sélection déclenche la création d’autant de DTO et de Relations qui avaient été sélectionnés.
En plus des outils définis par la palette, l’outil de drag and drop permet de déplacer un DTO d’un namespace à un autre.
Le drag and drop depuis le Model Explorer d’un DTO d’un autre Namespace que le Namespace sur lequel est défini le DTO Diagram a pour effet de déplacer le DTO depuis son Namespace d’origine dans le namespace du diagramme.
Le DTO ainsi déplacé reste référencé là où il l’était, comme par exemple en type de paramètre d’une opération SOA ou en référence sur une Relation. Si le calque External DTOs est activé, alors les DTO externes figurent sur le diagramme avec une couleur différente et un label représentant leur nom qualifié :
L’exposition d’un composant consiste à publier tout ou partie des services qu’il fournit de manière à les rendre accessibles à des clients (autres composants ou systèmes, et potentiellement au travers d’un réseau).
L’ensemble des services exposés d’un composant constitue son API (Application Programming Interface).
Dans SOA Designer, le type d’exposition est paramétrable au niveau d’une Operation, sur l’onglet principal de la vue de propriétés :
La notion de visibilité (Public/Privé) fait référence à la notion du même nom définie par les langages orientés objet et concernant les méthodes de classes. Ainsi, une Operation publique sera accessible depuis les implémentations des autres Operations du Composant ou bien depuis un autre composant destiné à être déployé dans la même application, mais il ne sera pas accessible depuis un autre système.
La notion d’exposition fait référence à la publication par une technologie permettant de la rendre accessible depuis un autre système, et çe typiquement au travers d’un réseau. C’est ce qu’adresse par exemple de manière non exaustive les technologies REST, SOAP ou gRPC. Ainsi, pour être exposée, une opération doit avoir une visibilité Publique.
SOA Designer propose les types d’exposition suivants :
- NONE : Non exposée,
- REST : Exposée en web service par Representational State Transfer
- SOAP : Exposée en web service par Simple Object Access Protocol
Le type d’exposition couvert par SOA Designer est REST. Le type d’exposition SOAP n’est disponible dans le studio qu’à titre indicatif, aucun outillage spécifique n’ayant été développé pour l’exploiter.
L’icone des Operations diffère suivant le type d’exposition :
 |
Privée | (type d’exposition ignoré) |
 |
NONE | (opération publique non exposée) |
 |
REST | (opération publique exposée en REST) |
 |
SOAP | (opération publique exposée en SOAP) |
SOA Designer permet de :
- modéliser des API Rest via un modeleur graphique basé sur Sirius,
- exporter / importer ces API au format Swagger (conforme à la norme OpenAPI),
- prévisualiser un export Swagger dans une vue web Swagger-UI.
La terminologie utilisée par SOA Designer provient du champ lexical de SOA (Service Oriented Architecture), dans lequel le concept de service est défini comme une fonction ou fonctionnalité. Cette définition est suffisament large pour autoriser un raffinement de la notion de Service en Operations, tel qu’il est fait dans SOA Designer.
Or, cette notion d’_Operation SOA_ est celle qui se prête à être en correspondance avec la notion de Service REST.
Le concept de Service SOA quand à lui, est mis en correspondance avec le concept de Tag défini par la norme OpenAPI.
Enfin, le concept de Component SOA est mis en correspondance avec le concept d’API, ce qui est appelé de manière générique Composant d’Exposition.
De manière synthétique, voici les correspondances clé entre les deux terminologies :
|_. SOA Designer |_. OpenAPI |
| Component | OpenAPI |
| Service | Tag |
| Operation | Service |
La suite de ce document privilègie la terminologie SOA. Les exceptions à cette règle seront clairement explicitées.
Le concept de SOA Designer correspondant à une API REST OpenAPI est le Component.
Les données d’exposition sont accessibles via l’onglet Exposition de la vue des propriétés :
L’_URL_ est l’URL de base du serveur destiné à héberger l’API.
Une URI peut être définie à chaque niveau de profondeur dans le modèle sur les concepts Component, Service et Operation :
L’URL d’une Operation peut donc être calculée par la concaténation de l’URL du Component et de chacune des URI sur les trois niveaux Component, Service et Operation.
Le concept en correspondance avec le Tag OpenAPI est le concept Service.
L’onglet principal du service permet d’en définir le nom, l’onglet Exposition permet d’en définir l’URI. Celle-ci peut rester vide.
Le concept en correspondance avec le Service OpenAPI est le concept Operation. Lorsqu’un type d’exposition autre que NONE est sélectionné comme expliqué au paragraphe Types d’exposition , l’onglet Exposition devient visible et accessible :
Le verbe correspond au verbe HTTP et peut prendre l’une des valeurs : GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, TRACE.
Dans le cas où l’opération définit des paramètres d’entrée, ceux-ci sont listés dans la section Input Parameters_, qui offre la possibilité de définir le mode de passage et les identifiants REST de chacun d’eux. Ceci est expliqué plus en détail ci-dessous dans la section Modélisation d’un paramètre d’entréeparameter .
Le contenu de l’onglet Exposition d’un paramètre n’est pas le même pour un paramètre d’entrée, de retour ou d’erreur.
L’identifiant REST est un moyen pour identifier un paramètre autrement que par son nom, et a des particularités liées au mode de passage du paramètre.
Pour un mode de passage BODY, l’identifiant REST n’a pas de sens.
Lorsque le mode de passage BODY est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une zone de texte non modifiable affichant le texte “body” :
Pour un mode de passage PATH_, l’identifiant REST doit correspondre à l’un des identifiants définis entre accolades dans l’URI de l’_Operation.
Lorsque le mode de passage PATH est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une autre liste déroulante proposant un choix déduit de l’analyse de l’URI de l’_Operation_. Ainsi, si l’URI est “/{country}/{author}”, la liste déroulante proposera les deux choix “country” et “author” :
Suite à une édition de l’URI d’une Operation, il est possible que la valeur de l’identifiant REST d’un Parametre PATH ne soit pas dans l’URI. Dans ce cas un message d’erreur est affiché :
Pour un mode de passage QUERY, COOKIE ou HEADER, l’identifiant REST permet d’identifier le paramètre soit dans l’URL d’appel du service REST, soit dans le cookie, soit dans le header HTTP.
Lorsque l’un de ces modes de passage est sélectionné dans la liste déroulante, la vue de propriétés affiche à côté de celle-ci une zone de texte libre permettant la saisie de l’identifiant :
L’onglet Exposition des vues de propriétés pour un paramètre de retour ou d’erreur présente la même IHM permettant de saisir un code de status et une description :
Le bouton à droite de la zone de texte Status Code ouvre une boîte de dialogue permettant de saisir facilement parmi une liste de valeurs par défaut des couples code / description.
Le dialogue propose les codes de succès dans le cas d’un paramètre de sortie, et des codes d’erreur dans le cas d’un paramètre d’erreur :
Les schemas de sécurité sont définis sur l’onglet Security Schemes de la vue de propriétés d’un Component :
Cette vue permet de créer (
), supprimer (
) et réordonner (
, 
) les Security Schemes du Component.
La création d’un Security Scheme déclenche l’affichage d’une boîte de dialogue permettant de le spécifier :
L’édition des valeurs saisies est modifiable par la suite en double-cliquant sur un SecurityScheme dans cette même vue de propriétés, ou bien dans la vue de propriétés d’un SecurityScheme lorsque celui-ci est séléctionné dans la vue Model Explorer :
Lorsqu’ils existent, les SecuritySchemes sont présentés dans la vue Model Explorer au niveau de profondeur suivant celui du Component.
Lorsqu’il existe au moins une définition de SecurityScheme dans le Component, alors une section Security apparaît dans l’onglet Exposition de la vue des propriétés d’une Operation :
Cette vue permet de sélectionner les SecuritySchemes à appliquer à l’_Operation_ (
), supprimer une affectation de Security Scheme à l’_Operation_ () et réordonner (, ) les applications de Security Schemes.
La suppression ne supprime pas le Security Scheme du modèle, mais simplement son affectation à l’_Operation_.
La sélection des Security Schemes ouvre une boîte de dialogue permettant d’ajouter, retirer, réordonner les affectations de Security Schemes à l’_Operation_ :
Les Security Schemes accessibles pour une affectation à une Operation sont ceux définis au niveau du Component auquel appartient l’_Operation_.
Quand au moins un Security Scheme est appliqué à une Operation_, celle-ci est décorée avec l’icone !pics/exposition/IconSecurityScheme.gif! :
Une fois que les infomrations requises à la définition d’une API Rest sont modélisées, il est possible de générer un fichier de spécification Swagger.
Une fonctionnalité de prévisualisation est disponible en menu contextuel du Component :
Celle-ci ouvre un navigateur montrant le résultat de l’export dans Swagger UI, permettant de s’assurer que la génération produit un résultat satisfaisant :
La fonctionnalité d’export permet de produire des fichier Swagger au format yaml ou json. Elle est disponible en menu contextuel sur l’objet racine Components ou bien sur l’objet Component. Dans les deux cas, une boîte de dialogue invite à choisir le dossier de destination :
Suite à la validation du Dialogue, un fichier est généré par Component, avec la convention de nommage suivante :
<Nom du Component>-<Version du Component>.<yaml|json>
La fonctionnalité d’import Swagger permet d’importer un fichier de spécifiction Swagger dans SOA Designer sous forme d’un Component. L’import incrémental n’est pas supporté. Si un Component du nom de l’API existe déjà dans le modèle SOA, alors l’import échoue avec un message d’erreur du type “Component with name BookStore already exist.”.
La fonctionnalité d’import Swagger est disponible en menu contextuel sur l’objet racine Components :
En cas de succès suite à l’import, un nouveau Component est créé, prêt à être utilisé dans un ensemble plus vaste de Components SOA.
La gestion des exigences pour un modèle SOA utilise le mécanisme transverse de gestion des exigences. Pour plus de détails, voir Obeo Network – Requirements Tooling .
Il est possible d’attacher de la documentation aux éléments d’un modèle SOA. Le mécanisme utilisé est le mécanisme transverse de gestion de la documentation : Obeo Network – Documentation Tooling .
Il est possible de créer des diagrammes d’interaction pour les éléments d’un modèle SOA. Voir la documentation Obeo Network – Interaction Tooling .
Il est possible de créer des diagrammes de machines à états pour les éléments d’un modèle SOA. Voir la documentation Obeo Network – State Machine Tooling .