= {appname} - DV-Konzept
Jens Kötterheinrich <jkh@beckmann-partner.de>
2020-05-06
ifndef::imagesdir[:imagesdir: images]
:appversion: 1.0
:source-highlighter: coderay
:pdf-page-size: A4
:appname: DocumentationTree
:project_root: ../..
:sourcedir: {project_root}/src/main/java
:lang: de
:sectnums:
:toc:

ifdef::lang[include::../theme/attributes-{lang}.adoc[]]

== Allgemeines
=== Zweck und Struktur des Dokuments
Dieses Dokument beschreibt die Anwendung {appname}.
Die Anwendung wird als Bestandteil von Dokumentation von Datenbanken verwendet.
Mit diesem Dokument soll der Leser in die Lage versetzt werden,
- den Aufbau und die Aufgaben der Anwendung zu verstehen,
- das System über die Benutzeroberfläche bedienen zu können,
- die Schnittstellen zu anderen Systemen zu kennen,
- im Falle eines Systemfehlers die geeigneten Maßnahmen ergreifen zu können.

== Übersicht
Die Anwendung {appname} basiert auf der Java Standard Edition.
Es wird mindestens die Version 8 vorausgesetzt.
Bei der Anwendung handelt es sich um eine JavaFX-Anwendung.
Sie lässt sich mit einer Java Runtime (>= Version 8u60) starten.
Alle fachlichen Vorgaben wurden durch Dr. Bruno Kaiser definiert.

== Funktionalität
Die Anwendung stellt folgende Funktionalitäten bereit:

- Öffnen und Parsen einer Datei mit LuaTable
- Darstellung als Baumstruktur
- Markieren von Knoten in unterschiedlichen Farben zur schnellen Übersicht und Analyse

== Dateibeschreibungen
=== LuaTable
Eine Lua-Datei besteht aus Lua-Code.
Darin wird eine LuaTable erzeugt und zurückgegeben.
Der Aufbau der LuaTable basiert auf https://webserver2.tecgraf.puc-rio.br/iup/en/elem/iuptree.html[IupTree].

.Beispiel LuaTable
[source,lua]
----
example =
{branchname="example",
  {branchname="foo", 'Hello'},
  {branchname="bar", 'world!'}
}

return example
----

== Programmdesign
=== Ablauf
==== Auswahl einer Datei
Nach dem Start der Anwendung wird ein leeres Fenster mit einem Menü angezeigt.
Im Menü kann über _Datei_ -> _Öffnen..._ eine Datei ausgewählt werden.
Die erlaubte Endung der zu öffnenden Dateien ist _.lua_.

==== Parsen einer ausgewählten Datei
Mit Hilfe des Frameworks

[source,xml]
----
<dependency>
    <groupId>org.luaj</groupId>
    <artifactId>luaj-jse</artifactId>
    <version>3.0.1</version>
</dependency>
----
wird die LuaTable geparst und eine Instanz von `org.luaj.vm2.LuaTable` erzeugt.
Das Framework wird mit dem Maven-Plugin _maven-assembly-plugin_ mit in das JAR gepackt, sodass nur eine Datei benötigt wird.

==== Erzeugen eines Baums
Auf Basis der erzeugten Instanz der LuaTable werden TreeItems erzeugt.
Dabei werden die Elemente der LuaTable rekursiv ausgewertet.
Einzelne Knoten werden als `javafx.scene.control.TreeItem` erzeugt, die zu einer javafx.scene.control.TreeView` hinzugefügt werden.
Standardmäßig werden Knoten immer aufgeklappt dargestellt.
Durch _state = 'COLLAPSED'_ kann für einen Knoten definiert werden, dass er initial nicht ausgeklappt dargestellt wird.

==== Darstellung
Die Klasse `javafx.scene.control.TreeView` ermöglicht die Darstellung von POJOs.
Dafür wird die Klasse `de.beckdev.TextNode` verwendet.

[source,java]
----
include::{sourcedir}/de/beckdev/TextNode.java[lines=21..72]
----

Eine Instanz von `de.beckdev.TextNode` kann in mehreren Instanzen von `javafx.scene.control.TreeItem` verwendet werden;
immer dann, wenn der Wert der Property `text` der Klasse `de.beckdev.TextNode` identisch ist.
Um Knoten zu färben wird die gewünschte Farbe der Property `color` zugewiesen.
Nachdem die Farben aller Knoten geändert wurden, wird die `javafx.scene.control.TreeView` neu aufgebaut.

==== Knoten selektieren
Ein Knoten kann durch einen Klick selektiert werden.
Dabei wird der Knoten blau markiert.
Erst wenn zum ersten Mal ein Knoten markiert wurde, wird der Button _Markieren_ aktiviert.

==== Knoten markieren
Wenn ein Knoten ausgewählt wurde, sollen Knoten nach folgenden Regeln gefärbt werden:

1. Der ausgewählte Knoten wird in blau gefärbt.
2. Knoten, deren Text mit dem des ausgewählten Knoten identisch sind, werden blau gefärbt.
3. Knoten über dem ausgewählten Knoten werden rot gefärbt; Knoten über den Knoten von 2. werden grau gefärbt.
4. Knoten unter dem ausgewählten Knoten werden grün gefärbt.
5. Knoten, die mit den Knoten unter 4. identisch sind, werden ebenfalls grün markiert.

Ein Knoten kann selektiert werden, ohne dass die Markierungen aufgehoben werden; dieser wird in gelb hervorgehoben.

==== Fehlerbehandlung
Beim Öffnen einer Datei werden mögliche Fehler abgefangen und in einem Fehlerdialog dargestellt.

=== Benutzeroberfläche
=== Start
image::Startbildschirm.png[Auswahl einer Datei]

=== Datei als Baum anzeigen
image::VollerBaum.png[Anzeige einer Datei als Baum]

=== Gefärbte Knoten
image::GefaerbteKnoten.png[Gefärbte Knoten]

=== Gefärbte Knoten mit Unterknoten
image::GefaerbteKnotenMitUnterknoten.png[Gefärbte Knoten mit Unterknoten]

=== Fehlermeldung
==== Keine Datei ausgewählt
image::FehlermeldungKeineDatei.png[Fehlermeldung bei nicht ausgewählter Datei]
==== Fehler in Datei
image::FehlermeldungSyntax.png[Fehlermeldung bei fehlerhafter Datei]
