# HG changeset patch
# User Sascha L. Teichmann <sascha.teichmann@intevation.de>
# Date 1345733095 0
# Node ID 4f16070b917b590d08500541c2576916f9c7d412
# Parent  6603aeeda6e3721b44b9b839041eb7d033ee016b
backend: Added first part of the importer documentation.

flys-backend/trunk@5250 c6561f87-3c4e-4783-a992-168aeb5c3f6f

diff -r 6603aeeda6e3 -r 4f16070b917b flys-backend/ChangeLog
--- a/flys-backend/ChangeLog	Thu Aug 23 14:01:21 2012 +0000
+++ b/flys-backend/ChangeLog	Thu Aug 23 14:44:55 2012 +0000
@@ -1,3 +1,8 @@
+2012-08-23	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
+
+	* doc/README.txt: Documentation for the importer (german).
+	  TODO: db crendentials, warning & errors, annotation types.
+
 2012-08-22  Ingo Weinzierl <ingo@intevation.de>
 
 	* contrib/shpimporter/run.sh: Moved 'SKIP_XXX' variables to the top of
diff -r 6603aeeda6e3 -r 4f16070b917b flys-backend/doc/README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/flys-backend/doc/README.txt	Thu Aug 23 14:44:55 2012 +0000
@@ -0,0 +1,103 @@
+FLYS3-Importer
+
+Der FLYS3-Importer dient dazu, hydrologische und morphologische
+Gewässerdaten aus dem Dateisystem in die FLYS3-Datenbank zu importieren.
+Das Werkzeug orientiert sich hierbei an der Dateihierachie,
+so wie sie auch von Desktop-FLYS ausgelesen wird.
+
+Als Startargument bekommt der Importer den Pfad zu einer
+GEW-Datei übergeben. 
+
+Wichtig für den Importer sind in dieser Datei
+die Zeilen, die mit "WSTDatei:" beginnen. In ihnen wird der 
+Pfad zu der zentralen WST-Datei des jeweiligen Gewässers angegeben.
+Alle anderen importierten Dateien werden in ihrer Lage relativ zur 
+Lage dieser Datei betrachtet.
+
+Das Verhalten des Importes kann mit sogenannten
+System-Properties gesteuert werden. Diese werden im
+Allgemeinen in der Form -Dkey=value angegeben.
+
+Will man z.B. mit dem Importer nur in simulierierten Import
+durchführen, dann kann dies über die Angabe von
+'-Dflys.backend.importer.dry.run=true' erfolgen.
+
+!!! Der Import geht wie Desktop-FLYS davon aus, dass die Dateien
+!!! Latin-1 encodiert vorliegen.
+
+Für den Importer stellt jeweils der Import eines Gewässers eine
+transaktionale Einheit dar. Wird der Import während eines Gewässers
+abgebrochen, werden alle Änderungen bzgl. dieses Gewässers zurück gerollt.
+
+Importierte Daten:
+
+Der Importer importiert folgende Datentypen:
+
+- Streckenfavoriten (*.km-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.annotations=true'
+  unterdrückt werden.
+
+  TODO SLT: flys.backend.importer.annotation.types erklären!
+
+- Pegel, Stammdaten (*.glt, *.sta-Dateien):
+  Der Import kann mit '-Dflys.backend.importer.skip.gauges=true'
+  unterdrückt werden.
+
+- Basis-Wasserstände (gewaesser.wst-Dateien):
+  Der Import kann mit '-Dflys.backend.importer.skip.wst=true'
+  unterdrückt werden.
+
+- Zusätzliche Längsschnitte (*.zus, *.wst-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.extra.wsts=true'
+  unterdrückt werden.
+
+- Fixierungen (*.wst-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.fixations=true'
+  unterdrückt werden.
+
+- Amtliche Linien (*.wst-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.official.lines=true'
+  unterdrückt werden.
+
+- Profilspuren (*.prf-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.prfs=true'
+  unterdrückt werden.
+
+- Hydraulische Kennzahlen (*.hyk)
+  Der Import kann mit '-Dflys.backend.importer.skip.hyks=true'
+  unterdrückt werden.
+
+- Hochwassermarken (*.zus)
+  Der Import kann mit '-Dflys.backend.importer.skip.flood.water=true'
+  unterdrückt werden.
+
+- Hochwasserschutzanlagen (*.zus)
+  Der Import kann mit '-Dflys.backend.importer.skip.flood.protection=true'
+  unterdrückt werden.
+
+  TODO INGO:
+
+  flys.backend.importer.skip.bed.height.single
+  flys.backend.importer.skip.bed.height.epoch
+  flys.backend.importer.skip.sediment.density
+  flys.backend.importer.skip.morphological.width
+  flys.backend.importer.skip.flow.velocity
+  flys.backend.importer.skip.sediment.yield
+  flys.backend.importer.skip.waterlevels
+  flys.backend.importer.skip.waterlevel.differences
+  flys.backend.importer.skip.sq.relation
+
+TODO SLT: Datenbank-Credentials dokumentieren.
+
+TODO SLT: Fehler und Warnungen aus separater Datei hier hin.
+
+Betrieb:
+
+    Der Speicherverbrauch des Importers ist sehr hoch. Es ist empfehlenswert,
+    der JVM mindestens 8GiB Haupspeicher zuzuordnen: '-Xmx=8192m'
+    Besonders speicherintensiv ist der Import der HYKs und der PRFs.
+    Hier ist es unter Umständen empfehlenswert, diese in zwei oder drei
+    Schritten zu importieren. Zuerst die sonstigen hydrologischen Daten
+    (hierbei mit flys.backend.importer.skip.hyks=true und flys.backend.importer.skip.prfs
+    den Import der HYKs und PRFs verhindern). Dann die HYKs (mit flys.backend.importer.skip.*
+    der anderen Daten) und im finalen Schritt dann die PRFs.