Entwicklung von EDADBManager PlugIns Grundlagen Einrichten

Entwicklung von EDADBManager PlugIns
Dr.-Ing. Volker Boos, IMMS, 2010
Grundlagen
Der EDADB-Manager ist ein in Java geschriebenes Programm zur Visualisierung, Dokumentation und
Bearbeitung von Schaltungsdaten. Es ist durch eine PlugIn-Schnittstelle erweiterbar. Der EDADBManager liegt in seiner ausführbarer Form als jar-File vor. PlugIns liegen im Unterverzeichnis plugins
und sind ebenfalls jar-Dateien. Die PlugIns müssen das Interface IPlugin unterstützen und werden
beim Start des EDADBManagers automatisch geladen.
Systemvoraussetzungen
Eclipse 3.x
Download von www.eclipse.org
EDADBPlugin-SDK
Wird vom IMMS bereitgestellt als EDADBPluginSDK.zip
Erfahrungen mit Java und Eclipse sollten vorhanden sein.
EDADBPlugin-SDK
Zur Erleichterung der Entwicklung gibt es ein Software Development Kit (SDK). Es ist ein Archiv
(EDADBPluginSDK.zip ) und enthält die notwendigen Interfaces, sowie ein Beispiel-Plugin
(SizingListPlugin), das XML-Dimensionierungslisten liest und die Parameter in den Bauelementen
einträgt.
Einrichten der Entwicklungsumgebung
Nach dem Start von Eclipse wird gewöhnlich nach dem Workspace gefragt. Erscheint dieses Fenster
nicht, sondern wird sofort ein bestehender Workspace geöffnet, kann mit dem Menübefehl „File –
Switch Workspace – Other…“ dieses Fenster aufgerufen werden. Als Workspace sollte ein neues oder
leeres Verzeichnis angegeben werden.
Nach Bestätigung mit OK öffnet sich das Welcome-Fenster von Eclipse. Mit einem Klick auf die
Ikone „Workbench“ gelangt man zu der noch leeren Java Perspective, wo alle Projekte des aktuellen
Workspace verwaltet werden.
Nun wird das Plugin-SDK in das neu angelegte Verzeichnis entpackt. Die Verzeichnisstruktur sollte
so aussehen:
EDADBManager Plugins
1
Nun wechselt man wieder zu Eclipse, um die Projekte einzubinden. Mit dem Menübefehl File – New –
Java Project erscheint das folgende Fenster. Hier ist der Projektname einzugeben und mit „Finish“
abzuschließen. Dieser Vorgang wird für die Projekte EDADBInterface, EDADBManager und
SizingListPlugin durchgeführt.
Im Package-Explorer sind nun die angelegten Projekte zu
sehen. Im Projekt SizingListPlugin sind noch Fehler, die
wegen der unreferenzierten Interfaces auftreten.
Im Kontextmenü, das sich durch Klicken mit der rechten
Maustaste auf SizingListPlugin öffnet, wird „Build Path“
und „Link Source…“ ausgewählt. Dann wird für die
„Linked folder location“ der Pfad zu
workspace_path\EDADBInterface\src
eingetragen und der „Folder name“ von src auf einen
beliebigen anderen Namen umbenannt, z.B.
src_edadb_ifc
Weiterhin wird ein Link von
workspace_path\EDADBManager\iface
mit einem aussagekräftigen Namen angelegt,
z.B.src_edbm_iface
Nach dem Anlegen der beiden Links sollten die
Fehlermarken verschwinden.
Das PlugIn als JAR wird mit dem ANT-File „SizingListAnt.xml“ generiert. Dazu mit der rechten
Maustaste diese Datei anklicken, und „Run As - Ant Build“ auswählen. Im Console-Fenster wird der
Build-Prozess angezeigt. Die entstehende Datei wird im Verzeichnis EDADBManager\plugins
angelegt.
EDADBManager Plugins
2
Debuggen des Plugins
Erster Start des EDADBManagers aus Eclipse
Der EDADBManager wird nun zum Anlegen einer „Run Configuration“ und zur Kontrolle aus
Eclipse heraus gestartet. Dazu den EDADBManager im Package-Explorer mit der rechten Maustaste
anklicken, „Run As“ und „Java Application“ auswählen. Im nächsten Fenster mit dem Titel „Select
Java Application“ den Eintrag „EDADBManApp – org.imms.edadbmanager“ auswählen und mit OK
betätigen.
Der EDADBManager startet nun. Im Menü „Extras Plugins“ ist das SizingList Plugin in der Liste zu
sehen. Jetzt wird der EDADBManager wird wieder beendet.
Einstellen der Source Folder
Um das Plugin zu debuggen, muss der Source-Folder des Plugins im Projekt EDADBManager
eingestellt werden. Dazu wird im Package-Explorer das Projekt EDADBManager ausgewählt und mit
der rechten Maustaste angeklickt. Im nun erscheinenden Kontextmenü wird „Properties“ ausgewählt.
Im Fenster „Properties for EDADBManager“ wird auf der linken Seite „Run/Debug Settings“
ausgewählt und auf der rechten Seite markiert man EDADBManApp und klickt auf die „Edit“
Schaltfläche.
EDADBManager Plugins
3
Im Reiter „Source“ wird die Schaltfläche „Add…“ geklickt ,anschließend „Workspace Folder
ausgewählt und mit OK bestätigt. Im Fenster „Folder Selection“ wird im Projekt SizingListPlugin“ der
„src“ Folder ausgewählt. Danach werden die drei Fenster mit OK geschlossen.
Ausführen des Debuggers
Um den Debugger im PlugIn zu stoppen, muss ein zunächst Breakpoint angelegt werden, zum Beispiel
durch Doppelklick auf eine Zeile der Funktion initialize in SizingListPlugin.java :
Der Debugger wird entweder über das Kontextmenü des Projekts EDADBManager mit „Debug As Java Application“ oder über das Debugger-Symbol in der Taskleiste gestartet.
EDADBManager Plugins
4
Der Debugger stoppt nun am angegebenen Breakpoint:
Nun steht die volle Funktionalität des Debuggers zur Verfügung.
Ist statt des Quelltextes eines der folgenden Fenster zu sehen, wurde der Source-Folder nicht
zugeordnet. Das kann an dieser Stelle nachgeholt werden, in dem die entsprechend Schaltfläche
angeklickt wird.
EDADBManager Plugins
5
Entwickeln eigener Plugins
Zunächst wird wieder mit dem Menübefehl File – New – Java Project ein neues Projekt angelegt, z.B.
MySuperPlugin. Mit „Next“ gelangt man zu den „Source“-Einstellungen. Hier kann mit „Link
additional source“ der Pfad zu den Interfaces wie oben beschrieben eingestellt werden.
Im Verzeichnis MySuperPlugin/src wird nun eine neue Java-Klasse angelegt, z.B.
MySuperPlugin.java.
EDADBManager Plugins
6
Die automatisch angelegten Funktionen werden nun nach dem Vorbild des Beispiel-Plugins gefüllt.
Die Informationen über das Plugin (Name, Version, Zeitstempel, …) werden in einer separaten Datei
gespeichert (properties/Version.txt). Zunächst ist im Projektverzeichnis mit „New - Folder“ ein neuer
Ordner properties anzulegen. Dort wird die Textdatei Version.txt neu angelegt oder aus dem
Beispiel-Plugin kopiert. Dort werden die Properties Name, Description, MinorBuild, MajorBuild,
PatchLevel und Vendor eingetragen. Der BuildLevel wird bei jedem Build-Prozess automatisch
hochgezählt, auch der Timestamp wird dabei aktualisiert. Im Beispiel wird die Versionsnummer 0.9.1
definiert.
#Thu Dec 02 14:03:46 CET 2010
Name=SizingListImport
TimeStamp=2010-12-02T14\:03\:46 MEZ
MinorBuild=9
BuildLevel=36
PatchLevel=1
MajorBuild=0
Vendor=Myself
Description=Ein super Plugin
Zur Erstellung des JAR-Files wird die *Ant.xml aus dem Beispiel-Plugin kopiert und angepasst. Dabei
ist der Projektname anzupassen und der Name der Main-class zu überprüfen. Der Build-Prozess wird
wie beim Beispiel-Plugin gestartet.
Zusammenwirken des PlugIns mit dem EDADBManager
Hier werden kurz die wichtigsten Interfaces und einige Funktionen zum Zusammenwirken zwischen
EDADBManager und Plugin beschrieben. Die vollständige Dokumentation kann als JavaDoc
generiert werden (siehe Kapitel „Dokumentation der Interfaces“)
Interface IPlugin
initialize()
Nach dem Start des EDADBManagers werden alle jar-Dateien mit dem Interface IPlugin geladen.
Dabei wird der Konstruktor (falls vorhanden) aufgerufen und unmittelbar danach die Funktion
initialize. Die Funktion initialize hat als Parameter die Applikationsschnittstelle des
EDADB-Managers vom Typ IEDBManController. Dieser arbeitet als Controller im Model-ViewController (MVC) Entwurfsmuster.
Die Controller-Schnittstelle sollte für die weitere Verwendung in einer Variablen gespeichert werden.
public class MyPlugin implements IPlugin
{
private IEDBManController controller; // application interface
public void initialize( IEDBManController controller)
{
this.controller = controller;
}
...
}
start()
Nachdem das grafische Benutzerinterface des EDADBManagers initialisiert wurde, wird die Funktion
start aufgerufen. Hier können Menüeinträge für das Plugin erstellt werden.
EDADBManager Plugins
7
JMenuBar mb = controller.getFrame().getJMenuBar();
mnuExtras = mb.getMenu( mb.getMenuCount()-2 );
myMenuItem = new JMenuItem("SizingList...");
mnuExtras.insert( myMenuItem, 0);
stop()
Die Funktion stop wird aufgerufen, wenn das Plugin entladen werden soll. Hier sollten alle Objekte,
die in start angelegt wurden, wieder entfernt werden.
mnuExtras.remove( myMenuItem );
getVersionProps()
Die Methode getVersionProps liefert ein Properties Objekt, mit den folgenden
Eigenschaften:
Name ............ Kurzer Name für das Plugin
Description ..... Kurze Beschreibung
Vendor .......... Anbieter (Firma, Organisation, Privatperson)
MajorBuild ...... Hauptversionsnummer
MinorBuild ...... Unterversionsnummer
PatchLevel ...... Patch-Versionsnummer
BuildLevel ...... Aktuelle Build-Nummer
TimeStamp ....... Datum und Zeit der Erstellung
Diese Angaben können fest programmiert sein oder aus einer Datei gelesen werden.
Im Kapitel „Entwickeln eigener Plugins“ wird eine Methode beschrieben, in der diese Werte in einer
Textdatei im JAR stehen und bei jedem Build mit Ant die Werte von BuildLevel und TimeStamp
automatisch aktualisiert werden.
Interface IEDBManController
getFrame()
Liefert das Rahmenfenster des EDADBManagers als JFrame.
getCurrentSchematic()
Liefert ein IEDBSchematicView Interface der aktuellen Schaltung oder null.
setStatusText()
Stellt den Text in der Statuszeile ein
doCommand()
Ausführen eines Menükommandos des EDADBManagers:
newFile, loadLibrary, saveFile, saveAs, exportGraphic, createPDFDocu,
printFile, showAboutBox, showHelp
getModel()
Liefert das Inteface IEDBManModel des aktuellen Datenmodell (Dokument) .
EDADBManager Plugins
8
Interface IEDBManModel
getCatalog()
Liefert die Wurzel der Library – Cell – Cellview Hierarchie
updateAllViews()
Aktualisiert alle Fenster.
Interface IEDBSchematicView
getDesign()
Liefert das Dateninterface IDesign des aktuell dargestellten Cellviews. Mit dem IDesign Interface
kann durch die Elemente iteriert werden.
getSelection()
Liefert das Interface zu den aktuell selektierten Elementen mit der Möglichkeit, einen
SelectionListener zu installieren (Siehe IGraphicsSelectionInterface ). Die Selection
besteht aus einer Sammlung von IGraphicsObject interfaces, die eine graphisch Repräsentation
der EDADB Objekte darstellen.
Dokumentation der Interfaces
Die Interfaces sind in 3 Packages organisiert, die aufeinander aufbauen.
Package
Interfaces für …
org.imms.edadb.iface
Design-Daten und ihre Lib – Cell –View - Hierarchie
org.imms.edagr.iface
Grundfunktionen zur grafischen Darstellung der Daten
org.imms.edbmanager.iface
spezielle Funktionen des EDADBManagers
Im Projekt EDADBInterface findet man die Datei javadoc.xml. Durch Anklicken mit der rechten
Maustaste und Auswahl von „Run As – Ant Build“ wird die Dokumentation als JavaDoc generiert und
im Folder jdoc abgelegt. Der Eintrittspunkt ist die Datei index.html.
In einigen Fällen kann es sein, dass die JavaDoc-Generierung mit folgendem Fehler abbricht:
Javadoc failed: java.io.IOException: Cannot run program "javadoc.exe" …
Dann ist Ant mit dem Kontextmenübefehlt „Run As – Ant Build …“ zu konfigurieren. Im Reiter
„Environment“ ist mit der Schaltfläche „New…“ eine neue Variable „PATH“ zu erstellen und als
Wert der Pfad zu javadoc.exe zu setzen.
EDADBManager Plugins
9