Kapitel 7. Webservice-Schnittstelle

Durch die Definition von Job-Templates wurde die Möglichkeit geschaffen, dass Clients nun nicht mehr die internen Schritte des jadice server, die für eine Konvertierung notwendig sind, kennen müssen. Diese werden für die Webservice-Schnittstelle an zentraler Stelle vorgehalten werden. Dadurch muss der Client nunmehr nur noch die Webservice-Methode run“ sowie den Ort des auszuführenden Templates kennen (diese liegen i.d.R. im Unterordner /server-config/).

Im Ordner /server-config/jobtemplates liegt die XSD-Definition für diese Templates.

Ein Beispiel, wie solch ein Template aussehen kann, ist das im Lieferumfang enthaltene Template x2pdf.xml, das ähnlich dem Beispiel aus Abschnitt „Konvertierung unbekannter Eingabedaten in ein einheitliches Format (PDF)“ unbekannte Eingabedaten identifiziert und in das PDF-Format umwandelt:

<job xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="jobtemplate.xsd" type="x2pdf">
 <properties>
  <property name="PROPERTY_KEY_COMMUNICATION_TIMEOUT">${communication_timeout:22000}</property>
 </properties>
 <nodes>
  <node class="com.levigo.jadice.server.nodes.StreamInputNode" id="node0">
   <property name="timeout">${timeout:6000}</property>
  </node>
  <node class="com.levigo.jadice.server.nodes.DynamicPipelineNode" id="node1">
   <property name="rulesetName">${rulesetName:default}</property>
   <property name="targetMimeType">${targetMimeType:application/pdf}</property>
   <property name="timeout">${timeout:6000}</property>
  </node>
  <node class="com.levigo.jadice.server.nodes.StreamOutputNode" id="node2">
   <property name="timeout">${timeout:6000}</property>
  </node>
 </nodes>
 <connections>
  <connect from="node0" to="node1" />
  <connect from="node1" to="node2" />
 </connections>
</job>
        

Wie man erkennen kann, ist ein Template in drei Blöcke gegliedert:

Sofern die einzelnen Nodes und deren Eigenschaften den Konventionen für java beans entsprechen, können die jeweiligen Eigenschaften hier einfach über deren Namen gesetzt werden. Außerdem ist es möglich, diese variabel zu machen, wie im obigen Beispiel zu sehen ist. Dies geschieht nach folgendem Muster: ${<Bezeichner>} oder ${<Bezeichner>:<Standardwert>}, wobei der Bezeichner zwingend mit einem Buchstaben beginnen muss und als weitere Zeichen Buchstaben, Ziffern, „_“ (Unterstrich), „-“ (Bindestrich) und „.“ (Punkt) haben darf.

Durch diesen Bezeichner können diese Werte beim SOAP-Aufruf als Eigenschaft (Element <property name="bezeichner">wert</property>) gesetzt bzw. überschrieben werden. Werden Variablen, die keinen Standardwert haben, nicht gesetzt, so führt dies beim Aufruf zu folgendem Fehler: com.thoughtworks.xstream.converters.ConversionException: Pattern refers to undefined variable <Bezeichner> for which there is no default

Die einzelnen Node-Elemente müssen eine für das jeweilige Template eindeutige ID einhalten. Durch diese werden sie im connections-Block zu einem Workflow verkettet.

Sollen über den SOAP-Aufruf, der zu diesem Template gehört, Daten vom Client zum Server übertragen werden, ist es notwendig, mindestens einen StreamInputNode zu definieren. Werden mehrere StreamInputNodes definiert, so müssen die einzelnen stream-Elemente in der SOAP-Anfrage den jeweils zutreffenden Node über das Attribut nodeId referenzieren. Dies entfällt, wenn es genau einen StreamInputNode gibt.

Die Datenströme, die aus StreamOutputNodes resultieren, werden als MTOM-Attachments in der SOAP-Antwort an den Client zurückgesendet. Dabei ist es auch möglich, mehrere StreamOutputNodes zu definieren. Dabei ist die Reihenfolge, in der die StreamOutputNodes abgefragt werden, um ihre Datenströme an die SOAP-Antwort anzuhängen, zufällig.

Um Job-Templates in eine SOAP-Anfrage einzubetten (siehe Abschnitt „Jobdefinition innerhalb der SOAP-Nachricht“), muss das Root-Element job entfernt werden; der Inhalt wird stattdessen an das Element configuration in der SOAP-Anfrage eingehängt. Das XML-Attributs type wird verwendet, um den Job-Typen so im Java-Code in Beispiel 6.2, „Job konfigurieren und ausführen“ zu deklarieren.