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.