A l'étape du billet précédant [step6] la page Graphics de notre éditeur de workflow basée sur GEF a été initialisée. Dans ce billet et le suivant, nous allons afficher les informations du modèle EMF workflow dans la page Graphics :

• les actions seront représentées par une figure carré.
• les states seront représentées par une figure ellipse.

Plus précisemment, dans ce billet nous allons initialiser les composants GEF (EditPart, EditPartFactory, figure Draw2d,GraphicalViewer) et nous occuper uniquement de l'instance EMF WorkflowType (pas de ces elements enfants StateType et ActionType). Pour vérifier que la mise en place de GEF soit faite correctement, nous représenterons l'instance EMF WorkflowType par un cadre rouge :

Vous pouvez télécharger le projet org.example.workflow_step7.zip présenté dans ce billet.

[Suite:]

GEF & Concepts

Lorsque j'ai démarré GEF, je ne savais pas par ou commencer car il y a une multitude de concepts à assimiler avant de pouvoir afficher/gérer son modèle. La documentation GEF propose plusieurs exemples qui m'ont beaucoup aidé une fois avoir passé un temps considérable à comprendre les principes de base de GEF. C'est pourquoi, je ne vais pas décrire GEF et ses principes d'un seul coup, mon idée est de les décrire principes au fur et à mesure que l'on avance dans les billets. Dans ce billet et le suivant nous souhaitons représenter graphiquement les instance EMF ActionType par des figures carrées et les instances EMF StateType par des ellipses. Ce billet et le suivant mettront en avant le concept Model View Controller (MVC) sur lequel GEF est basé.

GEF - MVC

GEF Programmer's Guide propose une vue d'ensemble GEF que j'aime bien :

Ce qui nous intéresse dans ce schéma c'est la partie de droite qui met en évidence le concept Model View Controller (MVC) sur lequel GEF est basé:

GEF - Model (EMF WorkflowType) - View (Draw2d) - Controlleur (EditPart)

Concrètement voici en GEF comment sont implémentées les 3 couches MVC :

• La couche modèle (Model) ne fait pas partie du framework GEF. Le modèle correspond aux données que l'on souhaite afficher/gérer graphiquement. Dans notre cas le modèle est notre instance EMF WorkflowType (et ses enfants ActionType et StateType).
• La couche vue (View) fait partie du framework GEF. Son rôle est d'afficher des figures. Dans notre cas les figures à afficher sont des carrées, des ellipses (et un cadre rouge pour l'instance EMF WorkflowType). La vue en GEF est basé sur l'API Draw2d.
• La couche contrôleur (Controlleur) fait partie du framework GEF. En GEF cette couche est appelée org.eclipse.gef.EditPart. Un EditPart a pour rôle de synchroniser le modèle avec la vue et inversement :
  
  • lorsque le modèle change (ex : on saisit le contenu XML d'une action, ce qui ajoute une instance EMF ActionType à l'instance EMF WorkflowType), la vue change (un nouveau carré est ajouté au diagramme).
  • lorsque la vue change le modèle est mis à jour. Un exemple est celui de A Shape Diagram Editor ou le modèle d'une Shape contient les coordonnées x, y. Lorsque l'utilisateur déplace une figure dans le diagramme (la vue change), les coordonées x, y de l'instance Shape sont mises à jour.

  Le contrôleur joue le rôle d'édition.
  

Chacune des instances du modèle qui doit être représentée graphiquement (instance EMF WorkflowType, ActionType, StateType) est gérée par une instance controleur EditPart. Un EditPart est associé aussi à une instance IFigure (interface Draw2d qui représente une figure visuelle). L'instanciation des contrôleur des EditPart s'effectue via une factory d'Editart (EditPartFactory) que nous devons implémenter. Cette factory permet d'indiquer la classe EditPart à instancier pour une instance du modèle donné.

Voici un schéma qui met en évidence la factory d'EditPart :

Ce schéma montre bien qu'une instance EMF (Model) est associé à une instance EditPart (Contrôleur) qui est elle même est associée à une instance IFigure (Vue). Dans ce schéma nous pouvons voir la notion de Graphicalviewer qui utilise la factory d'EditPart. Il stocke les EditPart crés par la factory d'EditPart. Pour conclure, les concepts GEF abordés dans ce billet seront :

• EditPart : classe de base qui joue le rôle du contrôleur dans une architecture MVC.
• IFigure : interface Draw2d qui joue le rôle de la vue dans une architecture MVC.
• EditPartFactory : factory d'EditPart qui est appelé par le GraphicalViewer dans le cas ou le modèle n'est pas encore associé à un EditPart.
• GraphicalViewer : gère le cycle de vie des EditPart. Pour retrouver l'EditPart associée à un modèle, il recherche dans un premier temps dans son registry d'EdipPart si il n'y pas de d'EditPart qui gére déja l'instance modèle en cours de traitement, sinon il utilise la factory d'EditPart pour instancier une nouvelle EditPart et l'enregistre dans son registry (Map<Modele, EditPart> ).

Voici le schéma ci-dessus personnalisé avec notre modèle EMF WorkflowType :

Ce schéma met en évidence les différentes classes que nous allons créer :

• Les classes EditPart (Contrôleur) :
  
  • WorkflowTypePart : EditPart qui gère l'instance EMF WorkflowType.
  • ActionTypePart : EditPart qui gère les instances EMF ActionType (voir billet suivant).
  • StateTypePart : EditPart qui gère les instances EMF StateType (voir billet suivant).
• Les classes IFigure Draw2D (Vue) :
  
  • WorkflowTypeFigure : figure Draw2d qui permet d'afficher un cadre rouge (ce cadre rouge sera enlevé dans le billet suivant).
  • ActionTypeFigure : figure Draw2d qui permet d'afficher un carré (voir billet suivant).
  • StateTypeFigure : figure Draw2d qui permet d'afficher une ellipse (voir billet suivant).
• WorkflowPartFactory factory d'EditPart qui permet d'instancier les EditPart WorkflowTypePart, ActionTypePart, StateTypePart en fonction du modèle EMF.
  

MVC - Workflow

Dans ce billet nous souhaitons représenter graphiquement uniquement l'instance EMF WorkflowType avec un cadre rouge :

Model - WorkflowType

Ici la couche modèle est représentée par notre instance EMF WorkflowType.

View - WorkflowTypeFigure

La couche vue est représentée par l'interface Draw2d org.eclipse.draw2d.IFigure. Il existe une classe d'implémentation de cette interface org.eclipse.draw2d.Figure qui implémente la plupart des méthodes de l'interface IFigure. GEF conseille d'utiliser cette classe au lieu d'implémenter soit même les méthodes de l'interface, ce qui permet d'assurer une compatibilité avec les versions futurs de GEF au cas où l'interface ajoute/supprime de nouvelle méthode. GEF conseille de suivre ce principe. En fait il est valable pour n'importe quel API.

Créer la classe org.example.workflow.presentation.graphical.figures.WorkflowTypeFigure comme suit :

package org.example.workflow.presentation.graphical.figures; 
 
import org.eclipse.draw2d.Figure; 
 
public class WorkflowTypeFigure extends Figure { 
 
}

A ce stade cette classe n'affichera rien.

Controlleur - WorkflowTypePart

La couche contrôleur est représentée par l'interface GEF org.eclipse.gef.EditPart. GEF propose la classe abstraite org.eclipse.gef.editparts.AbstractGraphicalEditPart qui implémente la plupart des méthodes de l'interface org.eclipse.gef.EditPart. GEF conseille encore d'utiliser cette classe abstraite pour les mêmes raisons décrites ci dessus (assurer la compabilité futur avec l'API).

Créer la classe org.example.workflow.presentation.graphical.parts.WorkflowTypePart comme suit :

package org.example.workflow.presentation.graphical.parts; 
 
import org.eclipse.draw2d.IFigure; 
import org.eclipse.gef.editparts.AbstractGraphicalEditPart; 
import org.example.workflow.presentation.graphical.figures.WorkflowTypeFigure; 
 
public class WorkflowTypePart extends AbstractGraphicalEditPart { 
 
  @Override 
  protected IFigure createFigure() { 
    return new WorkflowTypeFigure(); 
  } 
 
  @Override 
  protected void createEditPolicies() { 
    
  } 
  
}

La méthode abstraite AbstractGraphicalEditPart#createFigure() est implémentée dans notre cas pour retourner une instance de la Vue WorkflowTypeFigure.
La méthode abstraite AbstractGraphicalEditPart#createEditPolicies() doit aussi être aussi implémentée. Pour l'instant elle est vode. Nous reviendront plus tard sur la notion GEF d'EditPolicies.

Modification GraphicalWorkflowEditor

A cette étape nous avons les 3 couches MVC implémentées (Model=EMF WorkflowType, View=WorkflowTypeFigure et Controleur=WorkflowTypePart).
Nous devons maintant orchestrer ces 3 couches via le GraphicalViewer GEF, autrement dit :

1. indiquer au GraphicalViewer, la factory d'EditPart a utiliser (WorkflowPartFactory que nous allons créer).
2. indiquer au GraphicalViewer le modèle racine a utiliser (dans notre cas notre instance EMF WorkflowType).

GraphicalViewer - Factory d'EditPart

Definition Factory d'EditPart - WorkflowPartFactory

Une factory d'EditPart s'effectue en implémentant l'interface GEF org.eclipse.gef.EditPartFactory. Pour cela créer la classe org.example.workflow.presentation.graphical.parts.WorkflowPartFactory comme suit :

package org.example.workflow.presentation.graphical.parts; 
 
import org.eclipse.gef.EditPart; 
import org.eclipse.gef.EditPartFactory; 
import org.example.workflow.model.WorkflowType; 
 
public class WorkflowPartFactory implements EditPartFactory { 
 
  public static final EditPartFactory INSTANCE = new WorkflowPartFactory(); 
 
  public EditPart createEditPart(EditPart context, Object modelElement) { 
    // get EditPart for model element 
    EditPart part = getPartForElement(modelElement); 
    // store model element in EditPart 
    part.setModel(modelElement); 
    return part; 
  } 
 
  /** 
   * Maps an object to an EditPart. 
   *  
   * @throws RuntimeException 
   * if no match was found (programming error) 
   */ 
  private EditPart getPartForElement(Object modelElement) { 
    if (modelElement instanceof WorkflowType) { 
      return new WorkflowTypePart(); 
    } 
    throw new RuntimeException("Can't create part for model element: " 
        + ((modelElement != null) ? modelElement.getClass().getName() 
            : "null")); 
  } 
}

La méthode EditPartFactory#createEditPart(EditPart context, Object modelElement) est implémentée pour instancier une instance EditPart WorkflowTypePart dans le cas ou le modèle modelElement reçu est une instance EMF WorkflowType. Dans cette factory nous renseignons aussi le modèle EMF à l'EditPart créé via sa méthode EditPart#setModel(Object model)

Cette factory est utilisée par le GraphicalViewer. Ce dernier gère un registry qui permet de retrouver l'EditPart associé à un modèle via la Map<Model, EditPart> accéssible par la méthode GraphicalViewer#getEditPartRegistry(). La factory d'EditPart est sollicitée que quand le GraphicalViewer ne trouve pas d'EditPart associé au modèle dans son registry. Dans le cas ou la factory d'EditPart est sollicitée, le GraphicalViewer met ensuite à jour son registry avec son EditPart instancié.

La factory d'EditPart peut être un singleton, ceci se concrétise par le code :

public static final EditPartFactory INSTANCE = new WorkflowPartFactory();

GraphicalViewer - Enregistrement factory EditPart

A cette étape nous pouvons renseigner au GraphicalViewer de l'editor GEF la factory d'EditPart WorkflowPartFactory via la méthode GraphicalViewer#setEditPartFactory(EditPartFactory factory).
Une bonne pratique pour effectuer cette configuration est de le faire dans la méthode GraphicalEditor#configureGraphicalViewer() . Le GraphiCalViewer est une propriété de l'éditor GEF accéssible via la méthode protected GraphicalEditor#getGraphicalViewer().

Pour cela modifier la classe GraphicalWorkflowEditor en surchargeant la méthode configureGraphicalViewer() comme suit :

Modifier classe GraphicalWorkflowEditor
@Override 
protected void configureGraphicalViewer() { 
  super.configureGraphicalViewer(); 
 
  GraphicalViewer viewer = getGraphicalViewer(); 
  viewer.setEditPartFactory(WorkflowPartFactory.INSTANCE); 
 
}

GraphicalViewer - Model

A cette étape nous pouvons renseigner au GraphicalViewer de l'editor GEF notre modèle EMF racine WorkflowType à utiliser via la méthode GraphicalViewer#setContents(Object contents). Une bonne pratique pour effectuer ceci est de le faire dans la méthode GraphicalEditor#initializeGraphicalViewer().

Notre modèle EMF est chargé dans l'editor MultiPart WorkflowEditor et pas dans l'editor GEF GraphicalWorkflowEditor (contrairement aux examples GEF). Il faut donc dans un premier temps renseigner ce modèle dans notre editor GEF GraphicalWorkflowEditor. Une solution simple serait de le passer dans le constructeur de GraphicalWorkflowEditor, mais j'ai préféré passer l'editor WorkflowEditor au constructeur (car nous en aurrons besoin dans la suite de nos billets). A partir de l'editor WorkflowEditor nous pouvons ensuite récupérer l'instance EMF via l'EditingDomain EMF.

Pour cela, modifier le constructeur de la classe GraphicalWorkflowEditor pour renseigner l'editor WorkflowEditor comme suit :

... 
private IEditorPart parent; 
 
public GraphicalWorkflowEditor(IEditorPart parent) { 
  super.setEditDomain(new DefaultEditDomain(this)); 
  this.parent = parent; 
}

Modifer le code de la méthode WorkflowEditor#createAndAddGraphicalPage() pour renseigner l'instance WorkflowEditor au constructeur de GraphicalWorkflowEditor :

private void createAndAddGraphicalPage() { 
  GraphicalWorkflowEditor graphicalPage = new GraphicalWorkflowEditor(this); 
...

Modifier ensuite la classe GraphicalWorkflowEditor pour récupérer l'instance EMF du multi-part WorkflowEditor et le renseigner au GraphicalViewer comme suit :

... 
  @Override 
  protected void initializeGraphicalViewer() { 
    super.initializeGraphicalViewer(); 
 
    GraphicalViewer viewer = getGraphicalViewer(); 
    viewer.setContents(getWorkflow()); // set the contents of this 
    // editor 
  } 
 
  protected WorkflowType getWorkflow() { 
    EditingDomain editingDomain = ((IEditingDomainProvider) parent) 
        .getEditingDomain(); 
    Resource resource = editingDomain.getResourceSet().getResources() 
        .get(0); 
    return (WorkflowType) resource.getContents().get(0); 
  } 
...

Voici la classe GraphicalWorkflowEditor en entiere :

package org.example.workflow.presentation.graphical; 
 
import org.eclipse.core.runtime.IProgressMonitor; 
import org.eclipse.emf.ecore.resource.Resource; 
import org.eclipse.emf.edit.domain.EditingDomain; 
import org.eclipse.emf.edit.domain.IEditingDomainProvider; 
import org.eclipse.gef.DefaultEditDomain; 
import org.eclipse.gef.GraphicalViewer; 
import org.eclipse.gef.palette.PaletteRoot; 
import org.eclipse.gef.ui.parts.GraphicalEditorWithFlyoutPalette; 
import org.eclipse.ui.IEditorPart; 
import org.example.workflow.model.WorkflowType; 
import org.example.workflow.presentation.graphical.parts.WorkflowPartFactory; 
 
public class GraphicalWorkflowEditor extends GraphicalEditorWithFlyoutPalette { 
 
  private IEditorPart parent; 
 
  public GraphicalWorkflowEditor(IEditorPart parent) { 
    super.setEditDomain(new DefaultEditDomain(this)); 
    this.parent = parent; 
  } 
 
  @Override 
  protected void configureGraphicalViewer() { 
    super.configureGraphicalViewer(); 
 
    GraphicalViewer viewer = getGraphicalViewer(); 
    viewer.setEditPartFactory(WorkflowPartFactory.INSTANCE); 
 
  } 
 
  @Override 
  protected void initializeGraphicalViewer() { 
    super.initializeGraphicalViewer(); 
 
    GraphicalViewer viewer = getGraphicalViewer(); 
    viewer.setContents(getWorkflow()); // set the contents of this 
    // editor 
  } 
 
  protected WorkflowType getWorkflow() { 
    EditingDomain editingDomain = ((IEditingDomainProvider) parent) 
        .getEditingDomain(); 
    Resource resource = editingDomain.getResourceSet().getResources() 
        .get(0); 
    return (WorkflowType) resource.getContents().get(0); 
  } 
 
  @Override 
  protected PaletteRoot getPaletteRoot() { 
    return null; 
  } 
 
  @Override 
  public void doSave(IProgressMonitor monitor) { 
 
  } 
 
}

Avec cette solution on s'interdit de pouvoir utiliser GraphicalWorkflowEditor dans un éditeur unique (sans être contenu par le multi-part). Dans tous les examples GEF, c'est l'editor GEF qui charge le modèle. Dans notre cas, le chargement du modèle s'effectue dans un autre éditor (editor multi-part WorkflowEditor). Un autre solution aurrait été de passer le modèle EMF de l'editor multi-part WorkflowEditor a l'editor GEF GraphicalWorkflowEditor dans la méthode WorkflowEditor#createAndAddGraphicalPage() via le code :

WorkflowType emfWorkflowType = .... 
GraphicalViewer viewer = GraphicalWorkflowEditor.getAdapter(GraphicalViewer.class). 
viewer.setContent(emfWorkflowType) 

On peut remarquer que pour récupérer le GraphicalViewer on passe par la méthode GraphicalEditor#getAdapter(Object o) (voir article Adapters) et pas par la méthode GraphicalEditor#getGraphicalEditor() car celle-ci est en protected.

Le choix de passer le multi-part dans le constructeur GraphicalWorkflowEditor est discutable, mais les raisons de mon choix sont les suivantes :

• JSF Webtools fait comme ceci (ou presque).
• GEF conseille de renseigner le modèle au Graphicalviewer dans la méthode Graphicalviewer#initializeGraphicalviewer() (tous les examples GEF font comme cela).
• Je me dis que si la méthode GraphicalEditor#getGraphicalEditor() est en protected, c'est surement pour une bonne raison et que l'on ne doit pas récupérer le GraphicallViewer en dehors de l'editor GEF.

Test initialisation GEF - Visusalisation

A cette étape si vous relancez le plugin, la page GEF affichera une page blanche. Pour vérifier que tout le mécanisme GEF est bien mis en place, nous allons modifier la vue qui s'occupe de représenter l'instance EMF WorkflowType par une bordure rouge.

Pour cela modifier la classe WorkflowTypeFigure pour ajouter une bordure rouge a la vue qui représente l'instance EMF WorkflowType comme suit :

package org.example.workflow.presentation.graphical.figures; 
 
import org.eclipse.draw2d.ColorConstants; 
import org.eclipse.draw2d.Figure; 
import org.eclipse.draw2d.LineBorder; 
 
public class WorkflowTypeFigure extends Figure { 
 
  public WorkflowTypeFigure() { 
    super.setBorder(new LineBorder(ColorConstants.red, 2)); 
  } 
}

Relancer le plugin et vous pourrez constater qu'il y a un cadre rouge qui s'affiche.

Tous les concepts GEF (EditPart, Figure Draw2d, GraphicalViewer, EditPartFactory) sont bien initialisés! :

Test initialisation GEF - Debug

On peut aussi vérifier que notre initialisation est effectuée correctement en positionnant des points d'arret dans notre code pour suivre en debug le processus :

Mettez les 4 points d'arret suivants :

• à la fin de la méthode GraphicalWorkflowEditor#configureGraphicalViewer().
• à la fin de la méthode GraphicalWorkflowEditor#initializeGraphicalViewer().
• à la fin de la méthode WorkflowPartFactory#createEditPart(EditPart context, Object modelElement).
• à la fin de la méthode WorkflowTypePart#createFigure().

Relancez le plugin en mode debug.

Le debug s'arrete dans la méthode GraphicalWorkflowEditor#configureGraphicalViewer() :

On peut constater que la première chose qui est effectuée est la configuration du GraphicalViewer. Dans notre cas nous configurons a factory d'EditPart à utiliser.

Le debug s'arrete ensuite dans la méthode GraphicalWorkflowEditor#initializeGraphicalViewer() :

On peut constater que l'initialisation du GraphicalViewer. est effectuée apres sa configuration. Dans notre cas nous renseignons le modèle EMF WorkflowType au GraphicalViewer. La couche Model est initialisée.

Le debug s'arrete ensuite dans la méthode WorkflowPartFactory#createEditPart(EditPart context, Object modelElement) :

Ici la couche Controlleur est initialisée.

Le debug s'arrete ensuite dans la méthode WorkflowTypePart#createFigure() :

Ici la couche View est initialisée.

Draw2d

Je ne vais pas détailler Draw2d dans cette section car le sujet est vaste et GEF encapsule déja pas mal de problématiques. Draw2D peut être utilisé indépendemment de GEF et fournit la possibilité de :

• dessiner des figures.
• gérer les layouts (positionnement des figures).

Draw2D Developers Guide propose une vue d'ensemble Draw2d que j'aime bien :

Ce schéma montre que Draw2d est basé sur un Canvas SWT, containeur SWT où il est possible de déssiner. Draw2d fournit et utilise la classe org.eclipse.draw2d.LightweightSystem qui fait le lien entre le Canvas SWT et les figures Draw2d. Cette classe s'occupe par exemple de dispatcher les évenements SWT (ex : positionnement, click de la souris SWT effectuée sur le Canvas SWT) au figures Draw2d (pour par exemple sélectionner la figure qui aurrait été cliquée).

La classe abstraite GEF org.eclipse.gef.ui.parts.GraphicalEditor que nous avons utilisés pour notre éditeur de workflow (GraphicalEditorWithFlyoutPalette étend GraphicalEditor) et gère en interne une instance LightweightSystem. Plus exactement son viewer GraphicalViewer est basé sur la classe ScrollingGraphicalViewer qui étend GraphicalViewerImpl et qui gère en interne une instance LightweightSystem..

Figures Draw2D

Une figure Draw2D implémente l'interface org.eclipse.draw2d.IFigure. Draw2d fournit la classe abtraite org.eclipse.draw2d.Figure qui implémente IFigure. Draw2d fournit plusieurs figures par défaut (qui héritent de la classe abstraite Figure) comme :

• org.eclipse.draw2d.RectangleFigure : qui permet d'afficher un rectangle.
• org.eclipse.draw2d.Ellipse : qui permet d'afficher une ellipse.
• org.eclipse.draw2d.Triangle : qui permet d'afficher un triangle.
• org.eclipse.draw2d.Label : qui permet d'afficher du texte dans un label.

Mais il est conseillé de créer ou d'étendre les figures par défaut pour avoir des figures plus complexes (voir exemple Display a UML Diagram using Draw2D).

Layout Draw2D

Un gestionnaire de layout Draw2d est utilisé pour positionner et dimensionner les figures enfants d'unn figure parent. Il implémente l'interface org.eclipse.draw2d.LayoutManager. La plupart des layout étende la classe abstraite org.eclipse.draw2d.AbstractLayout (qui implémente LayoutManager).

Documentation Draw2D

Il n'y a malheureusement pas beaucoup de documentations sur Draw2d. Voici les liens que j'ai pu trouver concernant Draw2d :

• First Draw2d : l'exemple le plus basique que j'ai pu trouvé et qui affiche une liste de Label en Draw2d. Cet example est basé sur FigureCanvas qui étend SWT Canvas et qui instancie en interne la classe LightweightSystem.
  
• Display a UML Diagram using Draw2D : le seul example complet que j'ai trouvé qui permet d'expliquer pas à pas comment afficher des figures UML. Cet article montre que Draw2d est indépendant de GEF.
• Plotting with Draw2D and SWT with the Java platform : example Draw2d qui trace des lignes graphiques.
• IBM RedBook Eclipse Development using the Graphical Editing Framework and the Eclipse Modeling Framework : ce livre que vous pouvez télecharger parle de EMF et GEF et le chapitre 3.2 Introduction to Draw2D décrit en détail l'architecture de Draw2d (LightweightSystem....).