view README.markdown @ 1292:588f6deae24a

Fix authorization for OrtszuordnungMp and friends. Setting readonly equal to owner implied an owner cannot edit its own objects. That was probably not intended. As many of the conditionals actually evaluated to doing nothing, those were removed.
author Tom Gottfried <tom@intevation.de>
date Wed, 08 Feb 2017 19:56:01 +0100
parents b22ffbf88a43
children
line wrap: on
line source
Lada-Server
===========
Die Software bietet Funktionalität zur Erfassung und Bearbeitung
von Messdaten. Sowie der Planung der Messungen.

Weitere Informationen finden sich auf der Projektwebseite unter
der Adresse: https://wald.intevation.org/projects/lada/

Die Software entstand im Rahmen einer Software Entwicklung durch die
Intevation GmbH im Auftrag des Bundesamt für Strahlenschutz in den Jahren 2013
bis 2015.

Kontakt
-------
Bundesamt für Strahlenschutz
SW2 Notfallschutz, Zentralstelle des Bundes (ZdB)
Willy-Brandt-Strasse 5
38226 Salzgitter
info@bfs.de

Lizenz
------
Die Software ist unter der GNU GPL v>=3 Lizenz verfügbar.
Details siehe die Datei `COPYING`.

Quelltext
---------
Die Quelldateien lassen sich wie folgt auschecken:
```
hg clone https://scm.wald.intevation.org/hg/lada/lada-server
```

Entwicklung
-----------
Für die Entwicklung wird ein JDK7 und maven3 oder höher benötigt. Sämtliche
Abhängigkeiten werden von dem maven build System aufgelöst.

Installation
------------
Die Installation des Lada-Servers erfolgt in einem Wildfly-Application-Server
(http://wildfly.org). Dazu müssen folgende Schritte unternommen werden:

 $ mvn clean compile package
 $ mv target/lada-server-$VERSION.war $JBOSS_HOME/standalone/deployments
 $ touch $JBOSS_HOME/standalone/deployments/lada-server-$VERSION.war.dodeploy

$JBOSS_HOME ist hierbei durch den Pfad zur Wildfly-Installation zu ersetzen,
$VERSION durch die aktuelle Versionsbezeichnung (entsprechend der Angabe in
pom.xml).

Zum Aktualisieren der Anwendung genügt es, das WAR-Archiv zu aktualisieren.

Die Anwendung ist dann unter dem Pfad "/lada-server-$VERSION" erreichbar.

Um zu garantieren, dass die von den REST-Schnittstellen ausgelieferten
Zeitstempel sich korrekt auf UTC beziehen, muss die entsprechende System-
Property `user.timezone=UTC` vor dem Start des Application-Servers gesetzt
werden (siehe `wildfly/standalone.conf`).

Das PostgreSQL-Datenbank-Backend des Lada-Servers kann als Nutzer `postgres`
(bzw. als PostgreSQL-Superuser) mit dem Skript `db_schema/setup-db.sh`
eingerichtet werden.

Details zur Installation können den Dateien `Dockerfile` und
`db_schema/Dockerfile` entnommen werden.

Docker
------
Um schnell und automatisiert ein Entwicklungs-Setup für LADA aufsetzen zu
können, werden Dockerfiles mitgeliefert. Voraussetzung für die Anwendung ist
eine Docker-Installation. Folgendes Vorgehen führt zu einem
Vollständigen Setup inklusive LADA-Client, in dem jeweils der auf dem Host
vorhandene Quellcode in die Container gemounted wird, so dass auf dem Host
durchgeführte Änderungen leicht innerhalb der Container getestet werden können.

Bauen der Images:
 $ cd ./db_schema
 $ docker build -t koala/lada_db .
 $ cd ..
 $ docker build -t koala/lada_wildfly .
 $ cd your/repo/of/lada-client
 $ docker build -t koala/lada_client .

Aufbau eines Netzwerks für die LADA-Komponenten:
 $ docker network create lada_network

Starten der Container:
 $ cd db_schema
 $ docker run --name your_lada_db --net=lada_network -v $PWD:/opt/lada_sql/ \
          -d koala/lada_db:latest
 $ cd ..
 $ docker run --name lada_wildfly --net=lada_network \
          --link your_lada_db:lada_db -v $PWD:/usr/src/lada-server \
          -d koala/lada_wildfly
 $ cd your/repo/of/lada-client
 $ docker run --name lada_client --net=lada_network \
              -v $PWD:/var/www/html/ \
              --link lada_wildfly:lada-server \
              -p 8180-8184:80-84 -d koala/lada_client

Die LADA-Anwendung kann dann unter den angegebenen Ports mit verschiedenen
Rollen im Browser ausgeführt werden.

Tests
-----
Die auf Arquillian basierenden Tests erfordern einen vollständig konfigurierten
und gestarteten Wildfly Application-Server, da für die Schnittstellentest eine
Clientanwendung simuliert wird und HTTP-Requests ausgeführt werden.

Das Ausführen der Tests erfolgt durch das Kommando

 $ mvn -Premote-test clean test

und benötigt eine leere Datenbank, die z.B. mit

 $ ./setup-db.sh -cn

angelegt werden kann.

Dokumenation
------------
Die Entwicklerdokumentation (Javadoc) kann mit dem folgenden Befehl im
Verzeichnis der Serveranwendung erzeugt werden:

 $ mvn javadoc:javadoc

Der Ordner 'target' enthält dann die Dokumentation im HTML-Format in dem
Verzeichnis 'site/apidocs'.

Erstellen von Queries
---------------------
Queries können als SQL-Statement in der Tabelle stammdaten.queries definiert
werden. Eine Filterung kann über Variablen erfolgen, die in stammdaten.filter
definiert werden müssen und mittels SQL-Interpolation im SQL-Statement
verwendet werden können.
Um neue Queries für die Suche von Proben, Messungen und Messprogrammen zu
erstellen sind die folgenden Schritte erforderlich:

1. In der Tabelle 'stammdaten.query' einen neuen Eintrag erzeugen.
   * id: Primary-Key (wird generiert)
   * name: Der Name der Query
   * type: Der Datentyp der gefiltert werden soll.
     (mögliche Werte siehe Datenbank-Schema-Definition)
   * sql: Das auszuführende SQL-Statement (siehe #Regeln für die Syntax)
   * description: Ein beschreibender Text

2. In der Tabelle 'stammdaten.result' für die anzuzeigenden Felder je einen
   Eintrag erzeugen:
   * id: Primary-Key (wird generiert)
   * query_id: ID der zugehörigen und in Schritt 1. erzeugten Query
   * data_index: Name des Feldes zur Übertragung an den Client (in CamelCase)
   * header: Der Titel der Spalte für diesen Eintrag
   * width: Die Spaltenbreite (in Pixel)
   * flex: Dynamische Spaltenbreite (true/false)
   * index: Der Datenindex

3. In der Tabelle 'stammdaten.filter' für jeden Parameter in der 'WHERE'-Clause
   der Query einen Eintrag erzeugen:
   * id: Primary-Key (wird generiert)
   * query_id: ID der zugehörigen und in Schritt 1. erzeugten Query
   * data_index: Der Name der Variablen, die in dem 'WHERE'-Statement ersetzt
     werden soll
   * type: Datenbasis, die im Client als Eingabe genutzt werden soll
     (mögliche Werte siehe Datenbank-Schema-Definition)
   * label: Der angezeigte Name des Filters
   * multiselect: Mehrfachangabe von Werten für diesen Filter (true/false)

### Regeln

* Bei Queries vom Typ `probe` muss das erste selektierte Feld `probe.id` sein.
  Dieses wird in der Oberfläche nicht angezeigt.
* Bei Queries vom Typ `messung` muss das erste selektierte Feld `messung.id`
  und das zweite `probe.id` sein. Diese werden in der Oberfläche nicht
  angezeigt. Für `probe.id` muss in stammdaten.result ein Eintrag mit
  `data_index = 'probeId'` angelegt werden (obwohl diese Spalte nicht angezeigt
  wird). Um im Client die Funktionalität zu erhalten, sollten Messungsfilter
  die beiden Felder `probe.hauptproben_nr` und `messung.nebenproben_nr`
  enthalten.
* Bei Queries vom Typ `messprogramm` muss das erste selektierte Feld
  `messprogramm.id` sein. Dieses wird in der Oberfläche nicht angezeigt.
* Werden bei einem JOIN Spalten gleichen Namens aus verschiedenen Tabellen
  in der SELECT-Clause verwendet, so müssen diese mit einem expliziten Alias
  versehen werden, um eine
  org.hibernate.loader.custom.NonUniqueDiscoveredSqlAliasException zu
  vermeiden.
* Im `WHERE`-Statement genutzte Variablen müssen in der Form `:variablenName`
  angegeben werden und dem Feld `data_index` im zugehörigen Filter entsprechen.
* Wenn ein Filter mit `multiselect = true` angegeben wird, so wird in der
  `WHERE`-Clause ein `SIMILAR TO` erwartet.
* Das Feld `index` in der Tabelle `stammdaten.result` dient zur Zuordnung des
  selektierten Datenfeldes zu dem Entsprechenden Eintrag in der Tabelle
  `stammdaten.result`. Beispiel:
```
    'SELECT probe.id, probe.mst_id AS mstId, probe.hauptproben_nr AS hpNr, ...'
                      |----- index 1 -----|  |--------- index 2 --------|
    Wird in der Tabelle 'stammdaten.result' zu:
    Result 1:
    ...
        data_index: mstId
        header: Messstelle
        width: 100
        flex: false
        index: 1
    ...
    Result 2:
    ...
        data_index: hpNr
        header: Hauptproben Nr
        width: 150
        flex: false
        index: 2
    ....
```
* Queries für Stammdaten werden gesondert behandelt und beinhalten keine
  SQL-Statements. Dementsprechend können auch keine Einträge für Ergebnisse in
  der Tabelle `stammdaten.result` gemacht werden. Filter können allerdings,
  unter der Bedingung, dass `data_index` auf einen in dem Datentyp vorhandenes
  und in CamelCase geschriebenes Datenfeld zeigt, angelegt werden.
  Momentan sind Queries für die folgenden Stammdaten möglich:
   * Orte
   * Probennehmer
   * Datensatzerzeuger
   * Messprogrammkategorien
This site is hosted by Intevation GmbH (Datenschutzerklärung und Impressum | Privacy Policy and Imprint)