<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="scheduler_job_documentation.xsl"?>
<description xmlns="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0 http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0.xsd">

  <job name  = "JobSchedulerWebServiceShellJob" 
       title = "Process shell script for (a)synchronous Web Service request" 
       order = "both">
    <script language = "java" 
            java_class = "sos.stacks.webservice.JobSchedulerWebServiceShellJob"
            resource = "4"/>
  </job>

  <releases>
    <release id="1.0" created="2006-05-20" modified="2006-05-26">
      <title>Version 1.0</title>
      <author name="Andreas Püschel" email="andreas.pueschel@sos-berlin.com"/>
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Initiale Auslieferung
        </div> 
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
          initial release
        </div>
      </note>
    </release>
  </releases>

  <resources>
    <file os="all" type="java" file="sos.scheduler.jar" id="1">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Standard-Jobs der Auslieferung
        </div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Standard jobs in distribution
        </div>
      </note>
    </file>
    <file os="all" type="java" file="sos.spooler.jar" id="2">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Klasse Job_Impl
        </div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Class Job_Impl
        </div>
      </note>
    </file>
    <file os="all" type="java" file="sos.stacks.jar" id="4">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
          Klasse JobSchedulerWebServiceShellJob
        </div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">      
          Class JobSchedulerWebServiceShellJob
        </div>
      </note>
    </file>
  </resources>

  <configuration>
    <params id="job_parameter">
      <param name="shell_command" required="true">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter benennt den Inhalt der Kommandozeile, der ausgeführt wird. 
            Dies kann ein Shell Script oder eine ausführbare Datei sein.
            <br/><br/>
            Die Parameter des Jobs bzw. des Auftrags werden der Kommandozeile automatisch als Umgebungsvariable
            zur Verfpügung gestellt. Die Namen der Umgebungsvariablen werden als 
            Kommandozeilenparameter übergeben, deren Werte dagegen nicht, da dies nur
            schwer gegen code injection abzusichern wäre.
            <br/><br/>
            Als Beispiel für Windows können Sie ein Kommando wie folgt verwenden:
            <br/><br/>
            <code>
              cmd.exe /V:ON /C /scheduler/samples/shell.webservice.command/webservice_shell.cmd
            </code>
            <br/><br/>
            Unter Windows können Batch-Dateien nicht direkt gestartet werden, 
            sondern müssen mit der Shell <code>cmd.exe</code> aufgerufen werden.
            <br/><br/>
            Als Beispiel für Unix können Sie ein Kommando wie folgt verwenden:
            <br/><br/>
            <code>
              samples/shell.webservice.command/webservice_shell.sh
            </code>
            <br/><br/>
            Die Beispiele finden Sie in der Beschreibung des Software-Stacks für Web Services.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the command line that should be executed. 
            This could be a shell script or an executable file.
            <br/><br/>
            The parameters of this job resp. of an order are automatically provided as environment variables.
            The names of these variables are forwarded als parameters to the command line. 
            The values are not given in the command line parameters as this would be quite hard to 
            secure against code injection.
            <br/><br/>
            As an example for Windows you could specify a command such as:
            <br/><br/>
            <code>
              cmd.exe /V:ON /C /scheduler/samples/shell.webservice.command/webservice_shell.cmd
            </code>
            <br/><br/>
            Windows batch files cannot be started directly, but have to
            be launched by the shell <code>cmd.exe</code>.
            <br/><br/>
            As an example for Unix you could specify a command such as:
            <br/><br/>
            <code>
              samples/shell.webservice.command/webservice_shell.sh
            </code>
            <br/><br/>
            You will find these samples in the software stack description for Web Services.
          </div>
        </note>
      </param>
      <param name="&lt;any&gt;" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Job kann beliebige weitere Parameter annehmen, alle Parameter
            werden als Umgebungsvariablen bereitgestellt, ihre Namen der Kommandozeile übergeben,
            siehe Parameter <code>shell_command</code>.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This job processes arbitrary additional parameters, all parameters
            will be provided as environment variables and their names will be forwarded to the command line,
            see parameter <code>shell_command</code>.
          </div>
        </note>
      </param>
    </params>
  </configuration>

  <documentation language="de">
    <div xmlns="http://www.w3.org/1999/xhtml">
      Dieser Job startet ein angebbares Shell Script
      oder eine ausführbare Datei, warten deren Ausführung ab
      und übernimmt Ausgaben nach <code>stdout</code> und <code>stderr</code> in das Protokoll.
      <br/><br/>
      Der Job stellt der Kommandozeile die Job- bzw. Auftragsparameter 
      als Umgebungsvariablen zur Verfügung, die Namen der Umgebungsvariablen werden
      der Kommandozeile übergeben.
      <br/><br/>
      Der Job kann standalone verwendet werden oder wird mit Aufträgen
      in einer Job-Kette eingesetzt, die aus folgenden Job-Knoten besteht:
      <br/><br/>
      <ul>
        <li>Annahme und Verarbeitung von Web Service Anfragen (JobSchedulerWebServiceShellJobRequest)</li>
        <li>Ausführung einer Kommandozeile mit den Parametern der Anfrage (JobSchedulerWebServiceShellJob)</li>
        <li>Verarbeitung und Weiterleitung der Web Service Antwort (JobSchedulerWebServiceShellJobResponse)</li>
      </ul>
      <br/>
      Der Job kann standalone für asynchrone Web Services eingesetzt werden, und in einer Job-Kette
      für synchrone wie asynchrone Web Service Anfragen.
      <br/><br/>
      Der Job ist alternativ in den Sprachen Java, JavaScript und Perl implementiert. 
      Empfohlen wird die Verwendung der Java-Implementierung.
    </div>
  </documentation>

  <documentation language="en">
    <div xmlns="http://www.w3.org/1999/xhtml">
      This job starts a shell script or executable file, waits for its termination
      and catches output to <code>stdout</code> and <code>stderr</code> for logging.
      <br/><br/>
      This job provides the job parameters resp. order parameters as environment variables
      for the command line. The names of the environment variables are forwarded to the command line.
      <br/><br/>
      This job can be used standalone or with orders in a job chain that is composed of the job nodes:
      <br/><br/>
      <ul>
        <li>Receive and Process Web Service request (JobSchedulerWebServiceShellJobRequest)</li>
        <li>Do some job execution with the request content (JobSchedulerWebServiceShellJob)</li>
        <li>Process and forward Web Service response (JobSchedulerWebServiceShellJobResponse)</li>
      </ul>
      <br/>
      This job can be used standalone for asynchronous Web Service requests, and in a job chain
      for synchronous and asynchronous Web Service requests.
      <br/><br/>
      This job is alternatively available in Java, JavaScript and Perl.
      The Java implementation is recommended for use.
    </div>
  </documentation>
</description>
