Dokumenation SGS Editor

Der folgende Artikel dokumentiert den Aufbau sowie implementierungsspezifische Details des SGS Editors.

Source Code des Editors

Der Source Code des SGS Editors ist im SVN unter folgendem Link zu finden: [1]

Aufbau des Editors

Der Editor besteht aus folgenden Projekten:

smartgrid.model.input
smartgrid.model.input.edit
smartgrid.model.input.editor
smartgrid.model.output
smartgrid.model.output.edit
smartgrid.model.output.editor
smartgrid.model.topo
smartgrid.model.topo.edit
smartgrid.model.topo.editor
smartgrid.model.topo.graphiti

Jedoch enthalten ausschließlich folgende Projekte eigenen Quellcode.

smartgrid.model.topo.graphiti
smartgrid.model.input
smartgrid.model.output

Alle anderen Projekte wurden automatisch generiert und enthalten keine Änderungen.

Topo Plugin

Das smartgrid.model.topo.graphiti Plugin beschreibt den Kerneditor. Dieses Plugin enthält alle Komponenten, welche für den Graphiti-Editor notwendig sind, wie den DiagramTypeProvider.

Dieses Plugin ist wie folgt ausgebaut:

graphiti-Package enthält die klassen des Editors, wie beispielsweise den DiagramTypeProvider
graphiti.action-Package enthält die Hauptklasse, welche alle Actions in den Erweiterungsplugins implementieren müssen.
In graphiti.extensionpoint.definition sind alle ExtensionPoint Interfaces definiert, welche der Editor externen Plugins anbietet. Des Weiteren enthält graphiti.extensionpoint.evaluation alle Klassen, die notwendig sind, um die o.g. ExtensionPoints auszuwerten.
helper-Package enthält Helper-Klassen, welche für das ganze Framework notwendig sind.
In patterns sind alle Patterns des Haupteditors abgelegt und in patterns.connections alle Connection-Patterns des Haupteditors.
propertysheet-Package enthält die Propertysheets sowie die korresponierenden Filter.
In resizefeature ist ein Dummy-Feature hinterlegt, welches dafür sorgt, dass die grafischen Elemente des Editors nicht verändert werden können.
wizard-Package enthält den Wizard, mit dem neue SGS Diagramme erzeugt werden können.

Input Plugin

Das smartgrid.model.input Plugin erhält die Input Erweiterung des Editors. Es enthält zum beispiel alle grafischen Elemente, welche für das Input MetaModell notwendig sind. Alle Packagenamen, welche input enthalten sind automatisch generiert.

Das action-Package enthält die Toolbar-Actions, welche beispielweise für das Laden von input-Instanzen verantwortlich sind.

in customfeatures werden die Custom Actions definiert. Sie sind unter anderem verantwortlich, die grafische Oberfläche bei Stromausfall zu verändern.
customfeatures.addfeatures enthält die AddFeatures, welche die grafische Oberfläche (z.B. eines PowerGridNodes) wirklich verändern.
customFeatures.resizefeatures enthält die resize-Patterns. Diese werden jedoch aktuell nicht verwendet, da die Resize-Funktionalität zur Zeit global definiert ist.
extensionPoint.contribution-Package enthält die ExtensionPoint Implementierungen, welche dem Kerneditor alle Erweiterungen, wie grafische Repräsentierungen, übergeben.
In listener ist ScenarioModelChangedListener definiert. Dieser lauscht auf Veränderungen im ScenarioModel und modifiziert das InputModell falls es notwendig ist.

Output Plugin

Das smartgrid.model.output Plugin enthält alle Elemente, welche für das OutputModell benötigt werden. Alle Packages, welche model im Namen tragen, wurden mit eigenem Quellcode modifiziert.

action-Package enthält, wie im Input Plugin, die Toolbar Action, welche zuständig sind OutputModelle zu laden oder zu löschen.
contributor-Package entählt wiederum die Implementierungen der ExtensionPoints und das features-Package Klassen, welche dafür verantwortlich sind die grafischen Elemente für das das OutputModell zur Verfügung zu stellen.

Beschreibung klassischer Graphiti Konzepte

In diesem Abschnitt werden die Grundlegenden Konzepte von Graphiti behandelt. Tiefergehende Informationen bzgl. Graphiti sind bei [2] oder [3] zu finden.

Die folgende Abbildung zeigt die Grundfunktionsweise von Graphiti.

Der DiagramTypeProvider ist der Herzstück des Graphiti Editors. Dieser enthält alle Provider, die der Editor verwendet. Hierzu gehört der ToolBehaviorProvider(zur Manipulation des KontextMenüs), der ImageProvider oder der FeatureProvider. Features bedeuten im Kontext von Graphiti Funktionalitäten, welche zur Erzeugung grafischer Elemente o.ä. benötigt werden. Innherhalb von graphiti gibt es eine Anzahl von verschiedenen Features. Das CreateFeature erzeugt neue Business Objekte (Modellinstanzen), wohingegen das AddFeature neue PictogramElemente erzeugt. PictogramElemente beinhalten in Graphiti die grafischen Repräsentationen. Des Weiteren exisieren diverse andere Features, wie beispielsweise Resize Features, welche definieren was passiert, falls ein grafisches Element in seiner Größe verändert wird. Eine genaue Beschreibung der verschiedenen Features ist in den o.g. Links gegeben. In Graphiti ist es möglich darunterliegende Modellinstanzen mit grafischen Elementen zu verbinden. Damit besteht die Möglichkeit beispielsweise Attribute aus der Modellinstanz im Editor anzeigen zu lassen. Die Verbindung erfolgt in Graphiti über das Link-Konzept. Hierbei werden Modellinstanz und PictogramElement miteinander verbunden. Dabei besteht auch die Möglichkeit, dass ein BusinessObjekt mit mehreren PictogramElementen verbunden ist.

Erweiterung klassischer Graphiti-Konzepte

Der folgende Abschnitt gibt einen Überblick, welche Standart-Graphiti Klassen überschrieben wurden und was der Grund für die Erweiterung ist.

SGSDiagramBehavior

Die DiagramBehavior Klasse von Graphiti definiert, wie sich das Diagramm verhalten soll. Möchte man das Verhalten des Diagrammes anpassen, so muss diese Klasse überschrieben werden. Hierbei ist wichtig zu erwähnen, dass die überschriebene Klasse selbst instanziiert werden muss, da sonst die normale DiagramBehavior verwendet wird. Dies geschieht im DiagramEditor.

Im SGS Editor wurden folgende Methoden überschrieben.

initActionRegistry(): In dieser Methode werden die ToolbarActions aus den Plugin geladen und initialisiert.
register/unregisterBusinessObjectListener(): In dieser Methode werden Modelllistener hinzugefügt oder entfernt. Beispielsweise der Listener auf dem InputPlugin (s.o.)

SGSDiagramEditor

Die DiagramEditor-Klasse ist Hauptklasse des GraphitiEditor und repräsentiert diesen in Eclipse. Damit der Editor Eigenschaften, wie eine eigene DiagramBehavior, erhalten kann muss von der DiagramEditor-Klasse abgeleitet werden. Die überschriebene Klasse heißt SGSDiagramEditor. Die neue DiagramBehavior wird wie folgt initialisiert.

    @Override
    protected DiagramBehavior createDiagramBehavior() {
         return new SGSDiagramBehavior(this);
    }

Zur Verwendung der neuen DiagramEditor-Klasse muss diese noch dem Editor-ExtensionPoint in der plugin.xml bekanntgemacht werden

<extension point="org.eclipse.ui.editors">
     <editor
           class="smartgridsecurity.graphiti.SGSDiagramEditor"
           contributorClass="smartgridsecurity.graphiti.SGSActionBarContributor"
           name="SGSEditor"
           id="SGSEditorId"
           default="true"
           extensions="sgdiagram"
           matchingStrategy="org.eclipse.graphiti.ui.editor.DiagramEditorMatchingStrategy">
      </editor>
   </extension>

SGSActionBarContributor

Der SGSDiagramActionBarContributor stellt dem Editor alle ToolbarActions zur Verfügung. Hierfür wird von der Klasse DiagramEditorActionBarContributor abgeleitet. Für die Verwendung muss der Contributor dem Editor bekanntgemacht werden (s.o. DiagramEditor plugin.xml)

SGSImageProvider

Der SGSImageProvider stellt die Bilder für den Editor zur Verfügung. Hierfür wurde von AbstractImageProvider abgeleitet. Um neue Bilder hinzuzufügen muss zunächst eine Konstante definiert und mit dem jeweiligen Bild verknüft werden.

    public static final String IMG_REPAIR= PREFIX + "repair";

    @Override
    protected void addAvailableImages() {
       ...
       addImageFilePath(IMG_REPAIR, "icons/repair.png");
       ...
   }

Des Weiteren ist es notwendig, die Klasse folgendem ExtensionPoint in der plugin.xml hinzuzufügen.

   <extension point="org.eclipse.graphiti.ui.imageProviders">
   <imageProvider
         class="smartgridsecurity.graphiti.SGSImageProvider"
         id="smartgridsecurity.graphiti.SGSImageProvider.id">
   </imageProvider>
</extension>

SGSToolBehaviorProvider

Diese Klasse ist eine Spezialisierung von DefaultToolBehaviorProvider. Der DefaultToolBehaviorProvider ist unter anderem für die Darstellung der Kontext-Menüs zuständig. In unserem Fall wird bisher nur die getContextButtonPad()-Methode überschrieben. In ihr werden die CustomFeatures aus den anderen Plugins hinzugefügt.

Der SGSToolBehaviorProvider wird innerhalb des SGSDiagramTypeProvider initialisiert.

Diagram Wizard

Für die Erstellung eigenes Diagramme wurde ein Wizard implementiert. Derzeit existiert jedoch nur ein Diagramm-Wizard. Ein Projekt-Wizard wurde bisher noch nicht implementiert.

Der Diagramm-Wizard besteht aus zwei Teilen: dem SmartgridDiagramWizard sowie CreateNewSmartgridDiagramPage. SmartgridDiagramWizard ist für die Erzeugung des Diagrammes zuständig und CreateNewSmartgridDiagramPage beinhaltet die grafische Darstellung des Wizard. Diese beiden Klassen müssen folgenden ExtensionPoint in der plugin.xml hinzugefügt werden.

<extension point="org.eclipse.ui.newWizards">

Verwenden von PropertySheets in Graphiti

Die Verwendung von PropertySheets in Graphiti ist hier genauer erläutert. Der Editor verwendet das gleiche Konzept.

Graphiti Editor Properties hinzufügen

Hinzufügen von ToolbarActions zu Graphiti

Der Mechanismus ist hier erklärt:

Graphiti Editor einen Toolbar Button hinzufügen

Funktionsweise des Erweiterungsmechanismus für Plugins

Dieser Abschnitt beschreibt, wie der Kerneditor um Funktionen erweitert werden kann. Hierfür wurde ein ExtensionPoint-Konzept entwickelt. Bisher ist es möglich den Kerneditor um folgende Funktionen zu erweitern:

Grafische Elemente
ToolBarActions
ContextButtons
Resize Features

Nachfolgend soll das Erweiterungsprinzip exemplarisch für die ContextButtons dargestellt werden. Das Prinzip kann später um beliebige Funktionen erweitert werden.

Änderungen im Kerneditor zur Implementierung des Erweiterungsprinzips für ContextButtons

Innerhalb des Kerneditors müssen in folgende Modifikationen vorgenommen werden:

Definieren des ExtensionPoints

In der plugin.xml muss der ExtensionPoint smartgridsecurity.graphiti.extension.contextbutton definiert werden. Hierfür wurde folgendes Interface erzeugt und dem ExtensionPointSchema hinzugefügt.

public interface IContextButtonResolver {
	
	List<AbstractCustomFeature> getContextButtons(IFeatureProvider fp);

}

Implementierung der ExtensionPoint-Evaluierung

Dafür wurde die Klasse EvaluateContextButtons implementiert. Diese evaluiert den ExtensionPoint und gibt alle CustomFeatures zurück.

Aufrufen des Evaluierung

Die Evaluierung wird in diesem Fall im SGSFeatureProvider aufgerufen, da in diesem alle Features verwaltet werden. Zum Speichern der CustomFeatures wurde eine Registry-Klasse implementiert. Folgendes Code-Fragment zeigt die Evaluierung. Die addContextButtons()-Methode wird im Konstruktor des SGSFeatureProviders aufgerufen.

    private void addContextButtons() {
    	ExtensionPointRegistry.getInstance().clearContextButtons();
    	List<AbstractCustomFeature> extensionCustomButtons = (new EvaluateContextButtons(this)).evaluateFeatureExtension(Platform.getExtensionRegistry());
    	ExtensionPointRegistry.getInstance().addContextButtonsToRegistry(extensionCustomButtons);
    }

Änderungen im Plugin zur Implementierung des Erweiterungsprinzips für ContextButtons

Folgende Änderungen müssen in den Plugins vorgenommen werden (hier im Input Plugin)

Hinzufügen der Extension smartgridsecurity.graphiti.extension.contextbutton in die plugin.xml des Input Plugins.

   <extension
         point="smartgridsecurity.graphiti.extension.contextbutton">
      <contextButton
            class="smartgrid.graphiti.extensionpoint.contribution.ContextButtonContributor">
      </contextButton>
   </extension>

Implementieren des ExtensionPoint Interfaces und Erzeugung der Instanzen, welche an den Editor übergeben werden sollen.

public class ContextButtonContributor implements IContextButtonResolver {

	@Override
	public List<AbstractCustomFeature> getContextButtons(IFeatureProvider fp) {
		AbstractCustomFeature[] actions = {new NodeDestoryedFeature(fp), new PowerEnabledFeature(fp)};
		GraphitiRegistryProvider.getInstance().setFeatureProvider(fp);
		return Arrays.asList(actions);
	}

}