Die Schnittstelle zum Scheduler:

Die Aufträge, die von der Web-Oberfläche losgeschickt werden, werden von einem 
separaten Prozess entgegen genommen und nacheinander abgearbeitet. Dieser Prozess 
wird im folgenden Scheduler genannt.

Der Scheduler selbst wird über eine HTTP-Schnittstelle gesteuert. Seine 
Arbeitsanweisungen erhält er über HTTP-GET oder -POST-Requests.
Der HTTP-Server läuft standardmäßig auf Port 8880, dies kann aber über die
System.Property 'port' geändert werden.

!!! Zur Sicherheit ist zu sagen, dass der Scheduler nicht am offenen Internet 
!!! betrieben werden sollte. Er ist dafür gedacht, in einem abgesicherten Netz 
!!! die Aufträge aus der Web-Applikation entgegenzunehmen und zuverarbeiten.

Die Aufträge haben im Scheduler einen Status ('status'), der angibt, wie
zur Zeit ihr Bearbeitungszustand ist. Dieser kann folgende Werte annehmen.

    0: Der Auftrag wurde erfolgreich abgearbeitet. Details finden sich
       im Feld "result_msg", das über "list" zu erfragen ist.

    1: Der Auftrag wartet darauf vom Scheduler abgearbeitet zu werden.

    2: Bei der Bearbeitung ist ein Fehler aufgetreten. Details: "result_msg"

    3: Der Job wurde manuell abgebrochen. Details: "result_msg"

    4: Der Job befindet sich derweil in Bearbeitung

Der auszuführende Befehl wird über den Parameter 'cmd' übergeben.
Folgende Befehle stehen aktuell zur Verfügung:

1 - "add"      fügt einen neuen Auftrag hinzu.
2 - "list"     listet die Aufträge eines speziellen Benutzers auf.
3 - "delete"   löscht Aufträge aus der Warteschlange.
4 - "stop"     Hält Jobs an.
5 - "restart"  Startet angehaltene Aufträge neu.
6 - "shutdown" beendet den Scheduler.

7 - "kill"     Beendet Aufträge, die sich zur Zeit in Bearbeitung befinden.
               !!! Dieser Befehl wird auf delete abgebildet !!!

Die Antwort auf einen Befehl ist ein XML-Dokument (MIME-Typ "application/xml").
dessem Wurzel-Element ein "reply"-Knoten ist. Dessen Attribut "status"
gibt an, ob der Befehl erfolgreich ausgeführt (Wert ist 0) wurde oder
nicht (Wert ungleich 0). In Abhängikeit vom jeweiligen Befehl, sind
noch weitere Knoten in das Wurzel-Element eingebettet, die dann Details
zur Rückgabe enthalten. "shutdown" sendet bei Erfolg keine Antwort.

Im folgenden wird das Kommandozeilen-Werkzeug "curl" [1] benutzt, um
die korrekte Benutzung der Schnittstelle zu illustrieren.

zu 1: Über "add" werden neue Aufträge in die Warteschlange eingereiht.
      Folgende Parameter werden unterstützt.
          "user_id":     notwendig.    User ID in der Datenbank.
          "fluss":       notwendig.    Name des Fliessgewaessers.
          "user_msg:     optional.     Frei wählbarer Text.
          "email":       optional.     Benachrichtigungs-E-Mail-Adresse.
          "delta_von":  
          "delta_bis":  
          "delta_diff":  optional.     Siehe Dokumentation von WSPLGEN.
          "gel":         optional.     Siehe Dokumentation von WSPLGEN.
          "lin":         optional.     Siehe Dokumentation von WSPLGEN.
          "strecke_von":
          "strecke_bis": optional.     Siehe Dokumentation von WSPLGEN.
          "wsp":         ggf.optional. Siehe Dokumentation von WSPLGEN.
          "wsptag":      ggf.optional. Siehe Dokumentation von WSPLGEN.

      Beispiel:
          $ curl 'http://localhost:8880/add?user_id=Otto&fluss=Saar'
          liefert:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="0" msg="job enqueued"/>

zu 2: "list" listet die Aufträge eines Benutzers auf.
      Folgende Parameter werden unterstützt.
          "user_id":   notwendig. User ID in der Datenbank.

      Beispiel:
          $ curl 'http://localhost:8880/list?user_id=2'
          liefert je nach Job-Liste beispielsweise:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="0">
          <list user_id="2">
          <job id='2' status='1' enqueue_time='2007-09-16 13:16:59'/>
          <job id='5' status='1' enqueue_time='2007-09-16 13:42:57'/>
          <job id='6' status='1' enqueue_time='2007-09-16 14:33:41'/>
          </list>
          </reply>

zu 3: "delete" löscht wartende und beendete Aufträge aus der Liste eines Benutzers.
      Folgende Parameter werden unterstützt.
          "job_ids":   notwendig. Kommaseparierte Liste mit Auftragsnummern,
                       deren zugeordnete Aufträge gelöscht werden sollen.
      Beispiel:
          $ curl 'http://localhost:8880/delete?&job_ids=2,6'
          ergibt für obiges "list"-Beispiel:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="0"/>

zu 4: "stop" hält Aufträge an, löscht sie aber nicht aus der Job-Liste.
      Folgende Parameter werden unterstützt.
          "job_ids":   notwendig. Kommaseparierte Liste mit Auftragsnummern,
                       deren zugeordnete Aufträge angehalten werden sollen.
      Beispiel:
          $ curl 'http://localhost:8880/stop?&job_ids=2,6'
          ergibt für obiges "list"-Beispiel:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="0"/>

zu 5: "restart" startet angehaltene Aufträge neu.
      Folgende Parameter werden unterstützt.
          "job_ids":   notwendig. Kommaseparierte Liste mit Auftragsnummern,
                       deren zugeordnete Aufträge angehalten werden sollen.
      Beispiel:
          $ curl 'http://localhost:8880/restart?&job_ids=2,6'
          ergibt für obiges "list"-Beispiel:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="0"/>

zu 6: "shutdown" beendet den Scheduler. Dies sorgt u.a. dafür, dass
      Die Datenbank, in der die Aufträge gespeichert werden, korrekt herunter
      gefahren wird.
      Folgende Parameter werden unterstützt.
          "password": notwendig. Um das versehentliche (oder unbefugte)
                      Herrunterfahren zu verhindern, ist hierfür ein
                      Passwort erforderlich. Standardmäßig lautet dies "die!".
                      Es kann allerdings über die System-Property "shutdown"
                      geändert werden. Aus Sicherheitsgründen ist dies anzuraten.
      Beispiel:
          $ curl 'http://localhost:8880/shutdown?password=234'
          ergibt:
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <reply status="1" msg="wrong password!"/>

zu 7: "kill" dient dazu, Aufträge zu beenden, die sich derzeit aktiv in der 
      Ausführung befinden.
      !!! Dies is ein Synonym für "delete" !!!

[1] http://curl.haxx.se