Difference between revisions of "OS4X Server-side plugin philosophy"

Revision as of 16:57, 15 June 2008

Server-side OS4X plugins are programs which are executed during job processing. Plugins can be any type of executable: compiled programs, Java programs, shell/Perl/PHP/... scripts.

There are two types of plugins:

Synchronous plugins: will be executed by the plugin handler. The starting process waits until end of plugin execution.
Asynchronous plugins: will be executed by the plugin handler and job processing instantly stops. The job receives the status 'waiting for asynchronous plugin'. The plugin itself is responsible to start the asynchronous plugin handler at its end. Asynchronous plugins must understand the parameter "-c" in order to cancel job processing asynchronously.

Plugins receive an XML as parameter which contain all job parameters. The plugin may modify this XML file. The plugin handler starts the plugin with the last actual XML file, afterwards it reads in this XML file and saves is in the database as the actual XML.

The standard output "stdout" and "stderr" will be read in and saved in the plugins logs, attached to the actual job.

The return code of the executed plugin is received by the plugin handler (synchronous or asynchronous). If the return code is zero (0), job processing continues. If it's non-zero, job processing stops and the job receives the status "aborted".

At the end of plugin execution (even successful or unsuccessful), all files contained in the job XML with the attribute "copy" or "ENGDAT" will be deleted from the filesystem.

plugin parameters

Plugins must understand several combinations of parameters.

normal behaviour

Plugins receive one parameter: the absolute path of an XML file. All job information will be parsed from this XML file.

normal behaviour with configuration

Plugins receive two parameters: the absolute paths of two XML files. All job information will be parsed from the first XML file, the runtime configuration from the second. More information in the plugin configuration documentation.

automatic plugin installation

The only parameter is "-a". The plugin checks its availability in the plugin database table and its configuration parameters. This mode is usually used for automatic updates and installation.

configuration

In order to display configuration possibilities, plugins may support the parameter "-x". The output of the plugin must be a plugin with a special structure. Refer to the plugin configuration documentation for more information.

@@ Line 1: / Line 1: @@
-== german ==
+Server-side OS4X plugins are programs which are executed during job processing. Plugins can be any type of executable: compiled programs, Java programs, shell/Perl/PHP/... scripts.
-Server-seitige Plugins werden (wie der Name schon aussagt) am OS4X-Server ausgeführt. Plugins können ausführbare Dateien sein, daher können es Binaries oder Scripte (Shell, Perl, PHP etc.) sein.
+There are two types of plugins:
+*Synchronous plugins: will be executed by the plugin handler. The starting process waits until end of plugin execution.
+*Asynchronous plugins: will be executed by the plugin handler and job processing instantly stops. The job receives the status 'waiting for asynchronous plugin'. The plugin itself is responsible to start the asynchronous plugin handler at its end. Asynchronous plugins must understand the parameter "<code>-c</code>" in order to cancel job processing asynchronously.
-Es gibt zwei Arten von Plugins: synchrone und asynchrone.
+Plugins receive an XML as parameter which contain all job parameters. The plugin may modify this XML file. The plugin handler starts the plugin with the last actual XML file, afterwards it reads in this XML file and saves is in the database as the actual XML.
-* Synchrone Plugins werden gestartet und der startende Prozess wartet solange, bis das Plugin beendet wurde.
-* Asynchrone Plugins werden gestartet (für das Prozessmanagement sind sie selbst verantwortlich) und der Plugin-Handler beendet sich. Es muss nach Abarbeitung des Plugins ein asynchroner Plugin-Handler aufgerufen werden, der dann die Jobabarbeitung wieder aufnimmt.
-Plugins erhalten als Parameter (ohne vorangehendes "<code>-</code>" zur Deklarierung, dass es sich hierbei um einen anderen Parameter handeln könnte) eine XML-Datei oder die Auftragsnummer, je nach Plugin. Manche Plugins erlauben auch beide Arten von Parametern und/oder weitere Parameter. Mindestens jedoch muss ein Plugin eine XML-Datei als Parameter interpretieren können.
+The standard output "stdout" and "stderr" will be read in and saved in the plugins logs, attached to the actual job.
-Die Standard-(Fehler-)Ausgabe "<code>stdout</code>" und "<code>stderr</code>" werden vom Plugin-Handler aufgenommen und dem Auftrag in die Plugin-Logs hinzugefügt.
+The return code of the executed plugin is received by the plugin handler (synchronous or asynchronous). If the return code is zero (0), job processing continues. If it's non-zero, job processing stops and the job receives the status "aborted".
-Der Returncode des Plugins wird erfasst und bei einem Wert ungleich 0 wird der Auftrag abgebrochen.
+At the end of plugin execution (even successful or unsuccessful), all files contained in the job XML with the attribute "<code>copy</code>" or "<code>ENGDAT</code>" will be deleted from the filesystem.
-Im Abbruchfall werden Dateien mit dem Nodeattribut "<code>copy</code>" oder "<code>ENGDAT</code>" automatisch gelöscht, damit keine temporären Dateien als Leichen im Filesystem liegen bleiben.
-== english ==
+=== plugin parameters ===
+Plugins must understand several combinations of parameters.
+==== normal behaviour ====
+Plugins receive one parameter: the absolute path of an XML file. All job information will be parsed from this XML file.
+==== normal behaviour with configuration ====
+Plugins receive two parameters: the absolute paths of two XML files. All job information will be parsed from the first XML file, the runtime configuration from the second. More information in the [[OS4X Enterprise plugin configuration|plugin configuration]] documentation.
+==== automatic plugin installation ====
+The only parameter is "<code>-a</code>". The plugin checks its availability in the plugin database table and its configuration parameters. This mode is usually used for automatic updates and installation.
+==== configuration ====
+In order to display configuration possibilities, plugins may support the parameter "<code>-x</code>". The output of the plugin must be a plugin with a special structure. Refer to the [[OS4X Enterprise plugin configuration|plugin configuration]] documentation for more information.