Kapitel 7. Webservice-Schnittstelle

Es ist möglich, serverseitig eine in XML kodierte Jobbeschreibung abzulegen, sodass ein Client bei einer SOAP-Anfrage auf diese verweisen kann und der Job nicht zur Laufzeit konfiguriert werden muss.

Der Aufbau dieser Nachricht soll anhand des folgenden Beispiels erläutert werden:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ws="http://ws.server.jadice.levigo.com/">
 <soapenv:Header/>
 <soapenv:Body>
  <ws:run>
   <job templateLocation="resource:/jobtemplates/x2pdf.xml">
    <property name="dp.rulesetName">default</property>
    <property name="dp.targetMimeType">application/pdf</property>
    <property name="dp.timeout">8000</property>
    <stream mimeType="unknown/*" uuid="123456789"nodeId="node0">
     <documentData>BASE64_encoded_data</documentData>
    </stream>
   </job>
  </ws:run>
 </soapenv:Body>
</soapenv:Envelope>
        

Neben den vom SOAP-Standard vorgegebenen Elementen für Header und Body gibt es das spezifische Element run, das die vom Webservice angebotene Methode run adressiert.

Darin wird ein Job (siehe Kapitel 4, Systemarchitektur) definiert, der über ein Template vordefiniert ist (siehe Abschnitt „Definition von Job-Templates“). Im Attribut templateLocation steht dabei der Ort, an dem das jeweilige Template serverseitig zu finden ist. Sind im Template Variablen definiert, so können diese mittels property-Elementen konfiguriert bzw. deren Standardwert überschrieben werden. Optional ist das Attribut messageID. Dies kann der Client frei vergeben und wird ggf. in einer Antwort des Servers übernommen.

Zu verarbeitende Datenströme werden über stream-Elemente in der SOAP-Nachricht referenziert. Die Angabe einer eindeutigen ID (uuid) und des MIME-Typen sind optional. Sollte der MIME-Type nicht bekannt sein, aber dennoch angegeben werden, so ist dort unknown/* anzugeben.

Sind in der Templatedatei mehrere StreamInputNodes definiert, so muss eine eindeutige Zuordnung getroffen werden, welcher Datenstrom an welchen StreamInputNode gesendet wird. Dies erfolgt durch das Attribut nodeId. Dies verweist auf die ID, die dem StreamInputNode innerhalb des Templates (Attribut id) gegeben wurde.

Die eigentlichen Daten können entweder direkt im Tag documentData als Base64-codierter Datenstrom angegeben werden oder in einem multipart/related-Container referenziert werden, der die hier angegebene CID (contentID) besitzt, wenn das MTOM-Feature aktiviert ist.

Soll der Client keine serverseitig vordefinierte Jobkonfiguration verwenden, ist es möglich, diese in der SOAP-Anfrage einzubetten. Das Format ist hierbei das selbe, wie innerhalb eines separaten Job-Templates (vgl. Abschnitt „Definition von Job-Templates“). Anstelle des Root-Elements job wird hierbei die Definition als configuration-Element in die SOAP-Anfrage eingebettet.

Das folgende Beispiel soll dies veranschaulichen:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ws="http://ws.server.jadice.levigo.com/">
 <soapenv:Header/>
 <soapenv:Body>
  <ws:run>
   <job messageID="4711">
    <configuration type="demultipexer example">
     <nodes>
      <node class="com.levigo.jadice.server.nodes.StreamInputNode" id="input1" />
      <node class="com.levigo.jadice.server.nodes.StreamInputNode" id="input2" />
      <node class="com.levigo.jadice.server.nodes.DemultiplexerNode" id="demux" />
      <node class="com.levigo.jadice.server.nodes.StreamOutputNode" id="out" />
     </nodes>
     <connections>
      <connect from="input1" to="demux" />
      <connect from="input2" to="demux" />
      <connect from="demux" to="out" />
     </connections>
    </configuration>
    <stream nodeId="input1">
     <documentData>BASE64_encoded_data</documentData>
    </stream>
    <stream nodeId="input2">
     <documentData>BASE64_encoded_data</documentData>
    </stream>
   </job>
 </ws:run>
</soapenv:Body>
</soapenv:Envelope>
        

In diesem Beispiel werden zwei StreamInputNodes miteinander über einen DemultiplexerNode gekoppelt und die Eingabedaten unverändert an den Client zurückgesendet.

Die Definition der Nodes und welchen Workflow-Graphen sie bilden, ist innerhalb des Blocks configuration beschrieben.

Hier ist außerdem zu sehen, wie es möglich ist, bestimmte Eingabeströme an einen StreamInputNode zu binden: Das erste Dokument wird an den ersten (nodeId input1), das zweite Dokument an den zweiten StreamInputNode (nodeId input2) gebunden.