--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/etl/README.txt	Thu Apr 25 15:23:37 2013 +0200
@@ -0,0 +1,322 @@
+FLYS-AFT:
+"""""""""
+
+Der FLYS-AFT-ETL-Prozessor aktualisiert eine FLYS-Datenbank mithilfe
+eines DIPS-XML-Exports und einer AFT-Datenbank in bezug auf Pegel und
+Abflusstafeln.
+
+Vorbedingungen:
+---------------
+
+    * Es existiert ein DIPS-XML-Export unter einen erreichbaren Pfad
+      im Dateisystem.
+
+    * Es existiert eine AFT-Datenbank mit bekannten Credentials.
+
+    * Es existiert eine FLYS-Datenbank mit bekannten Credentials.
+
+Bau:
+----
+   * Maven2 sollte installiert und im Pfad liegen.
+     ( http://maven.apache.org/docs/2.2.1/release-notes.html )
+
+     $ mvn --version
+     Sollte Versionsinformationen ausgeben.
+
+   * Für die Nutzung der Oracle JDBC-Bindings muss das Oracle-Treiber-Jar
+     in das lokale Maven-Repository installiert werden:
+
+     $ mvn install:install-file -DgroupId=ojdbc5.jar -DartifactId=ojdbc5 \
+       -Dversion=0 -Dpackaging=jar -Dfile=ojdbc.jar -DgeneratePom=true
+
+   * Für den eigentlichen Oracle-kompatiblen Bau kann dann folgendes
+     aufgerufen werden:
+
+     $ mvn -f pom-oracle.xml clean compile assembly:single
+
+     $ cp target/de.intevation.aft-1.0-SNAPSHOT-jar-with-dependencies.jar \
+       bin/etl.jar
+
+   * Folgendes führt das fertige Programm dann aus:
+
+     $ bin/run.sh
+
+Konfiguration:
+--------------
+
+Zur Konfiguration wird eine Konfiguration-Datei benötigt. Diese wird 
+standardmässig  im aktuellen Arbeitsverzeichnis uter dem Name 'config.xml'
+gesucht. Der Pfad zu dieser Datei kann allerdings auch mit der
+System-Property config.file gesetzt werden.
+
+Dies geschieht über den Kommandozeilenparameter "-Dconfig.file=/pfad/zur/config.xml"
+im Start-Skript bin/run.sh
+
+Die Konfigurationsdatei hat folgende Struktur:
+
+ 1 <?xml version="1.0" encoding="UTF-8"?>
+ 2 <sync>
+ 3   <!-- If modified send messages -->
+ 4   <notifications>
+ 5     <notifaction url="http://example.com">
+ 6       <caches>
+ 7         <cache name="my-cache"/>
+ 8       </caches>
+ 9     </notifaction>
+10   </notifications>
+11   <!-- The path to the DiPs file -->
+12   <dips>
+13     <file>/the/path/to/the/dips/file</file>
+14     <repair>/the/path/to/the/xslt/to/repair/dips</repair>
+15   </dips>
+16   <!-- The FLYS side -->
+17   <side name="flys">
+18     <db>
+19       <driver>oracle.jdbc.OracleDriver</driver>
+20       <user>flys</user>
+21       <password>flys</password>
+22       <url>jdbc:oracle:thin:@//localhost:1521/XE</url>
+23     </db>
+24   </side>
+25   <!-- The AFT side -->
+26   <side name="aft">
+27     <db>
+28       <driver>oracle.jdbc.OracleDriver</driver>
+29       <user>aft</user>
+30       <password>aft</password>
+31       <url>jdbc:oracle:thin:@//localhost:1521/XE</url>
+32       <execute-login>
+33         <statement>ALTER SESSION SET CURRENT_SCHEMA=AFT</statement>
+34       </execute-login>
+35     </db>
+36   </side>
+37 </sync>
+
+Sie besteht aus vier Bereichen:
+
+  * DIPS:
+    Zeile 13: Pfad zur XML-Datei mit dem DIPS-Export
+    Zeile 14: Pfad zur Reparatur-XSL-Transformation (s.u.).
+               Dieser ist optional.
+  * FLYS:
+    Zeile 19: JDBC-Treiber für den Zugriff auf die FLYS-Datenbank
+    Zeile 20: DB-Nutzername
+    Zeile 21: Connection-URL zur FLYS-Datenbank
+
+  * AFT:
+    Zeile 28: JDBC-Treiber für den Zugriff auf die AFT-Datenbank
+    Zeile 29: DB-Nutzername
+    Zeile 30: Connection-URL zur AFT-Datenbank
+
+  * Schemata:
+    Zeile 32-34: Schema in welches die Daten geschrieben werden sollen.
+
+  * Benachrichtigungen:
+    Zeile    5: URL des Web-Service, der benachrichtigt werden soll.
+    Zeile 6-18: Die Nachricht, die an den Web-Service verschickt werden soll.
+
+Funktionsweise:
+---------------
+
+    Als erstes wird die DIPS-Datei geladen. Ist angegeben, dass
+    eine Reparatur-XSL-Transformation auf diese angewendet werden
+    soll, wird diese ebenfalls gelanden und auf das DIPS-Dokument
+    angewandt. 
+
+    !!! Hinweis: Unter doc/repair.xsl findet sich eine Beispiel-Transformation,
+    !!! Die mithilfe von doc/pegelstationen.xml für die Flüsse
+    !!! Saar, Mosel und Elbe die Pegelnummern der FLYS-Pegel
+    !!! auf die Pegelnummernvon Pegel-Online anpasst.
+
+    Die so vorbehandelten DIPS-Daten werden mit der AFT-Datenbank
+    verbunden. Verbindungspunkt ist hierbei die Pegelnummer, die
+    in beiden Systemen gleich sein muss.
+
+    Wurde für einzelne Pegel die Verbindung zwischen AFT und DIPS
+    erfolgreich hergestellt, wird versucht mit der entsprechenden
+    Pegelnummer auch eine Verbindung zu FLYS hergestellt.
+
+    Werden Pegel in AFT und DIPS gefunden, die sich nicht in FLYS befinden,
+    werden diese in FLYS angelegt und mit den Abflusstafeln aus AFT
+    gefüllt.
+
+    Werden Pegel in AFT, DIPS und FLYS gefunden, werde die Abflusstafeln
+    in FLYS mithilfe von AFT aktualisiert. Die Verbindung der Abflusstafeln
+    wird über deren Bezeichner hergestellt:
+
+       AFT:  "ABFLUSSTAFEL.ABFLUSSTAFEL_BEZ"
+       FLYS: "discharge_tables.decsription"
+
+    Für alle vorhandenen Paare von AFT/FLYS-Abflusstafeln werden
+    die W/Q-Werte abgeglichen und FLYS entsprechend aktualisiert.
+    Abflusstafeln, die in FLYS noch nicht vorhanden sind, werden
+    in FLYS übernommen.
+
+    Wenn es nach dem Abgleich der AFT- und FLYS-DB eine Veränderung
+    in FLYS gegeben hat, können an konfigurierbare Web-Dienste
+    Nachrichten verschickt werden, dass sich Daten geändert haben.
+    Die FLYS-Applikation selbst bestitzt einen Dienst, der aufgerufen
+    werden kann, um dessen internen Caches zu invalidieren.
+    Dies vermeidet Dateninkonsistenzen.
+
+Fehlermeldungen:
+================
+
+Wärend die Synchronisationsprozesses können verschiedene Fehler
+auftreten.
+
+Allgemein:
+----------
+
+SYNC: syncing failed.
+
+    Wärend der Synchronisation ist ein Fehler aufgetreten. Details
+    finden sich in der Regel oberhalb dieser Fehlermeldung.
+
+REPAIR: Cannot open DIPS repair XSLT file.
+    
+    Die zur Reparatur angegebene XSL-Transformation konnte nicht geladen
+    werden.
+
+REPAIR: Fixing DIPS failed.
+
+    Die Anwendung der XSL-Transformation zur Reparatur der DIPS-Daten
+    ist fehlgeschlagen. Datails hierzu sollten sich oberhalb dieser
+    Fehlermeldung zu finden sein.
+
+Benachrichtigung:
+-----------------
+
+NOTIFY: Invalid URL '<URL>'. Ignored.
+
+    Die zur Benachrichtigung angegebene URL ist nicht valide und
+    wird daher ignoriert.
+
+NOTIFY: '<URL>' is not an HTTP(S) connection.
+
+    Die zur Benachrichtigung angegebene URL öffnet keine 
+    HTTP- bzw. HTTPS-Verbindung.
+
+NOTIFY: Sending message to '<URL>' failed.
+
+    Der Versand der Benachrichtigung an die URL ist fehlgeschlagen.
+
+DIPS:
+-----
+
+DIPS: MESSSTELLE '<NAME>' not found in DIPS. Gauge number used for lookup: <NUMMER>
+
+    Es wurde vergeblich versucht, mithilfe einer AFT-Pegelnummer in DIPS
+    ein entsprechendes Gegenstück zu finden.
+
+DIPS: MESSSTELLE '<NAME>' is assigned to river '<FLUSS1>'. Needs to be on '<FLUSS2>'.
+
+    Aus Sicht von AFT wird Messstelle <NAME> an <FLUSS2> erwartet.
+    DIPS ordnet sie aber <FLUSS1> zu.
+
+DIPS: Gauge '<PEGEL>' has no datum. Ignored.
+
+    Der DIPS-Pegel <PEGEL> hat keinen PNP und kann deshalb nicht
+    importiert werden.
+
+DIPS: Setting AEO of gauge '<NAME>' to zero.
+
+    Der AEO-Wert ist bei dem DIPS-Pegel <NAME> nicht gesetzt und
+    wird mit Null angenommen.
+
+DIPS: Setting station of gauge '<NAME>' to zero.
+
+    Der DIPS-Pegel '<NAME>' hat keine zugeordnete Stationierung und
+    es wird angenommen, dass dieser an km 0 liegt.
+
+DIPS: Station of gauge '<NAME>' is zero.
+
+    Im Regelfall ist ein Stationierung an km 0 ein Datenfehler.
+
+DIPS: Cannot find '<DATEINAME>'.
+
+    Der Pfad zum XML-Dokument mit den DIPS-Daten konnte nicht gefunden
+    werden.
+
+DIPS: Cannot load DIPS document.
+    
+    Das XML-Dokument mit den DIPS-Daten konnte nicht geladen werden.
+
+DIPS: '<NAME2>' collides with '<NAME1>' on gauge number <NUMMER>.
+
+    In DIPS gibt es zwei Pegel mit NAME1 und NAME2, die dieselbe Pegelnummer
+    haben.
+
+DIPS: Gauge '<NAME>' has invalid gauge number '<NUMBER>'.
+
+    Der DIPS-Pegel Name hat eine Pegelnummer <NUMMER>, die sich nicht
+    in einen 64bit-Integer erwandeln lässt.
+
+AFT:
+----
+
+AFT: ABFLUSSTAFEL_NR = <NUMMER>: <GUELTIG_VON> > <GUELTIG_BIS>. -> swap
+
+    Eine AFT-Abflusstafel hat vertauschte GUELTIG_VON- und GUELTIG_BIS-Werte.
+    Diese werden implizit in die zeitlich richtige Reihenfolge gebracht.
+
+FLYS/AFT: Value duplication w=<W> q=<Q>. -> ignore.
+
+    Beim Laden einer Abflusstafel wurden ein W/Q-Duplikat entdeckt
+    und ignoriert.
+
+AFT: Invalid MESSSTELLE_NR for MESSSTELLE '<NAME>':
+
+    Die Messtellen-Nummer für die Messtelle <NAME> ist ungültig.
+    Erwartet wird ein String, der sich in einen 64bit-Integer umwandeln lässt.
+
+AFT: Found discharge table '<BESCHREIBUNG>' with same description. -> ignore.
+
+    In AFT wurde eine Abflusstafel gefunden, die die gleiche Bezeichnung
+    trägt wie eine andere, die demselben Pegel zugeordnet ist. Somit
+    ist keine eindeutige Zuordnung möglich.
+
+FLYS:
+-----
+
+FLYS: Found discharge table '<BESCHREIBUNG>' with same description. -> ignore
+
+    In FLYS wurde eine Abflusstafel gefunden, die die gleiche Bezeichnung
+    trägt wie eine andere, die demselben Pegel zugeordnet ist. Somit
+    ist keine eindeutige Zuordnung möglich.
+
+FLYS: Gauge '<PEGEL>' has no official number. Ignored.
+
+    Der Pegel <PEGEL> in FYLS hat keinen Pegelnummer und wird deshalb
+    nicht in Betracht gezogen.
+
+FLYS: Gauge '<PEGEL>' number is not found in AFT/DIPS.
+
+    Der Pegel <PEGEL> hat eine Pegelnummer, die aber nicht in AFT/DIPS
+    zu finden ist.
+
+FLYS: discharge table <ID> has no description. Ignored.
+
+    Die Abflusstafel in FLYS hat keine Beschreibung. Diese wird
+    allerdings zum Abgleich mit DIPS/AFT benötigt.
+
+FLYS: Found discharge table '<BESCHREIBUNG>' with same description. -> ignore
+
+    In FLYS wurde eine Abflusstafel gefunden, die die gleiche Bezeichnung
+    trägt wie eine andere, die demselben Pegel zugeordnet ist. Somit
+    ist keine eindeutige Zuordnung möglich.
+
+FLYS: Gauge '<PEGEL>' has no official number. Ignored.
+
+    Der Pegel <PEGEL> in FYLS hat keinen Pegelnummer und wird deshalb
+    nicht in Betracht gezogen.
+
+FLYS: Gauge '<PEGEL>' number is not found in AFT/DIPS.
+
+    Der Pegel <PEGEL> hat eine Pegelnummer, die aber nicht in AFT/DIPS
+    zu finden ist.
+
+FLYS: discharge table <ID> has no description. Ignored.
+
+    Die Abflusstafel in FLYS hat keine Beschreibung. Diese wird
+    allerdings zum Abgleich mit DIPS/AFT benötigt.