comparison backend/doc/README.txt @ 5838:5aa05a7a34b7

Rename modules to more fitting names.
author Sascha L. Teichmann <teichmann@intevation.de>
date Thu, 25 Apr 2013 15:23:37 +0200
parents flys-backend/doc/README.txt@d1b50434b259
children
comparison
equal deleted inserted replaced
5837:d9901a08d0a6 5838:5aa05a7a34b7
1 FLYS3-Importer
2
3 Der FLYS3-Importer dient dazu, hydrologische und morphologische
4 Gewässerdaten aus dem Dateisystem in die FLYS3-Datenbank zu importieren.
5 Das Werkzeug orientiert sich hierbei an der Dateihierachie,
6 so wie sie auch von Desktop-FLYS ausgelesen wird.
7
8 Als Startargument bekommt der Importer den Pfad zu einer
9 GEW-Datei übergeben.
10
11 Wichtig für den Importer sind in dieser Datei
12 die Zeilen, die mit "WSTDatei:" beginnen. In ihnen wird der
13 Pfad zu der zentralen WST-Datei des jeweiligen Gewässers angegeben.
14 Alle anderen importierten Dateien werden in ihrer Lage relativ zur
15 Lage dieser Datei betrachtet.
16
17 Das Verhalten des Importes kann mit sogenannten
18 System-Properties gesteuert werden. Diese werden im
19 Allgemeinen in der Form -Dkey=value angegeben.
20
21 Will man z.B. mit dem Importer nur einen simulierten Import
22 durchführen (also nicht in die Datenbank geschrieben werden),
23 dann kann dies über die Angabe von
24 '-Dflys.backend.importer.dry.run=true' erfolgen.
25
26 !!! Der Import geht wie Desktop-FLYS davon aus, dass die Dateien
27 !!! Latin-1 encodiert vorliegen.
28
29 Für den Importer stellt jeweils der Import eines Gewässers eine
30 transaktionale Einheit dar. Wird der Import während eines Gewässers
31 abgebrochen, werden alle Änderungen bzgl. dieses Gewässers zurück gerollt.
32
33 Importierte Daten:
34
35 Der Importer importiert folgende Datentypen:
36
37 - Streckenfavoriten (*.km-Dateien)
38 Der Import kann mit '-Dflys.backend.importer.skip.annotations=true'
39 unterdrückt werden.
40
41 Zur Klassifikation von Streckenfavoriten kann mit
42 -Dflys.backend.importer.annotation.types=DATEI
43 der Pfad zu einer XML-Datei angegeben werden, in der über
44 Regeln festgelegt wird, wie diese geschehen soll.
45 Details hierzu im Anhang 'Klassifikation von Streckenfavoriten'.
46
47 - Pegel, Stammdaten (*.glt, *.sta-Dateien):
48 Der Import kann mit '-Dflys.backend.importer.skip.gauges=true'
49 unterdrückt werden.
50 Die .glt-Datei, die neben der .wst-Datei liegt, wird zuerst
51 ausgelesen. Es werden nur *.sta-Datei von Pegeln geladen, die
52 in der .glt-Datei vermerkt sind.
53
54 Wenn "-Dflys.backend.sta.parse.gauge.numbers=true' wird versucht,
55 die offiziellen Pegelnummern aus den Stammdaten zu extrahieren.
56 !!! Dies ist mit Vorsicht zu behandeln, denn die meisten STA-Dateien
57 !!! Enthalten invalide Pegelnummern.
58
59 Die System-Property "flys.backend.main.value.types" kann einen
60 String mit gültigen Typen von Stammdaten enthalten. Vorbelegt
61 ist "QWTD". In der Praxis ist "QWD" eine sinnvolle Belegung.
62
63 - Basis-Wasserstände (gewaesser.wst-Dateien):
64 Der Import kann mit '-Dflys.backend.importer.skip.wst=true'
65 unterdrückt werden.
66
67 - Zusätzliche Längsschnitte (*.zus, *.wst-Dateien)
68 Der Import kann mit '-Dflys.backend.importer.skip.extra.wsts=true'
69 unterdrückt werden.
70 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
71 "../Zus.Längsschnitte" relativ zur gewaesser.wst-Datei betrachtet.
72
73 - Fixierungen (*.wst-Dateien)
74 Der Import kann mit '-Dflys.backend.importer.skip.fixations=true'
75 unterdrückt werden.
76 Es werden die *.wst-Dateien aus dem Verzeichnis
77 "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
78
79 - Amtliche Linien (*.wst-Dateien)
80 Der Import kann mit '-Dflys.backend.importer.skip.official.lines=true'
81 unterdrückt werden.
82 Es werden die "Amtl_Linien.wst"-Dateien aus dem Verzeichnis
83 "../Basisdaten" und "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
84
85 - Profilspuren (*.prf-Dateien)
86 Der Import kann mit '-Dflys.backend.importer.skip.prfs=true'
87 unterdrückt werden.
88 Es werden rekursiv alle *.prf-Dateien aus "../../.." relativ
89 zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
90 mithilfe eines Längen- und eines MD5-Summen-Vergleichs
91 inhaltliche Duplikate ausgeschlossen.
92
93 - Hydraulische Kennzahlen (*.hyk)
94 Der Import kann mit '-Dflys.backend.importer.skip.hyks=true'
95 unterdrückt werden.
96 Es werden rekursiv alle *.hyk-Dateien aus "../../.." relativ
97 zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
98 mithilfe eines Längen- und eines MD5-Summen-Vergleichs
99 inhaltliche Duplikate ausgeschlossen.
100
101 - Hochwassermarken (*.zus, *.wst)
102 Der Import kann mit '-Dflys.backend.importer.skip.flood.water=true'
103 unterdrückt werden.
104 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
105 "../HW-Marken" relativ zur gewaesser.wst-Datei betrachtet.
106
107 - Hochwasserschutzanlagen (*.zus)
108 Der Import kann mit '-Dflys.backend.importer.skip.flood.protection=true'
109 unterdrückt werden.
110 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
111 "../HW-Schutzanlagen" relativ zur gewaesser.wst-Datei betrachtet.
112
113 TODO INGO:
114
115 flys.backend.importer.skip.bed.height.single
116 flys.backend.importer.skip.bed.height.epoch
117 flys.backend.importer.skip.sediment.density
118 flys.backend.importer.skip.morphological.width
119 flys.backend.importer.skip.flow.velocity
120 flys.backend.importer.skip.sediment.yield
121 flys.backend.importer.skip.waterlevels
122 flys.backend.importer.skip.waterlevel.differences
123 flys.backend.importer.skip.sq.relation
124
125 Für die Verbindung zur Datenbank ist es nötig, dem Import
126 die Verbindungsdaten zu übergeben. Dies geschieht ebenfalls
127 über System-Properties:
128
129 -Dflys.backend.user=NUTZER
130 Datenbanknutzer
131
132 -Dflys.backend.password=PASSWORT
133 Datenbankpasswort
134
135 -Dflys.backend.url=URL
136 URL zur Datenbank. Typische wäre im Fall einer Oracle-XE-Edition z.B.:
137 jdbc:oracle:thin:@//RECHNER:PORT/XE
138 mit RECHNER Name des Servers, auf dem die Datenbank läuft
139 und PORT der Port auf dem die Datenbank konkret zu erreichen ist.
140 Weitere Details unter http://www.orafaq.com/wiki/JDBC
141
142 -Dflys.backend.driver=TREIBER
143 mit TREIBER dem Namen des JDBC-Treibers, der es erlaubt
144 das Protokoll der Datenbank zu sprechen. Im Falle
145 einer Oracle XE wäre dies z.B.:
146 oracle.jdbc.OracleDriver
147
148 -Dflys.backend.dialect=DIALECT
149 mit DIALECT dem Hibernate-Dialekt, den die Datenbank versteht.
150 Im Falle eine Oracle-XE wäre dies z.B.:
151 org.hibernate.dialect.OracleDialect
152
153
154 Hinweise zum Betrieb:
155 ---------------------
156
157 Der Speicherverbrauch des Importers ist sehr hoch. Es ist empfehlenswert,
158 der JVM mindestens 8GiB Hauptspeicher zuzuordnen: '-Xmx8192m'
159 Besonders speicherintensiv ist der Import der HYKs und der PRFs.
160 Hier ist es unter Umständen empfehlenswert, diese in zwei oder drei
161 Schritten zu importieren. Zuerst die sonstigen hydrologischen Daten
162 (hierbei mit flys.backend.importer.skip.hyks=true und flys.backend.importer.skip.prfs
163 den Import der HYKs und PRFs verhindern). Dann die HYKs (mit flys.backend.importer.skip.*
164 der anderen Daten) und im finalen Schritt dann die PRFs.
165
166 Anhang 'Klassifikation von Streckenfavoriten'
167 ---------------------------------------------
168 Streckenfavoriten werden aus KM-Dateien importiert. Um die einzelnen Einträge
169 eine Kategorie (Brücken, Pegel, etc.) zuzuordnen, kann eine XML angegeben werden,
170 in der Regeln für diese Klassifikation definiert werden. Schematisch gliedert
171 sich diese Datei in die zwei Bereiche 'types' und 'patterns':
172
173 <annotation>
174 <types> ... </types>
175 <patterns> ... </patterns>
176 </annotation>
177
178 In der Sektion 'types' werden die Kategorien vereinbart, in die
179 klassifiziert werden sollen. Die geschieht mit einzelnen
180
181 <type name="Pegel"/>
182 <type name="Brücke"/>
183 ...
184 <type name="Sonstige" default="true"/>
185
186 Das Attribut 'default' kann einmal vergeben werden und
187 besagt, dass diese Kategorie gewählt werden soll, wenn
188 keine andere Kategorie zugeordnet werden kann.
189
190 In der Sektion 'patterns' werden dann die Regel
191 definiert, die einzelne Einträge den definierten Kategorien
192 zuordnet. Hierfür können zwei Arten von Definitionen
193 angegeben werden:
194
195 <file pattern="^Brücken$" type="Brücke"/>
196
197 oder
198
199 <line pattern="^Brücke[:\s].*$" type="Brücke"/>
200
201 Die erste Variante bestimmt die Kategorie, die pro KM-Datei
202 gelten soll. 'pattern' ist hierbei ein regulärer Ausdruck,
203 der auf den Dateinamen angewandt wird. Passt der Name
204 der Datei auf den regulären Ausdruck, wird 'type' als
205 Vorgabe angenommen. Treffen mehrere <file>-Regeln zu,
206 wird der erste Treffer angewandt. Findet keine der <file>-Regeln
207 Anwendung, wird die Kategorie ausgewählt, die in der <types>-Section
208 das Attribut 'default' gesetzt hat.
209
210 Die zweite Regel-Variante <line> wird auf jeden Eintrag
211 innerhalb einer KM-Datei auf den Bezeichner der Streckenfavoriten
212 angewandt. Als Muster dient auch hier ein regulärer Ausdruck,
213 der über das Attribut 'pattern' definiert wird. Die Kategorie
214 wird in Trefferfall über das Attribut 'type' bestimmt. Treffen
215 mehrere Regeln zu, wird die Kategorie gewählt, die zum ersten
216 Treffer gehört. Trifft keine Regel zu wird der Eintrag der
217 Kategorie zugeteilt, die für die beinhaltende Datei als Vorgabe
218 gilt.
219
220 Anhang 'Fehler und Warnungen':
221 =============================
222
223 Fehler:
224 -------
225
226 - 'error while parsing gew'
227 Die GEW-Datei ist fehlerhaft oder konnte nicht geöffnet werden.
228
229 - 'File 'XYZ' is broken!'
230 Die Datei XYZ ist inkonsistent und führt zu Fehlern.
231
232 - 'Error while parsing file for morph. width.'
233 Beim Lesen der morphologischen Breite trat ein Fehler auf.
234
235 - 'Error while storing flow velocity model.'
236 Beim Schreiben eines Fliessgeschwindigkeitsmodells trat ein Fehler auf.
237
238 - 'Error while storing flow velocity measurement.'
239 Beim Schreiben einer Fliessgeschwindigkeitsmessung trat ein Fehler auf.
240
241 - 'Error while storing sediment yield.'
242 Beim Schreiben einer Sedimentablagerung trat ein Fehler auf.
243
244 - 'Error while storing waterlevel diff.'
245 Beim Schreiben einer Wassspiegeldifferenz trat ein Fehler auf.
246
247 - 'Error while storing sq relation.'
248 Beim Schreiben einer S(Q) Beziehung trat ein Fehler auf.
249
250 - 'Error reading PRF file.'
251 Beim Lesen einer PRF-Datei trat ein Fehler auf.
252
253 - 'Error closing PRF file.'
254 Beim Schliessen einer PRF-Datei trat ein Fehler auf.
255
256 - 'HYK 1: not enough elements in line #'
257 - 'HYK 2: not enough elements in line #'
258 - 'HYK 5: not enough elements in line #'
259 - 'HYK 6: not enough elements in line #'
260 Eine Zeile in einer HYK-Datei hat nicht genügend Elemente.
261
262 - 'HYK: parsing num zones, bottom or top height failed in line #'
263 - 'HYK: HYK: number of flow zones mismatches in line #'
264 Die Anzahl der Zonen oder Daten über die Zonen sind nicht korrekt.
265
266 - 'HYK: cannot parse number in line #'
267 Eine Zahl wurde erwartet.
268
269 - 'HYK: Error reading file.'
270 Beim Lesen einer HYK-Datei trat ein Fehler auf.
271
272 - 'HYK: Error closing file.'
273 Beim Schliessen einer HYK-Datei trat ein Fehler auf.
274
275 Warnungen:
276 ----------
277
278 - 'annotation type file 'XYZ' is not readable.'
279 Die Datein XYZ kann nicht gelesen werden.
280
281 - 'cannot parse annotation types file.'
282 Während der Verarbeitung der Annotationsdatei ist Fehler aufgetreten.
283
284 - 'Cannot read directory.'
285 verzeichnis konnte nicht gelesen werden.
286
287 - 'no official lines wst file found'
288 Keine Datei mit amtlichen Linien gefunden.
289
290 - 'cannot read fixations wst file directory'
291 Das Verzeichnis mit den Fixierungen kann nicht gelesen werden.
292
293 - 'cannot read extra longitudinal wst file directory'
294 Das Verzeichnis mit den zusätzlichen Längsschnitten kann nicht gelesen werden.
295
296 - 'cannot read gauges from 'XYZ''
297 Die Pegelgültigkeiten können nicht gelesen werden.
298
299 - 'HYK file 'XYZ' seems to be a duplicate.'
300 Die HYK-Datei wurde unter anderem Namen aber gleichen Inhalts
301 bereits gefunden.
302
303 - 'PRF file 'XYZ' seems to be a duplicate.'
304 Die PRF-Datei wurde unter anderem Namen aber gleichen Inhalts
305 bereits gefunden.
306
307 - 'Skip invalid SedimentYield: time interval or unit null!'
308 Eine Sedimentablagerung ist ungültig und wurde ausgelassen.
309
310 - 'skip flow velocity model: No discharge zone specified.'
311 Da kein Abflussbereich angegeben wurde, wurde das Fliessgeschwindigkeitsmodell ausgelassen.
312
313 - 'skip invalid waterlevel - no unit set!'
314 Ein einheitenloser Wasserstand wurde ausgelassen.
315
316 - 'Cannot parse time range.'
317 Das Zeitformat wurde nicht erkannt.
318
319 - 'skip invalid data line #'
320 Ungültige Datenzeile wurde ausgelassen.
321
322 - 'Error while parsing sq relation row #'
323 Eine Zeile in der S(Q)-Beziehung ist ungültig.
324
325 - 'GLT: no gauge found in line #'
326 In der GLT-Datei wurde ein Pegel erwartet, aber nicht gefunden.
327
328 - 'GLT: line # has not enough columns.'
329 Eine Zeile in der Pegelgültigkeitsdatei hat nicht genug spalten.
330
331 - 'Error while parsing flow velocity values.'
332 - 'skip invalid data line: #'
333 Invalide Datenzeile in einer Datei mit einer Fliessgeschwindigkeitsmessung.
334
335 - 'skip invalid waterlevel line: #'
336 - 'Error while parsing value: #'
337 - 'Error while parsing station: #'
338 Invalide Datenzeile in einer Datei mit Wasserstandsdifferenzen.
339
340 - 'skip invalid MainValue part: #'
341 - 'skip invalid gauge part: #'
342 - 'Error while parsing Q value: <Q>'
343 - 'skip invalid data line: #'
344 - 'Error while parsing flow velocity values.'
345 Invalide Datenzeile in einer Datei Fliessgeschwindigkeitsmodellen.
346
347 - 'Error while parsing number from data row: #'
348 TODO INGO
349
350 - 'Unknown meta line: #'
351 - 'Error while parsing numbers in: #'
352 - 'skip invalid data line: #'
353 - 'Error while parsing numbers in #'
354 Invalide Datenzeile in einer Datei mit Sedimentdichten.
355
356 - 'STA file is empty'
357 - 'STA file has not enough lines'
358 - 'STA file is too short'
359 Stammdatendatei ist leer oder hat zu wenige Zeilen.
360
361 - 'First line in STA file is too short.'
362 Die erste Zeile der Stammdaten ist zu kurz.
363
364 - 'STA: second line is too short'
365 Die zweite Zeile ist zu kurz.
366
367 - 'STA: parsing of the datum of the gauge failed'
368
369 - 'STA: 'XYZ' is not a valid long number.'
370 Die Pegelnummer ist invalide.
371
372 - 'STA: Not enough columns for aeo and datum.
373 AEO und Pegelnullpunkt können nicht ermittelt werden.
374
375 - 'STA: cannot parse aeo or datum.'
376 AEO oder Pegelnullpunkt sind invalide.
377
378 - 'STA: value not parseable in line #'
379 Wert ist nicht als Zahl zu interpretieren.
380
381 - 'PRF: cannot open file <FILE>'
382 Die PRF kann nicht geöffnet werden.
383
384 - PRF: file is empty
385 - PRF: First line does not look like a PRF data pattern.
386 - PRF: premature EOF. Expected integer in line 2
387 - PRF: Expected <num> in line 2
388 - PRF: invalid integer in line 2
389 - PRF: premature EOF. Expected pattern for km extraction
390 - PRF: line 4 does not look like a PRF km extraction pattern.
391 - PRF: premature EOF. Expected skip row count.
392 - PRF: line 5 is not an positive integer.
393 - PRF: cannot extract km in line #
394 Das PRF-Format ist komplex. Hier sollten weitere Information
395 zur genaueren Analyse herangezogen werden.
396
397 - 'cannot access WST file <FILE>'
398 Die WST-Datei konnte nicht gefunden werden.
399
400 - 'Found an invalid row in the AT file.'
401 Eine Zeile in einer AT-Datei ist nicht korrekt.
402
403 - 'AT: invalid number <XYZ>'
404 Eine Zahl wurde erwartet aber nicht gefunden.
405
406 - 'Try to add Q range without waterlevel!'
407 Q-Bereich ohne Wasserstand gefunden.
408
409 - 'Error while parsing Q range: #'
410 Invalider Q-Bereich
411
412 - 'skip invalid waterlevel line: #'
413 Ungültige Wasserstandslinie
414
415 - 'Error while parsing number values: #'
416 Ungültige Zahlenwerte.
417
418 - 'ANN: not enough columns in line #'
419 Nicht genug Zeichenspalten in KM-Datei
420
421 - 'ANN: invalid number in line #'
422 Ungültige Zahl.
423
424 - 'ANN: cannot parse 'Unterkante' in line #'
425 Die Unterkante in einer KM-Datei konnte nicht gelesen werden.
426
427 - 'ANN: cannot parse 'Unterkante' or 'Oberkante' in line #'
428 Unter- oder Oberkannte liegen in einem falschen Format vor.
429
430 - 'ANN: duplicated annotation 'XYZ' in line #'
431 Ein Duplikat eines Streckenfavoriten wurde gefunden.
432
433 - 'ANN: 'XYZ' is not a directory.'
434 Unterverzeichnis konnte nicht geöffnet werden.
435
436 - 'ANN: cannot list directory 'XYZ''
437 Unterverzeichnis konnte nicht durchsucht werden.
438
439 - 'BHP: Meta line did not match any known type: #'
440 Unbekannter Typ.
441
442 - 'BHP: Error while parsing timeinterval!'
443 Ungültiges Zeitinterval.
444
445 - 'BHP: Error while parsing year!'
446 Ungültige Jahresangabe.
447
448 - 'BHP: Error while parsing sounding width!'
449 Unbekannte Peilungsbreite.
450
451 - 'BHP: Error while parsing range!'
452 Bereichsangabe fehlerhaft.
453
454 - 'MWP: Unknown meta line: #'
455 Meta-Informationen ungültig.
456
457 - 'MWP: skip invalid data line: #'
458 Ungültige Datenzeile wurde übersprungen.
459
460 - 'MWP: Error while parsing numbers in #'
461 Falsche Zahlenformat.
462
463 - 'ANNCLASS: rule has no name'
464 Klassifizierungsregel für Streckenfavoriten hat keinen Namen.
465
466 - 'ANNCLASS: pattern has no 'pattern' attribute.'
467 Klassifizierungsmuster für Streckenfavoriten hat kein Muster.
468
469 - 'ANNCLASS: pattern has unknown type 'XYZ''
470 Klassifizierungsmuster für Streckenfavoriten konnte keinem Typ zugeordnet werden.
471
472 - 'ANNCLASS: pattern 'XYZ' is invalid.'
473 Klassifizierungsmuster für Streckenfavoriten ist ungültig.
474
475 - 'BSP: Error while parsing data row.'
476 Ungültige Datenzeile.
477
478 - 'SYP: Unknown meta line: #'
479 Ungültige Metadatenzeile.
480
481 - 'SYP: skip invalid data line #'
482 Ungültige Datenzeile wurde übersprungen.
483
484 - 'SYP: Error while parsing numbers in #'
485 Ungültige Zahlenformatierung.
486
487 - 'SYP: Unknown time interval string <XYZ>'
488 Falsches Datumformat.
489
490 - 'SYP: Error while parsing years <XYZ>'
491 Falsches Jahreszahlformat.
492
493 - 'SYP: Error while parsing ranges of <XYZ>'
494 Bereichsangaben fehlerhaft.
495
496 - 'SYP: Unknown grain fraction <XYZ>'
497 Unbekannte Kornfraktion.
498
499 - 'WST: invalid number.'
500 Ungültige Zahl.
501
502 - 'WST: km <km> (<Zeile>) found more than once. -> ignored.'
503 Ein Kilometer ist doppelt in einer WST-Datei enthalten.
504
505 - 'HYK: zone coordinates swapped in line #'
506 Fliesszonenkordinaten wurden in umgekehrter Reihenfolge angeben.
507
508 - 'BHS: Skip invalid file 'XYZ''
509 Die Inhalte der Datei sind ungültig.
510
511 - 'ISQ: Unable to store sq relation value.'
512 S(Q) Beziehung konnte nicht gespeichert werden.
513
514 - 'ISQ: Cannot determine sq relation without time interval.'
515 Einer S(Q)-Beziehung ist keine zeitliche Gültigkeit zugeordnet.
516
517 - 'IWD: skip invalid waterlevel difference - no unit set!'
518 Wasserstandsdifferenz hat keine Einheit.
519
520 - 'BHE: Skip file - invalid current elevation model.'
521 Höhenmodell ungültig.
522
523 - 'BHE: Skip file - invalid time range.'
524 Zeitbereich ungültig.
525
526 - 'BHE: Skip file - invalid km range.'
527 Kilometerbereich ungültig.
528

http://dive4elements.wald.intevation.org