SAA: DotPlot-Portierung

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Im Rahmen der Veranstaltung Softwarearchitektur und Anwendungsentwicklung (SAA) wollen wir das DotPlot-Projekt von der Eclipse Version 3.1 auf die aktuelle Version 3.5 portieren.

Portierung

Herausforderungen

Strategische Maßnahmen

Migration vor Merge

  • Wissen über Branches gering (Wizard nicht auffindbar)
  • Funktionalität des Wizards in Versionen unter 3.3 unklar (oder sogar nicht vorhanden)

Durchführung der Migration

Als besonders hilfreich haben sich die beiden folgenden Internetseiten herausgestellt:


Wiederinbetriebnahme unter 3.1
  • Nicht "trunk" sondern "org.dotplot.plugin" auschecken
  • Leerzeichen im Pfad zum Workspace führen zu Problemen und müssen daher vermieden werden.

Umstellung 3.1 -> 3.2
  • Bewusste Ausnutzung der Abwärtskompatibilität
Änderungen wurden so spät wie möglich durchgeführt, damit Probleme nicht zwei Mal gelöst werden mussten.
Hauptaufgabe 3.2 -> 3.3
  • Einführung von JAR-signing
  • Änderungen an:
    • OSGi-Konfiguration: Manifest.mf und
    • Eclipse-spezifischer Konfiguration: plugin.xml
  • Application model changes (unter Ausnutzung der Abwärtskompatibilität erst später umgesetzt)
    • org.eclipse.equinox.app löst org.eclipse.core.runtime ab
Migration 3.3 -> 3.4
  • Läuft auf Mac OS, Linux, Windows
  • Ausstehende Aufgaben erledigen
Abschluss 3.4 -> 3.5
  • Aktualisierung der Abhängigkeiten
  • Anpassen der Application ID

Probleme und Herausforderungen

Inventarliste der externen Bibliotheken

[Stand 16.06.2009]

Java Advanced Imaging (JAI)[3]
Umstieg von der Version 1.1.2 auf die Version 1.1.3 der Bibliotheken: jai_core und jai_codec.
Zwischen den Versionen wurden einige Bugfixes vorgenommen und die Performanz gesteigert.
Unberührt blieben: jai_imageio, jai_mlibwrapper und clibwrapper_jiio
JavaMail API[4] *
Umstieg von der Version 1.3.2 auf die Version 1.4.2 vom 02.03.2009.
Zwischen den Versionen wurden umfangreichen Änderungen vorgenommen.
Neben zahlreichen Bugfixes wurden auch Veränderungen an der API vorgenommen.
JavaBeans Activation Framework (JAF)[5] *
Umstieg von der Version 1.0.2 auf die Version 1.1.1 vom 22.10.2007.
Zwischen den Versionen wurden zahlreichen Bugfixes vorgenommen.
Apache log4j[6]
Umstieg von der Version 1.2.8 auf die Version 1.2.15 vom 24.08.2007.
Neben zahlreichen Bugfixes wurden kleinere Veränderungen an der API vorgenommen und ein neues Log-Level: TRACE eingeführt.
Apache PDFBox[7]
Umstieg von der Version 0.7.2 auf die Version 0.7.3 vom 10.12.2006.
Neben zahlreichen Bugfixes wurden kleinere Veränderungen an der API vorgenommen.
iText[8]
Umstieg von der Version 1.4.2_04-b05 auf die Version 2.1.5 vom 23.06.2006.
Zwischen den Versionen wurden umfangreichen Änderungen vorgenommen.
Neben zahlreichen Bugfixes wurde der Quellcode aufgeräumt und neu organisiert.
Daraus resultieren unter anderem auch Veränderungen an der API.
Info.png

* Die JavaMail API benötigt das JavaBeans Activation Framework (JAF). Dieses wird seit Java 1.6 mitgeliefert. Aus Gründen der Abwärtskompatibilität wird JAF aber weiterhin mit DotPlot ausgeliefert.

Struktur des Subversion-Repositories

  • branches
    • feature
      • [DotPlotForAppEngine]
      • [CloudGrid]
    • release
      • [2.4]
      • [2.5]
  • tags
    • 2.1.1
    • [2.4]
    • [2.5]
  • trunk
    • ...

Diese Struktur findet sich in vielen Open Source Projekten wieder (z.B. PHPUnit). Die Idee ist, dass grundsätzlich die Entwicklung im Trunk stattfindet. Parallel dazu kann aber die Entwicklung von neuen Features in separaten Feature-Branches erfolgen. Dies ist zum Beispiel dann sinnvoll, wenn diese Features die Hauptentwicklung zu Anfang eher behindern würden. Branching ist immer problematisch, daher sind die Entwickler dazu angehalten, ständig die Änderungen aus dem Trunk zu migrieren. Dadurch lassen sich Probleme wie verlorengegangene Änderungen minimieren.

Im Gegensatz zu reinen Webapplikationen erfordert das DotPlot-Projekt ein etwas klassischeres Release-Management. Nachdem diverse Meilensteine genommen wurden, steht üblicherweise ein neues Release an. Dieses Release soll in einem separaten Release-Branch vorbereitet werden. Dort können dann in Ruhe die letzten Schritte bis zum fertigen Release gegangen werden. Üblicherweise trägt der Branch die Versionsnummer des Releases. Ein Release-Branch bietet auch die Möglichkeit, dass später Bugfixes für ein bestimmtes Release veröffentlicht werden können. Jedes Release wird außerdem unter der veröffentlichten Versionsnummer getaggt.

Weitere Projektregeln

Die Commit-Kommentare müssen auf Englisch verfasst werden. Ein Commit-Kommentar sollte nie leer bleiben oder mehrmals das gleiche Kommentar für unterschiedliche Änderungen verwendet werden. Dies macht nämlich das Nachvollziehen der Änderungen durch die übrigen Entwickler viel zu schwer. Desweiteren ist es wichtig, dass jeder Entwickler sich unter seinem echten Vornamen und Nachnamen registriert. Auch dies fördert die Kommunikation.

Kodierrichtlinien

Als Richtlinie für Checkstyle dienen die Vorgaben von Sun (mit geringfügigen Anpassungen für die Eclipse). Die Richtlinien von MNI bilden zwar die Basis, einige Regeln konnten allerdings nicht formalisiert werden. Ein Beispiel hierfür ist die aussagekräftige Namensgebung von Variablen. Mit Hilfe der angepassten "Save Actions" wird dem Programmierer einige Arbeit abgenommen, zum Beispiel die Formatierung oder die Pflege der Importe. Wie erwähnt wird er jedoch nicht gänzlich von seinen Pflichten entbunden, er muss also weiterhin dafür sorgen, dass er Richtlinien wie die bereits beschriebene Namensgebung oder den Verzicht auf innere Klassen einhält. Sofern möglich werden derartige Verstöße von Checkstyle gemeldet.

Analyse des bestehenden Quellcodes

Metriken nach Robert C. Martin

  • Vorher- / Nachher-Metriken werden vom Architektur-Dokumentationsteam gezeigt.
  • Die Metriken auf dem Hudson sind weithin bekannt und jeder kann sie sich anschauen.
  • Daher Experimente mit anderen Tools (Metrics Plugin für Eclipse)
    • Metriken auf Basis der Expertise von Robert C. Martin (Bild des Buches)
    • Teilweise ähnlich zu den Metriken am Hudson
    • Beschreibung der Unterpunkte in der Übersicht (nicht alle, nur ein paar)
    • Wo finde ich den Fehler (Baumstruktur, simple Navigation -> Doppelklick führt einen zur Fehlerursache)
    • Warum tritt an den Stellen ein Fehler auf?

Unit-Tests

Für das DotPlot-Projekt existieren knapp 400 Unit-Tests. Die Qualität dieser Tests wird hier analysiert. Generell gilt, dass diese Tests offensichtlich nicht mit einem Test-First-Ansatz erstellt wurden. Dies fällt bereits beim ersten Blick auf eine beliebige Testklasse auf.

Langsam laufende Tests

Die Ausführungsdauer aller Unit-Tests beträgt etwa 30 Sekunden. Dies ist bereits zu lange um effektiv arbeiten zu können. Der Grund hierfür ist, dass das Konvertieren von Daten zu PDFs und umgekehrt sehr zeitintensiv ist. Es sollte daher eine weitere Testsuite geben, die exemplarisch eine Konvertierung durchführt (Smoke Test), damit die Tests schneller durchlaufen. Vor dem Integrieren kann und muss aber wieder die komplette Testsuite ausgeführt werden. Eine andere Möglichkeit wäre der Einsatz von Test-Doublen. Dies muss aber genauer geprüft werden.

Innere/Anonyme Klassen

In den Tests werden häufig anonyme Klassen erstellt. Diese Praxis ist eher fragwürdig, da der Test dadurch auseinandergezogen wird und die Intention nicht mehr deutlich erkennbar ist. Stattdessen sollten diese Klassen ausgelagert werden. Eine Alternative bietet der Einsatz von Mock-Objekten. Hierfür wäre allerdings ein externer Framework nötig. Ob die Einführung einer solchen Abhängigkeit gewünscht ist, müsste erst geklärt werden.

Mehrere Testfälle in einer Methode

Als weiterer Test-Smell ist zu nennen, dass mehrere Testfälle in einer Testmethode geprüft werden. Auch dies ist eine schlechte Praxis. Damit entsteht außerdem der Anschein, als ob nicht ein Feature, sondern die Methoden an sich getestet wurden. Hier besteht also Refaktorisierungsbedarf. Die Klasse org.dotplot.tokenizer.converter.tests.DefaultConverterConfiguration mit der Methode testObjectForm() zeigt einen solchen Aufbau. Beachtenswert ist auch das Verwenden einer plattformspezifischen Pfadangabe (Zeile 120). Dieser Test wird auf allen Nicht-Windows-Betriebssystemen garantiert fehlschlagen.

Warnungen mit hoher Priorität

An dieser Stelle gehen wir auf einige von den Hudson-Metriken mit hoher Priorität markierten Warnungen ein. Sehr häufig wird zum Beispiel bemängelt, dass zu einer Implementierung der equals-Methode die dazugehörige Implementierung der Methode hashCode fehlt. In Java ist es ein Gesetz, dass wenn equals überschrieben wird, auch hashCode überschrieben werden muss [9]:

"If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result."

Die Implementierung von hashCode ist Situationsabhängig und nicht trivial. Mehr dazu findet sich im Artikel How to Write an Equality Method in Java.

Ein weiterer Punkt ist das Verwenden von einem Array, welches zwar als static final angelegt, gleichzeitig aber komplett öffentlich ist. Dieses Array kann daher von außerhalb manipuliert werden, was höchstwahrscheinlich nicht vorgesehen ist. Das Werkzeug FindBugs erkennt diesen Fehler [10]:

"A final static field references an array and can be accessed by malicious code or by accident from another package. This code can freely modify the contents of the array."

Ein Beispiel für ein solches Array findet sich hier: org.dotplot.core.IDotplot Zeile 65

Es gibt auch ein Beispiel für eine mögliche Dereferenzierung von null: org.dotplot.eclipse.actions.PlotAction Zeilen 223ff. Hier wird nur ein Objekt angelegt, wenn eine Exception auftritt!

Teilweise wird außerdem auf eine Klassenvariable aus einem Objektkontext heraus zugegriffen. Auch dies ist für FindBugs ein Fehler mit hoher Priorität. Ein Beispiel ist in der Klasse org.dotplot.grid.GridServer Zeile 47 zu finden.

Im Vergleich zur Eclipse Version 3.1 hat sich die API in Version 3.4 an einigen Stellen geändert. Die alte API steht zwar weiterhin zur Verfügung, ist aber als deprecated markiert. Daher wurden diese Stellen angepasst. Hier auszugsweise ein Changeset, welches die Veränderungen der API veranschaulicht: Changeset 2288

Offener Handlungsbedarf

Neue Update-Sites unterstützen

Die Eclipse bietet jetzt eine neue Möglichkeit eine Update-Site anzubieten. Sollte dieses Feature bereits von DotPlot genutzt werden, müssen die bestehenden Strukturen an die neuen Bedingungen angepasst werden. Nutzt DotPlot allerdings noch keine Update-Site, lohnt es sich für die Zukunft zu überlegen, ob dieses Feature nicht auch für das DotPlot-Projekt genutzt werden sollte. Die Anwender der Software würden dadurch von dem verbesserten Aktualisierungsprozess profitieren.

Branches Parser und BioJava nicht lauffähig

Die beiden Branches Parser und BioJava sollten genau wie der Wizard in den Hauptentwicklungszweig migriert werden. Die beiden Branches sind auch vorhanden, allerdings in keinem lauffähigen Zustand. In den Parser-Branch wurde bereits BioJava migriert, auf den ersten Blick scheint der Migrationsaufwand also gering. Jedoch stellte sich heraus, dass sich der BioJava-Teil des Branches nicht kompilieren ließ. DotPlot ließ sich daher erst gar nicht ausführen. Es scheint auch, als seien die neuen Teile des Parsers noch gar nicht an das Projekt angeschlossen worden. Eine Migration dieses Branches ist daher generell fraglich.

Der BioJava Branch ließ sich dagegen kompilieren und ausführen. Allerdings gab es auch hier ein Problem: DotPlot startet zwar, aber kein einziger Menüpunkt oder Button führte eine Aktion aus. Es konnte daher nicht ermittelt werden, ob die BioJava-Funktionalität fertiggestellt wurde. Daher wurde auch hier auf eine Migration verzichtet.

Lehrvideo mit eXe und Camtasia

Die folgenden Themen sind Bestandteil der Lehreinheit:

Einrichtung der Entwicklungsumgebung:

  • Eclipse-Installation auf verschiedenen Plattformen
  • Integration von Subversive u. Einführung in die Bedienung
  • Integration von Checkstyle u. Einführung in die Bedienung
  • Arbeiten mit JUnit

Einstieg in das DotPlot-Projekt:

  • DotPlot-Checkout u. Inbetriebnahme
  • Projekt-Konventionen (Kodierrichtlinien u. Eclipse-Einstellungen)
  • SVN-Struktur

Ziel unseres Lehrvideos ist es die Studenten

  • sowohl beim Einstieg in die Eclispe-Entwicklungsumgebung
  • als auch bei der Weiterentwicklung von DotPlot

...zu unterstützen.

Hier geht's zur finalen Version: DotPlot - getting started

Die Sources liegen als aufgeteilte 7-Zip Archive vor, leider mussten wir diesen einzeln noch einmal "zippen", da .00x Files nicht hochgeladen werden dürfen. Hier die Links zu den Dateien:

Literatur

  • Jeff McAffer, Jean-Michel Lemieux: Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications. Addison-Wesley Longman, Amsterdam. ISBN: 0321334612
  • Frank Westphal: Testgetriebene Entwicklung mit JUnit & FIT: Wie Software änderbar bleibt. Dpunkt Verlag. ISBN: 3898642208

Referenzen

--Thelen-CTh 06:44, 16. Jun. 2009 (UTC)

--Hoffmann-PHo58 11:17, 16. Jun. 2009 (UTC)

--Leupold-HLe 12:40, 7. Aug. 2009 (CEST)

--Philippi-SPh 12:42, 7. Aug. 2009 (CEST)