Kapitel 7. Webservice-Schnittstellen

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>
     <ws:job templateLocation="resource:/jobtemplates/x2pdf.xml">
      <ws:property name="dp.rulesetName">default</ws:property>
      <ws:property name="dp.targetMimeType">application/pdf</ws:property>
      <ws:property name="dp.timeout">8000</ws:property>
      <ws:stream mimeType="unknown/*" uuid="123456789" nodeId="node0">
       <ws:documentData>BASE64_encoded_data</ws:documentData>
      </ws:stream>
     </ws: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>
     <ws:job messageID="4711">
      <ws:configuration type="demultipexer example">
       <ws:nodes>
        <ws:node class="com.levigo.jadice.server.nodes.StreamInputNode" id="input1" />
        <ws:node class="com.levigo.jadice.server.nodes.StreamInputNode" id="input2" />
        <ws:node class="com.levigo.jadice.server.nodes.DemultiplexerNode" id="demux" />
        <ws:node class="com.levigo.jadice.server.nodes.StreamOutputNode" id="out" />
       </ws:nodes>
       <ws:connections>
        <ws:connect from="input1" to="demux" />
        <ws:connect from="input2" to="demux" />
        <ws:connect from="demux" to="out" />
       </ws:connections>
      </ws:configuration>
      <ws:stream nodeId="input1">
       <ws:documentData>BASE64_encoded_data</ws:documentData>
      </ws:stream>
      <ws:stream nodeId="input2">
       <ws:documentData>BASE64_encoded_data</ws:documentData>
      </ws:stream>
     </ws: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.

Im Lieferumfang des Java Development Kit (JDK) Version 1.7 befindet sich das Kommandozeilentool wsimport, mit dem Proxy-Klassen generiert werden können. Ist der Webservice von jadice server wie in Abschnitt „Konfiguration SOAP-Schnittstelle“ beschrieben aktiviert worden, werden mit folgendem Aufruf die notwenden Clientklassen erzeugt:

          <jdk1.7>\bin\wsimport http://localhost:9000/jadiceServer?wsdl -keep -extension 
        

Der Parameter -keep bewirkt, dass nicht nur die Klassen, sondern auch deren Quelltexte gespeichert werden. Zur weiteren Entwicklung empfehlt es sich, mit diesen weiter zu arbeiten. Abbildung 7.2, „Von JAX-WS generierte Klassen“ zeigt die generierten Klassen, die in die Entwicklungsumgebung eingebunden werden können.

Abbildung 7.2. Von JAX-WS generierte Klassen

Einstiegspunkte für eine Clientanwendung sind die Klassen JadiceServerJobInvoker und JobInvocationService, über die ein Zugriff auf die SOAP-Schnittstelle erfolgt, und die Klasse JobConfiguration über die der Aufruf konfiguriert wird. Eine minimale Implementierung kann so aussehen:

// Abstraction of the SOAP interface:
JadiceServerJobInvoker invoker = new JadiceServerJobInvoker();
JobInvocationService service = invoker.getJobInvocationServiceImplPort();

// Configuration of the job
JobConfiguration job = new JobConfiguration();
job.setTemplateLocation("resource:/jobtemplates/x2pdf.xml");

// Optional: Apply a property (e.g. a timeout)
Property timeout = new Property();
timeout.setName("timeout");
timeout.setValue("20000");
job.getProperty().add(timeout);

// Attach input data (if the template defines a StreamInputNode)
Stream inputStream = new Stream();
inputStream.setDocumentData(…);
job.getStream().add(inputStream);

// Submit the SOAP request (method is blocking!)
JobResult result = service.run(job);

// Retrieve result status
ResultStatus status = result.getStatus();

for (Log log : result.getLogEntry()) {
  // Evaluate log entries...
}

// Retrieve and handle result data
for (Stream stream : result.getStream()) {
  InputStream is = stream.getDocumentData().getInputStream();
  …      
}

Wenn die Security-Schnittstelle von jadice server wie in Abschnitt „Konfiguration Security-Schnittstelle“ beschrieben aktiviert ist, muss der clientseitige SOAP-Request um einen Security-Header erweitert werden. Folgendes Beispiel zeigt dies anhand der Java-WS Referenzimplementierung. Ein SOAPHandler erzeugt den benötigeten Security-Header:

public class SecurityHeaderSoapHandler implements SOAPHandler<SOAPMessageContext> {

  private static final String SOAP_HEADER_SECURITY_NAMESPACE //
    = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";
  private static final String SOAP_HEADER_USER_TOKEN_NAMESPACE //
    = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";
  private static final String SOAP_HEADER_PASSWORD_TYPE_NAMESPACE //
    = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText";

  @Override
  public boolean handleMessage(SOAPMessageContext context) {
    final Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
    if (outboundProperty.booleanValue()) {

      final SOAPMessage message = context.getMessage();
      try {

        SOAPEnvelope envelope = message.getSOAPPart().getEnvelope();
        SOAPHeader header = envelope.getHeader();

        SOAPElement security = header.addChildElement("Security", "wsse", SOAP_HEADER_SECURITY_NAMESPACE);

        SOAPElement usernameToken = security.addChildElement("UsernameToken", "wsse");
        usernameToken.addAttribute(new QName("xmlns:wsu"), SOAP_HEADER_USER_TOKEN_NAMESPACE);

        SOAPElement username = usernameToken.addChildElement("Username", "wsse");
        username.addTextNode("myUsername");

        SOAPElement password = usernameToken.addChildElement("Password", "wsse");
        password.setAttribute("Type", SOAP_HEADER_PASSWORD_TYPE_NAMESPACE);
        password.addTextNode("myPassword");
      } catch (Exception e) {
        // Causes the JAX-WS runtime to cease handler processing and generate a fault
        throw new RuntimeException("Cannot apply username token", e);
      }
    }
    return outboundProperty;
  }

Dieser Handler wird mittels eines HandlerResolvers dem Invoker gesetzt. Folgender Abschnitt des Client-Codes muss hierzu angepasst werden:

// Abstraction of the SOAP interface:
JadiceServerJobInvoker invoker = new JadiceServerJobInvoker();
invoker.setHandlerResolver(new HandlerResolver() {

  @Override
  public List<Handler> getHandlerChain(PortInfo portInfo) {
    List<Handler> handlerChain = new ArrayList<Handler>();

    SecurityHeaderSoapHandler securtiyHandler = new SecurityHeaderSoapHandler();

    handlerChain.add(securtiyHandler);

    return handlerChain;
  }
});
JobInvocationService service = invoker.getJobInvocationServiceImplPort();

Apache Axis2 ist unter http://axis.apache.org/axis2/java/core/ verfügbar und steht unter der Apache License. Ist der Webservice von jadice server wie in Abschnitt „Konfiguration SOAP-Schnittstelle“ beschrieben aktiviert worden, werden mit folgendem Aufruf die notwendigen Clientklassen erzeugt:

            <AXIS2_HOME>\bin\wsdl2java
  	        -o generatedCode
  	        -p com.levigo.jadice.server.ws.client.axis2.stub 
  	        -d jaxbri 
  	        -uri http://localhost:9000/jadiceServer?wsdl
        

Die Verwendung der Parameter -o für das Ausgabeverzeichnis und -p für den zu verwendenden Paketnamen sind optional. Der Parameter -d bestimmt, welches Databinding für die Wandlung nach / von XML verwendet werden soll. Standard ist das Apache Axis Data Binding (ADB). Dieses hat in der aktuellen Fassung jedoch Probleme mit der Deserialisierung von SOAP/MTOM-Attachments, sodass stattdessen auf die JAX-B Referenzimplemenentierung (jaxbri) zurückgegriffen werden sollte.

Einstiegspunkte für eine Clientanwendung sind die Klassen JadiceServerJobInvokerStub und Run, über die ein Zugriff auf die SOAP-Schnittstelle erfolgt, und die Klasse JobConfiguration, über die der Aufruf konfiguriert wird. Eine minimale Implementierung kann so aussehen:

// Abstraction of the SOAP interface:
JadiceServerJobInvokerStub invoker = new JadiceServerJobInvokerStub();

// Configuration of the job
JobConfiguration job = new JobConfiguration();
job.setTemplateLocation("resource:/jobtemplates/x2pdf.xml");

// Optional: Apply a property (e.g. a timeout)
Property timeout = new Property();
timeout.setName("timeout");
timeout.setValue("20000");
job.getProperty().add(timeout);

// Attach input data (if the template defines a StreamInputNode)
Stream inputStream = new Stream();
inputStream.setDocumentData(…);
job.getStream().add(inputStream);

// Configure the SOAP request
Run run = new Run();
run.setJob(job);

// Submit the SOAP request (method is blocking!)
RunResponse response = invoker.run(run);

// Retrieve the result object
JobResult result = response.getReturn();

// Retrieve result status
ResultStatus status = result.getStatus();

for (Log log : result.getLogEntry()) {
  // Evaluate log entries...
}

// Retrieve and handle result data
for (Stream stream : result.getStream()) {
  InputStream is = stream.getDocumentData().getInputStream();
  …      
}

Wenn die Security-Schnittstelle von jadice server wie in Abschnitt „Konfiguration Security-Schnittstelle“ beschrieben aktiviert ist, muss der clientseitige SOAP-Request um einen Security-Header erweitert werden. Folgendes Beispiel zeigt dies für Apache Axis2.

private static final String SOAP_HEADER_SECURITY_NAMESPACE = //
    "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";
private static final String SOAP_HEADER_USER_TOKEN_NAMESPACE = //
    "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";
private static final String SOAP_HEADER_PASSWORD_TYPE_NAMESPACE = //
    "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText";

private static OMElement createSecurityHeader() {
  OMFactory omFactory = OMAbstractFactory.getOMFactory();
  OMElement omSecurityElement = omFactory.createOMElement(new QName(SOAP_HEADER_SECURITY_NAMESPACE, "Security", "wsse"));
  omSecurityElement.addAttribute("mustUnderstand", "1", null);
  OMElement omUsertoken = omFactory.createOMElement(new QName(SOAP_HEADER_SECURITY_NAMESPACE, "UsernameToken", "wsse"));
  
  omUsertoken.declareNamespace(SOAP_HEADER_USER_TOKEN_NAMESPACE, "wsu");
  
  OMElement omUserName = omFactory.createOMElement(new QName(SOAP_HEADER_SECURITY_NAMESPACE, "Username", "wsse"));
  omUserName.setText("myUsername");
  
  OMElement omPassword = omFactory.createOMElement(new QName(SOAP_HEADER_SECURITY_NAMESPACE, "Password", "wsse"));
  omPassword.addAttribute("Type", SOAP_HEADER_PASSWORD_TYPE_NAMESPACE, null);
  omPassword.setText("myPassword");
  
  omUsertoken.addChild(omUserName);
  omUsertoken.addChild(omPassword);
  
  omSecurityElement.addChild(omUsertoken);
     
  return omSecurityElement;
}

Der erzeugte Header wird mit den folgenden Anpassungen des Webservice Client-Codes gesetzt und für jeden Webservice-Request verwendet:

// Abstraction of the SOAP interface:
JadiceServerJobInvokerStub invoker = new JadiceServerJobInvokerStub();
ServiceClient _stub = invoker._getServiceClient();
_stub.addHeader(createSecurityHeader());

Apache CXF ist unter http://cxf.apache.org/ verfügbar und steht unter der Apache License. Ist der Webservice von jadice server wie in Abschnitt „Konfiguration SOAP-Schnittstelle“ beschrieben aktiviert worden, werden mit folgendem Aufruf die notwendigen Clientklassen erzeugt:

            <CXF_HOME>\bin\wsdl2java
  	        -d generatedCode
  	        -p com.levigo.jadice.server.ws.client.cxf 
  	        http://localhost:9000/jadiceServer?wsdl
          

Die Verwendung der Parameter -d für das Ausgabeverzeichnis und -p für den zu verwendenden Paketnamen sind optional.

Einstiegspunkte für eine Clientanwendung sind die Klassen JadiceServerJobInvoker und Run, über die ein Zugriff auf die SOAP-Schnittstelle erfolgt, und die Klasse JobConfiguration, über die der Aufruf konfiguriert wird. Eine minimale Implementierung kann so aussehen:

// Abstraction of the SOAP interface:
JadiceServerJobInvoker invoker = new JadiceServerJobInvoker();
JobInvocationService service = invoker.getJobInvocationServiceImplPort();

// Configuration of the job
JobConfiguration job = new JobConfiguration();
job.setTemplateLocation("resource:/jobtemplates/x2pdf.xml");

// Optional: Apply a property (e.g. a timeout)
Property timeout = new Property();
timeout.setName("timeout");
timeout.setValue("20000");
job.getProperty().add(timeout);

// Attach input data (if the template defines a StreamInputNode)
Stream inputStream = new Stream();
inputStream.setDocumentData(…);
job.getStream().add(inputStream);

Run run = new Run();
run.setJob(job);

// Submit the SOAP request (method is blocking!)
RunResponse response = service.run(run);

// Retrieve the result object
JobResult result = response.getReturn();

// Retrieve result status
ResultStatus status = result.getStatus();

for (Log log : result.getLogEntry()) {
  // Evaluate log entries...
}

// Retrieve and handle result data
for (Stream stream : result.getStream()) {
  InputStream is = stream.getDocumentData().getInputStream();
  …      
}

Wenn die Security-Schnittstelle von jadice server wie in Abschnitt „Konfiguration Security-Schnittstelle“ beschrieben aktiviert ist, muss der clientseitige SOAP-Request um einen Security-Header erweitert werden. Hierbei kann die gleiche Syntax wie bei der JAX-WS Referenzimplementierung verwendet werden, siehe „JAX-WS Referenzimplemenentierung“