--- a/backend/doc/README.txt	Fri Aug 09 21:35:53 2013 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,528 +0,0 @@
-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.
-