--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/backend/doc/README.txt	Thu Apr 25 15:23:37 2013 +0200
@@ -0,0 +1,528 @@
+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 einen simulierten Import
+durchführen (also nicht in die Datenbank geschrieben werden),
+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.
+
+  Zur Klassifikation von Streckenfavoriten kann mit
+  -Dflys.backend.importer.annotation.types=DATEI
+  der Pfad zu einer XML-Datei angegeben werden, in der über
+  Regeln festgelegt wird, wie diese geschehen soll.
+  Details hierzu im Anhang 'Klassifikation von Streckenfavoriten'.
+
+- Pegel, Stammdaten (*.glt, *.sta-Dateien):
+  Der Import kann mit '-Dflys.backend.importer.skip.gauges=true'
+  unterdrückt werden.
+  Die .glt-Datei, die neben der .wst-Datei liegt, wird zuerst
+  ausgelesen. Es werden nur *.sta-Datei von Pegeln geladen, die
+  in der .glt-Datei vermerkt sind.
+
+  Wenn "-Dflys.backend.sta.parse.gauge.numbers=true' wird versucht,
+  die offiziellen Pegelnummern aus den Stammdaten zu extrahieren.
+  !!! Dies ist mit Vorsicht zu behandeln, denn die meisten STA-Dateien
+  !!! Enthalten invalide Pegelnummern.
+
+  Die System-Property "flys.backend.main.value.types" kann einen
+  String mit gültigen Typen von Stammdaten enthalten. Vorbelegt
+  ist "QWTD". In der Praxis ist "QWD" eine sinnvolle Belegung.
+
+- 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.
+  Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
+  "../Zus.Längsschnitte" relativ zur gewaesser.wst-Datei betrachtet.
+
+- Fixierungen (*.wst-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.fixations=true'
+  unterdrückt werden.
+  Es werden die *.wst-Dateien aus dem Verzeichnis
+  "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
+
+- Amtliche Linien (*.wst-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.official.lines=true'
+  unterdrückt werden.
+  Es werden die "Amtl_Linien.wst"-Dateien aus dem Verzeichnis
+  "../Basisdaten" und "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
+
+- Profilspuren (*.prf-Dateien)
+  Der Import kann mit '-Dflys.backend.importer.skip.prfs=true'
+  unterdrückt werden.
+  Es werden rekursiv alle *.prf-Dateien aus "../../.." relativ
+  zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
+  mithilfe eines Längen- und eines MD5-Summen-Vergleichs
+  inhaltliche Duplikate ausgeschlossen.
+
+- Hydraulische Kennzahlen (*.hyk)
+  Der Import kann mit '-Dflys.backend.importer.skip.hyks=true'
+  unterdrückt werden.
+  Es werden rekursiv alle *.hyk-Dateien aus "../../.." relativ
+  zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
+  mithilfe eines Längen- und eines MD5-Summen-Vergleichs
+  inhaltliche Duplikate ausgeschlossen.
+
+- Hochwassermarken (*.zus, *.wst)
+  Der Import kann mit '-Dflys.backend.importer.skip.flood.water=true'
+  unterdrückt werden.
+  Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
+  "../HW-Marken" relativ zur gewaesser.wst-Datei betrachtet.
+
+- Hochwasserschutzanlagen (*.zus)
+  Der Import kann mit '-Dflys.backend.importer.skip.flood.protection=true'
+  unterdrückt werden.
+  Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
+  "../HW-Schutzanlagen" relativ zur gewaesser.wst-Datei betrachtet.
+
+  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
+
+Für die Verbindung zur Datenbank ist es nötig, dem Import
+die Verbindungsdaten zu übergeben. Dies geschieht ebenfalls
+über System-Properties:
+
+  -Dflys.backend.user=NUTZER
+   Datenbanknutzer
+
+  -Dflys.backend.password=PASSWORT
+   Datenbankpasswort
+
+  -Dflys.backend.url=URL
+   URL zur Datenbank. Typische wäre im Fall einer Oracle-XE-Edition z.B.:
+   jdbc:oracle:thin:@//RECHNER:PORT/XE
+   mit RECHNER Name des Servers, auf dem die Datenbank läuft
+   und PORT der Port auf dem die Datenbank konkret zu erreichen ist.
+   Weitere Details unter http://www.orafaq.com/wiki/JDBC
+
+ -Dflys.backend.driver=TREIBER
+  mit TREIBER dem Namen des JDBC-Treibers, der es erlaubt
+  das Protokoll der Datenbank zu sprechen. Im Falle
+  einer Oracle XE wäre dies z.B.:
+  oracle.jdbc.OracleDriver
+
+ -Dflys.backend.dialect=DIALECT
+  mit DIALECT dem Hibernate-Dialekt, den die Datenbank versteht.
+  Im Falle eine Oracle-XE wäre dies z.B.:
+  org.hibernate.dialect.OracleDialect
+
+
+Hinweise zum Betrieb:
+---------------------
+
+    Der Speicherverbrauch des Importers ist sehr hoch. Es ist empfehlenswert,
+    der JVM mindestens 8GiB Hauptspeicher zuzuordnen: '-Xmx8192m'
+    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.
+
+Anhang 'Klassifikation von Streckenfavoriten'
+---------------------------------------------
+Streckenfavoriten werden aus KM-Dateien importiert. Um die einzelnen Einträge
+eine Kategorie (Brücken, Pegel, etc.) zuzuordnen, kann eine XML angegeben werden,
+in der Regeln für diese Klassifikation definiert werden. Schematisch gliedert
+sich diese Datei in die zwei Bereiche 'types' und 'patterns':
+
+<annotation>
+    <types> ...  </types>
+    <patterns> ...  </patterns>
+</annotation>
+
+In der Sektion 'types' werden die Kategorien vereinbart, in die
+klassifiziert werden sollen. Die geschieht mit einzelnen
+
+  <type name="Pegel"/>
+  <type name="Brücke"/>
+  ...
+  <type name="Sonstige" default="true"/>
+
+Das Attribut 'default' kann einmal vergeben werden und
+besagt, dass diese Kategorie gewählt werden soll, wenn
+keine andere Kategorie zugeordnet werden kann.
+
+In der Sektion 'patterns' werden dann die Regel
+definiert, die einzelne Einträge den definierten Kategorien
+zuordnet. Hierfür können zwei Arten von Definitionen
+angegeben werden:
+
+  <file pattern="^Brücken$" type="Brücke"/>
+
+oder
+
+  <line pattern="^Brücke[:\s].*$" type="Brücke"/>
+
+Die erste Variante bestimmt die Kategorie, die pro KM-Datei
+gelten soll. 'pattern' ist hierbei ein regulärer Ausdruck,
+der auf den Dateinamen angewandt wird. Passt der Name
+der Datei auf den regulären Ausdruck, wird 'type' als
+Vorgabe angenommen. Treffen mehrere <file>-Regeln zu,
+wird der erste Treffer angewandt. Findet keine der <file>-Regeln
+Anwendung, wird die Kategorie ausgewählt, die in der <types>-Section
+das Attribut 'default' gesetzt hat.
+
+Die zweite Regel-Variante <line> wird auf jeden Eintrag
+innerhalb einer KM-Datei auf den Bezeichner der Streckenfavoriten
+angewandt. Als Muster dient auch hier ein regulärer Ausdruck,
+der über das Attribut 'pattern' definiert wird. Die Kategorie
+wird in Trefferfall über das Attribut 'type' bestimmt. Treffen
+mehrere Regeln zu, wird die Kategorie gewählt, die zum ersten
+Treffer gehört. Trifft keine Regel zu wird der Eintrag der
+Kategorie zugeteilt, die für die beinhaltende Datei als Vorgabe
+gilt.
+
+Anhang 'Fehler und Warnungen':
+=============================
+
+Fehler:
+-------
+
+- 'error while parsing gew'
+  Die GEW-Datei ist fehlerhaft oder konnte nicht geöffnet werden.
+
+- 'File 'XYZ' is broken!'
+  Die Datei XYZ ist inkonsistent und führt zu Fehlern.
+
+- 'Error while parsing file for morph. width.'
+  Beim Lesen der morphologischen Breite trat ein Fehler auf.
+
+- 'Error while storing flow velocity model.'
+  Beim Schreiben eines Fliessgeschwindigkeitsmodells trat ein Fehler auf.
+
+- 'Error while storing flow velocity measurement.'
+  Beim Schreiben einer Fliessgeschwindigkeitsmessung trat ein Fehler auf. 
+
+- 'Error while storing sediment yield.'
+  Beim Schreiben einer Sedimentablagerung trat ein Fehler auf.
+
+- 'Error while storing waterlevel diff.'
+  Beim Schreiben einer Wassspiegeldifferenz trat ein Fehler auf.
+
+- 'Error while storing sq relation.'
+  Beim Schreiben einer S(Q) Beziehung trat ein Fehler auf.
+
+- 'Error reading PRF file.'
+  Beim Lesen einer PRF-Datei trat ein Fehler auf.
+
+- 'Error closing PRF file.'
+  Beim Schliessen einer PRF-Datei trat ein Fehler auf.
+
+- 'HYK 1: not enough elements in line #'
+- 'HYK 2: not enough elements in line #'
+- 'HYK 5: not enough elements in line #'
+- 'HYK 6: not enough elements in line #'
+  Eine Zeile in einer HYK-Datei hat nicht genügend Elemente.
+
+- 'HYK: parsing num zones, bottom or top height failed in line #'
+- 'HYK: HYK: number of flow zones mismatches in line #'
+  Die Anzahl der Zonen oder Daten über die Zonen sind nicht korrekt.
+
+- 'HYK: cannot parse number in line #'
+  Eine Zahl wurde erwartet.
+
+- 'HYK: Error reading file.'
+  Beim Lesen einer HYK-Datei trat ein Fehler auf.
+
+- 'HYK: Error closing file.'
+  Beim Schliessen einer HYK-Datei trat ein Fehler auf.
+
+Warnungen:
+----------
+
+- 'annotation type file 'XYZ' is not readable.'
+  Die Datein XYZ kann nicht gelesen werden.
+
+- 'cannot parse annotation types file.'
+  Während der Verarbeitung der Annotationsdatei ist Fehler aufgetreten.
+
+- 'Cannot read directory.'
+  verzeichnis konnte nicht gelesen werden.
+
+- 'no official lines wst file found'
+  Keine Datei mit amtlichen Linien gefunden.
+
+- 'cannot read fixations wst file directory'
+  Das Verzeichnis mit den Fixierungen kann nicht gelesen werden.
+
+- 'cannot read extra longitudinal wst file directory'
+  Das Verzeichnis mit den zusätzlichen Längsschnitten kann nicht gelesen werden.
+
+- 'cannot read gauges from 'XYZ''
+  Die Pegelgültigkeiten können nicht gelesen werden.
+
+- 'HYK file 'XYZ' seems to be a duplicate.'
+  Die HYK-Datei wurde unter anderem Namen aber gleichen Inhalts
+  bereits gefunden.
+
+- 'PRF file 'XYZ' seems to be a duplicate.'
+  Die PRF-Datei wurde unter anderem Namen aber gleichen Inhalts
+  bereits gefunden.
+
+- 'Skip invalid SedimentYield: time interval or unit null!'
+  Eine Sedimentablagerung ist ungültig und wurde ausgelassen.
+
+- 'skip flow velocity model: No discharge zone specified.'
+  Da kein Abflussbereich angegeben wurde, wurde das Fliessgeschwindigkeitsmodell ausgelassen.
+
+- 'skip invalid waterlevel - no unit set!'
+  Ein einheitenloser Wasserstand wurde ausgelassen.
+
+- 'Cannot parse time range.'
+  Das Zeitformat wurde nicht erkannt.
+
+- 'skip invalid data line #'
+  Ungültige Datenzeile wurde ausgelassen.
+
+- 'Error while parsing sq relation row #'
+  Eine Zeile in der S(Q)-Beziehung ist ungültig.
+
+- 'GLT: no gauge found in line #'
+  In der GLT-Datei wurde ein Pegel erwartet, aber nicht gefunden.
+
+- 'GLT: line # has not enough columns.'
+  Eine Zeile in der Pegelgültigkeitsdatei hat nicht genug spalten.
+
+- 'Error while parsing flow velocity values.'
+- 'skip invalid data line: #'
+  Invalide Datenzeile in einer Datei mit einer Fliessgeschwindigkeitsmessung.
+
+- 'skip invalid waterlevel line: #'
+- 'Error while parsing value: #'
+- 'Error while parsing station: #'
+  Invalide Datenzeile in einer Datei mit Wasserstandsdifferenzen.
+
+- 'skip invalid MainValue part: #'
+- 'skip invalid gauge part: #'
+- 'Error while parsing Q value: <Q>'
+- 'skip invalid data line: #'
+- 'Error while parsing flow velocity values.'
+  Invalide Datenzeile in einer Datei Fliessgeschwindigkeitsmodellen.
+
+- 'Error while parsing number from data row: #'
+  TODO INGO
+
+- 'Unknown meta line: #'
+- 'Error while parsing numbers in: #'
+- 'skip invalid data line: #'
+- 'Error while parsing numbers in #'
+  Invalide Datenzeile in einer Datei mit Sedimentdichten.
+
+- 'STA file is empty'
+- 'STA file has not enough lines'
+- 'STA file is too short'
+  Stammdatendatei ist leer oder hat zu wenige Zeilen.
+
+- 'First line in STA file is too short.'
+  Die erste Zeile der Stammdaten ist zu kurz.
+
+- 'STA: second line is too short'
+  Die zweite Zeile ist zu kurz.
+
+- 'STA: parsing of the datum of the gauge failed'
+
+- 'STA: 'XYZ' is not a valid long number.'
+  Die Pegelnummer ist invalide.
+
+- 'STA: Not enough columns for aeo and datum.
+  AEO und Pegelnullpunkt können nicht ermittelt werden.
+
+- 'STA: cannot parse aeo or datum.'
+  AEO oder Pegelnullpunkt sind invalide.
+
+- 'STA: value not parseable in line #'
+  Wert ist nicht als Zahl zu interpretieren.
+  
+- 'PRF: cannot open file <FILE>'
+  Die PRF kann nicht geöffnet werden.
+
+- PRF: file is empty
+- PRF: First line does not look like a PRF data pattern.
+- PRF: premature EOF. Expected integer in line 2
+- PRF: Expected <num> in line 2
+- PRF: invalid integer in line 2
+- PRF: premature EOF. Expected pattern for km extraction
+- PRF: line 4 does not look like a PRF km extraction pattern.
+- PRF: premature EOF. Expected skip row count.
+- PRF: line 5 is not an positive integer.
+- PRF: cannot extract km in line #
+  Das PRF-Format ist komplex. Hier sollten weitere Information
+  zur genaueren Analyse herangezogen werden.
+
+- 'cannot access WST file <FILE>'
+  Die WST-Datei konnte nicht gefunden werden.
+
+- 'Found an invalid row in the AT file.'
+  Eine Zeile in einer AT-Datei ist nicht korrekt.
+
+- 'AT: invalid number <XYZ>'
+  Eine Zahl wurde erwartet aber nicht gefunden.
+
+- 'Try to add Q range without waterlevel!'
+  Q-Bereich ohne Wasserstand gefunden.
+
+- 'Error while parsing Q range: #'
+  Invalider Q-Bereich
+
+- 'skip invalid waterlevel line: #'
+  Ungültige Wasserstandslinie
+
+- 'Error while parsing number values: #'
+  Ungültige Zahlenwerte.
+
+- 'ANN: not enough columns in line #'
+  Nicht genug Zeichenspalten in KM-Datei
+
+- 'ANN: invalid number in line #'
+  Ungültige Zahl.
+
+- 'ANN: cannot parse 'Unterkante' in line #'
+  Die Unterkante in einer KM-Datei konnte nicht gelesen werden.
+
+- 'ANN: cannot parse 'Unterkante' or 'Oberkante' in line #'
+  Unter- oder Oberkannte liegen in einem falschen Format vor.
+
+- 'ANN: duplicated annotation 'XYZ' in line #'
+  Ein Duplikat eines Streckenfavoriten wurde gefunden.
+
+- 'ANN: 'XYZ' is not a directory.'
+  Unterverzeichnis konnte nicht geöffnet werden.
+
+- 'ANN: cannot list directory 'XYZ''
+  Unterverzeichnis konnte nicht durchsucht werden.
+
+- 'BHP: Meta line did not match any known type: #'
+  Unbekannter Typ.
+
+- 'BHP: Error while parsing timeinterval!'
+  Ungültiges Zeitinterval.
+
+- 'BHP: Error while parsing year!'
+  Ungültige Jahresangabe.
+
+- 'BHP: Error while parsing sounding width!'
+  Unbekannte Peilungsbreite.
+
+- 'BHP: Error while parsing range!'
+  Bereichsangabe fehlerhaft.
+
+- 'MWP: Unknown meta line: #'
+  Meta-Informationen ungültig.
+
+- 'MWP: skip invalid data line: #'
+  Ungültige Datenzeile wurde übersprungen.
+
+- 'MWP: Error while parsing numbers in #'
+  Falsche Zahlenformat.
+
+- 'ANNCLASS: rule has no name'
+  Klassifizierungsregel für Streckenfavoriten hat keinen Namen.
+
+- 'ANNCLASS: pattern has no 'pattern' attribute.'
+  Klassifizierungsmuster für Streckenfavoriten hat kein Muster.
+
+- 'ANNCLASS: pattern has unknown type 'XYZ''
+  Klassifizierungsmuster für Streckenfavoriten konnte keinem Typ zugeordnet werden.
+
+- 'ANNCLASS: pattern 'XYZ' is invalid.'
+  Klassifizierungsmuster für Streckenfavoriten ist ungültig.
+
+- 'BSP: Error while parsing data row.'
+  Ungültige Datenzeile.
+
+- 'SYP: Unknown meta line: #'
+  Ungültige Metadatenzeile.
+
+- 'SYP: skip invalid data line #'
+  Ungültige Datenzeile wurde übersprungen.
+
+- 'SYP: Error while parsing numbers in #'
+  Ungültige Zahlenformatierung.
+
+- 'SYP: Unknown time interval string <XYZ>'
+  Falsches Datumformat.
+
+- 'SYP: Error while parsing years <XYZ>'
+  Falsches Jahreszahlformat.
+ 
+- 'SYP: Error while parsing ranges of <XYZ>'
+  Bereichsangaben fehlerhaft.
+
+- 'SYP: Unknown grain fraction <XYZ>'
+  Unbekannte Kornfraktion.
+
+- 'WST: invalid number.'
+  Ungültige Zahl.
+
+- 'WST: km <km> (<Zeile>) found more than once. -> ignored.'
+  Ein Kilometer ist doppelt in einer WST-Datei enthalten.
+
+- 'HYK: zone coordinates swapped in line #'
+  Fliesszonenkordinaten wurden in umgekehrter Reihenfolge angeben.
+
+- 'BHS: Skip invalid file 'XYZ''
+  Die Inhalte der Datei sind ungültig.
+
+- 'ISQ: Unable to store sq relation value.'
+  S(Q) Beziehung konnte nicht gespeichert werden.
+
+- 'ISQ: Cannot determine sq relation without time interval.'
+  Einer S(Q)-Beziehung ist keine zeitliche Gültigkeit zugeordnet.
+
+- 'IWD: skip invalid waterlevel difference - no unit set!'
+  Wasserstandsdifferenz hat keine Einheit.
+
+- 'BHE: Skip file - invalid current elevation model.'
+  Höhenmodell ungültig.
+
+- 'BHE: Skip file - invalid time range.'
+  Zeitbereich ungültig.
+
+- 'BHE: Skip file - invalid km range.'
+  Kilometerbereich ungültig.
+