sebastianknopf/uic-tlb-interpreter

interpreter library for UIC layout tickets

uic-tlb-interpreter's Issues

Einrichtung Kommandozeilen-Tool

Zusammenfassung
Die aktuelle Variante der Kommandozeilenanwendung ist eher zusammengehacked und dient bislang nur Demozwecken. Perspektivisch soll die Konsolenanwendung auch einen interaktiven Assistenten bieten, mit dem Interpreter erstellt werden können. Dazu sind einige Anpassungen notwendig.

Akzeptanzkriterien

• Das existierende "Demo"-Artefakt wurde umbenannt zu "Console"
• Das Console-Artefakt enthält eine saubere Package-Struktur, die Mainklasse wurde entsprechend verschoben
• Es existiert eine erste Version einer sauberen Console-Klasse, die wichtige Basisfunktionen zur Interaktion mit der Konsole bietet

Interpreter-Datei für SWA Deutschlandtickets

Zusammenfassung
Hi Sebastian,
ich habe einen Interpreter für Deutschlandtickets der Stadtwerke Augsburg angelegt. Du kannst gerne einmal schauen ob die Datei so in Ordnung ist. Wenn alles passen sollte, dann kannst du den Interpreter gerne in deiner Sammlung aufnehmen.
SWA_DTicket_Interpreter.json

Falls noch was sein sollte, kannst du gerne Fragen.

Gruß Thomas

Optionale Felder

Zusammenfassung
Stand jetzt ist es nicht möglich, Layoutfelder in ihrem Vorhandensein als optional zu kennzeichnen. Es kann bisher lediglich der Ergebniswert als optional gekennzeichnet werden, was bedeutet, dass dieser Null werden darf. Wenn jedoch das referenzierte Layoutfeld nicht vorhanden ist, wird eine Exception geworfen.

Zukünftig soll keine Exception mehr geworfen werden, wenn ein referenziertes Layoutfeld nicht enthalten ist. Stattdessen soll der gesamte Ergebniswert als "nicht vorhanden" (=Null) gekennzeichnet werden.

Beispiel: Ein Issuer gibt Barcodes mit derselben MessageTypeVersion und derselben Record-Version aus. Auch das Layout ist gleich, nur das Feld für das Geburtsdatum ist manchmal vorhanden und manchmal nicht. Nach bisherigem Stand müssten für diese beiden Fälle zwei Interpreter hinterlegt werden, einer mit und einer ohne Geburtsdatum. Wird nun durch ungeschickte Dateibenennung aber zunächst der Interpreter ohne Geburtsdatum versucht auszuführen, führt das unweigerlich dazu, dass das Geburtsdatum nie für diesen Issuer ausgelesn wird, da der erste Versuch mit dem Interpreter ohne Geburtsdatum immer gelingen wird und der zweite Interpreter so nie zum Zuge käme. Indem das Geburtsdatum als optional gekennzeichnet wird, kann es problemlos auch den Wert Null annehmen, wenn das Layoutfeld dazu nicht vorhanden ist.

Akzeptanzkriterien

• Wird ein Ergebniswert als optional definiert, wird keine Exception geworfen, wenn eines der referenzierten Layoutfelder nicht vorhanden ist

Interaktiver Kommandozeilen-Assistent

Zusammenfassung
Aktuell müssen JSON-Interpreter noch händisch angelegt und dann getestet werden. Das ist z.T. sehr Zeitraubend und nicht wirklich anwenderfreundlich. Daher soll ein interaktiver Kommandozeilen-Assistent entworfen werden, der es Endnutzern oder dem 1st-Levelsupport ermöglicht, selbst Interpreter erstellen zu können.

Der Ablauf nach dem Start des Assistenten soll folgendermaßen sein:

• Der Benutzer wird aufgefordert, eine JSON-Datei der App (((eTicketInfo einzulesen. Der Inhalt dieser Datei wird dann auf zwei Arten analysiert: Zum einen wird das Layout einmal als solches auf der Konsole ausgegeben, zum anderen werden die einzelnen Layoutfelder nochmals als Liste mit Zeile und Spalte ausgegeben, sodass man später nicht lange danach suchen muss. Vor dem Layout wird außerdem der Carrier-Code, die Message-Version, die Record-Version und der Layout-Standard als Kopfinformation auagegeben.
• Im nächsten Schritt werden die Spezifikations-Constraints abgefragt. Als Default-Werte sind hier jeweils die bereits ermittelten Werte für Carrier, ... hinterlegt.
• Anschließend wird der Benutzer gefragt, ob es weitere Bedingungen gibt, die für den Interpreter erfüllt sein müssen. Ist dies der Fall, werden die Feld-Constraints abgefragt, bis der Benutzer angibt, keine Constraints mehr zu haben.
• Nun beginnt die eigentliche Arbeit, der Assistent fragt der Reihe nach jeden verfügbaren Feld-Typ ab. Zu jedem Feld-Typ werden alle notwendigen Parameter abgefragt. Nach jedem angegebenen Feld wird der Wert, wie er aktuell geparsed würde, zur Info angezeigt. Wenn der Wert so in Ordnung ist, wird fortgefahren, ansonsten wird die Abfrage der Felder wiederholt. Abschließend werden ggf. zusätzlich notwendige Parameter abgefragt. So wird beim validFrom z.B. ein Format abgefragt, bei der Starthaltestelle hingegen nicht. Abschließend wird der geparsede Wert nochmals zur Kontrolle angezeigt, sofern dieser vom Benutzer angenommen wird, wird das Ergebnis so gespeichert, falls nicht, beginnt die Abfrage für das Ergebnisfeld von vorne.
• Am Ende wird nach einer Bezeichnung und einer Versionsinfo für den Interpreter, sowie einem Dateinamen gefragt und die finale Datei geschrieben.

Dieses Ticket dient als Epic zum kapseln der vier einzelnen Tickets bzgl. Assistentenumsetzung. Außerdem sollen in diesem Ticket globale Entscheidungen getroffen werden.

Folgende Punkte müssen noch überlegt werden:

• Was für eine Sprache soll zur Interaktion genutzt werden? Deutsch oder Englisch? In Englisch wäre die Interaktion leichter zur Geltung zu bringen, auf Deutsch wäre ein breiterer Nutzerkreis abgedeckt, die Sprache allerdings deutlich formeller
• Bestimmte Punkte wie z.B. das Parsen der einzelnen Felder sollte eigentlich von der Interpreterlogik übernommen werden, nicht über eine Zweitimplementierung im Assistenten. Nur so kann sichergestellt werden, dass auch die tatsächliche Reaktion des Interpreters sichtbar wird. Allerdings sind die meisten Felder im Interpreter protected oder private, d.h. diese müssten erst über Reflection sichtbar gemacht werden. Möglicherweise gibt es einen anderen Weg, bswp. eine externalisierte API? Es muss geklärt werden, bis auf welche Tiefe man mit dem Interpreter herunter muss. Dies wird interaktiv im entspr. Ticket ermittelt
• Welche Kommandozeilenparameter soll die gesamte uic-interpreter-console.jar verarbeiten? Ein Argument mit dem auszuführenden Kommando wäre ausreichend.
• Welche Kommandos sollten umgesetzt werden? Allen voran wohl view zum simplen Anzeigen der Ticket-Daten und assistant zum Ausführen des Assistenten.

Umsetzung View-Command

Zusammenfassung
Endnutzer sollen die Möglichkeit haben, die Daten aus einem UIC918.3 Code sowohl als Layout, als auch als Tabelle anzeigen zu lassen.

Akzeptanzkriterien

• Es existiert eine Kommandoklasse für das "view" Kommando
• Das View-Kommando wird in der Mainklasse aufgerufen
• Es existiert eine Implementierung, welche das Ticketlayout einmal graphisch anzeigt und einmal als Tabelle ausgibt
• Zur Ausgabe existiert jeweils eine eigene Methode

Implementierungshinweise

• Die Anzeige-Implementierung muss sowohl den StaticFrame, als auch das Layout des UIC-Tickets abfragen

Schreiben von JSON-Interpretern

Zusammenfassung
Aktuell ist die Bibliothek nur in der Lage, Interpreter-JSONs zu lesen. Zukünftig soll die Lib auch Interpreter-JSONs schreiben können.

Akzeptanzkriterien

• Analog zum Lesen einer JSON existiert eine Methode zum Schreiben einer passenden JSON