sql2json

Der sql2json Transformator (Trafo) arbeitet pro Programmaufruf ein Json-Template mit n im Template enthaltenen Trafo-Tags ab. Für jedes Trafo-Tag setzt der Trafo ein Sql-Statement auf die Metadatenbank ab und ersetzt das Trafo-Tag mit dem Ergebnis des SQL-Queries.

Falls beim Aufruf ein Json-Schema angegeben wird, validiert der Trafo das erzeugte Json gegen das Schema.

In den folgenden Kapiteln ist die Konfiguration und Benutzung des Trafo beschrieben. Die Entwicklerdoku ist hier zuhause.

Der Trafo ist ein executable fat jar, welches via Releases im Github-Repo bezogen werden kann.

Befehl zur Ausgabe der Hilfe:

java -jar sql2json.jar -h

Die Konfiguration des Trafo erfolgt mittels Kommandozeilenparameter und/oder Umgebungsvariable. Bei Variablen, welche sowohl auf Kommandozeile wie in Umgebungsvariable definiert sind, wird der Wert der Kommandozeile verwendet.

Netzpfad:

• Als absolute URL "http(s)://..." oder Dateipfad angeben
• Bsp. Dateipfad: opt/user/trafo/wms/template.json

Siehe die Integrationstests als Beispiele:

• exit_ok.sh: Aufruf via Kommandozeilen-Parameter
• env_ok.sh: Aufruf via Umgebungs-Variablen
• validation_ok.sh: Aufruf der Validierung

Trafo nutzt die Bibliothek slf4j-simple. Loglevel und Ausgabeformat können mittels Java-Variablen gesetzt werden.

Setzen des Log-Levels:

java -Dorg.slf4j.simpleLogger.defaultLogLevel=warn -jar sql2json.jar

Log-Level: "trace", "debug", "info", "warn", "error" oder "off". Default: "info"

Siehe javadoc der Klasse SimpleLogger bezüglich der weiteren Konfigurationsmöglichkeiten des Loggings.

java -Dorg.slf4j.simpleLogger.defaultLogLevel=warn -jar sql2json.jar \
  -c jdbc:postgresql://localhost/postgres \
  -u postgres \
  -p postgres \
  -t $(pwd)/template.json \
  -o $(pwd)/result.json

Für jedes Trafo-Tag, welches der Trafo im Json-Template antrifft, werden die folgenden Schritte durchgeführt. Der Trafo:

• setzt das im Trafo-Tag referenzierte SQL-Query auf die Datenbank ab. Der Pfad zur Query-Datei wird relativ zum Template-Pfad aufgelöst, damit die Sql-Dateien auch in Unterverzeichnissen geordnet werden können.
• verarbeitet das SQL Resultset in ein Json-Element.
• ersetzt im Output.json das Trafo-Tag mit dem Json-Element.

Das Trafo-Tag ist ein Json-Objekt, dessen Name mit "$trafo:" beginnt: {"$trafo:elem": "object.sql"}

Typen:

• "$trafo:elem": Rendert ein einzelnes Json-Element in das Output-Json. Typen von Json-Elementen:
  • "Primitive" Werte (String, Number, Boolean, Null)
  • Liste von Elementen: [...]
  • Objekt: {...}
• "$trafo:list": Rendert eine Liste von Json-Elementen in das Output-Json.
  • Die Elemente der Liste können wiederum Primitivwerte, Objekte oder Listen sein.
• "$trafo:set": Rendert ein Objekt mit Name-Wert-Paaren in das Output-Json.
  • Der Name in den Paaren ist ein String.
  • Die Werte in den Paaren können wiederum Primitivwerte, Objekte oder Listen sein.

Template-Ausschnitt

{
	"fuu": "...",
	"layer": {"$trafo:elem": "element.sql"},
	"bar": "..."
}

Query-Rückgabe

Der Trafo verwendet die erste zurückgegebene Spalte des Resultsets.

• Spaltenname ist egal
• Aus dem Db-Typ der Spalte leitet der Trafo das passende Json-Element ab
  • Json, Jsonb -> Objekt oder Liste
  • Varchar, Number, .... -> entsprechender Json "Primitivtyp"

Json-Ausgabe

{
	"fuu": "...",
	"layer": "ch.so.agi.gemeindegrenzen",
	"bar": "..."
}

Template-Ausschnitt

{
	"fuu": "...",
	"layers": {"$trafo:list": "objectlist.sql"},
	"bar": "..."
}

Query-Rückgabe

Verhalten bezüglich der Spaltentypen identisch wie bei {"$trafo:elem": "..."}

Json-Ausgabe

{
	"fuu": "...",
	"layers": [{
			"id": "ch.so.agi.gemeindegrenzen",
			"title": "Gemeindegrenzen",
			"visible": true
		},
		{
			"id": "ch.so.agi.bezirksgrenzen",
			"title": "Bezirksgrenzen",
			"visible": false
		}
	],
	"bar": "..."
}

Template-Ausschnitt

{
	"fuu": "...",
	"layers": {"$trafo:set": "objectset.sql"},
	"bar": "..."
}

Query-Rückgabe

Der Trafo verwendet die ersten beiden zurückgegebenen Spalten des Resultsets.

• Die Spaltennamen sind egal
• Der Db-Typ der ersten Spalte muss ein String sein (varchar, ...)
• Aus dem Db-Typ der zweiten Spalte leitet der Trafo das passende Json-Element ab
  • Json, Jsonb -> Objekt oder Liste
  • Varchar, Number, .... -> entsprechender Json "Primitivtyp"

Json-Ausgabe

{
	"fuu": "...",
	"layers": {
		"ch.so.agi.gemeindegrenzen": {
			"title": "Gemeindegrenzen",
			"visible": true
		},
		"ch.so.agi.bezirksgrenzen": {
			"title": "Bezirksgrenzen",
			"visible": false
		}
	},
	"bar": "..."
}

Die Integrationstests sind gute erläuternde Komplettkonfigurationen (mit Template, Trafo-Tag, Sql-Datei). Siehe die auf _ok.sh endenden Integrationstests in Ordner [Repo-Root]/inttest.

Beim Auftreten eines Fehlers wird das Json-Tag mit dem Fehlertext "erweitert" und in das output-json geschrieben. Zusätzlich wird ein umfangreicher Fehleroutput auf den Error-Stream geschrieben.

Bei einem Fehler bei der Verarbeitung eines Trafo-Tag wird die Verarbeitung der weiteren Tag's nicht abgebrochen. Die auftretenden Fehler werden sequentiell ausgegeben. Bei einem Fehler gibt der gestartete Java-Prozess <> 0 als exit value zurück.