Chapter 7. Webservice Interfaces

An XML-coded job description can be stored on the server so that the client can refer to it in its SOAP request and thus the job does not have to be configured during the processing time.

The structure of the message will be explicated with the following example:

  <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>
          

Beside the pre-defined elements for header and body in SOAP messages, the specific element run addresses the method run which is offered by the webservice.

This method defines a job (see Chapter 4, System Architecture) which is pre-defined by a template (see the section called “Definition of Job Templates”). The location of the corresponding template on the server is given by the attribute templateLocation. If variables are defined in the template, they can be configured (i. e. their default values can be overwritten) with the help of property elements. The attribute messageID is optional. The client can freely assign it and it will then be adopted in the server's reply.

Data streams which are to be processed are referenced with the help of stream elements in the SOAP message. Information about the individual ID (uuid) and the MIME type are optional. If the MIME type is unknown but specified in the message, unknown/* should be used.

If multiple StreamInputNodes are defined in the template file, you need to clearly allocate which data stream should be sent to which StreamInputNode. This allocation is realized through the nodeId attribute which refers to the ID assigned to the StreamInputNode within the template (attribute id).

The actual data can be assigned as BASE64-coded data stream with the tag documentData or referenced in a multipart/related container which features the CID (contentID) specified here if the MTOM feature is activated.

If the client is not supposed to use a job configuration pre-defined on the server, it is possible to incorporate this configuration in the SOAP request. The format used is similar to the one in a separate job template (see the section called “Definition of Job Templates”). Instead of the root element job, the definition is embedded in the SOAP request as a configuration element.

The following example illustrates this:

  <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 this example two StreamInputNodes are connected through a DemultiplexerNode and the input data is returned to the client without changes.

The definition of the Nodes and their designated workflow graph is described in the configuration block.

Furthermore, this example shows how to connect specific input streams to a StreamInputNode: The first document is connected to the first StreamInputNode (nodeId input1) and the second document to the second StreamInputNode (nodeId input2).

The distribution package of Java Development Kit (JDK) Version 1.7 contains the command line tool wsimport with which proxy classes can be generated. If the webservice of jadice server has been activated as described in the section called “Configuring the SOAP Interface”, the necessary client classes are generated with the following command:

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

The parameter -keep effectuates that not only classes but also their source codes are saved. We recommend to work with these in further development. Figure 7.2, “Classes generated by JAX-WS” shows the generated classes which can be incorporated into the developing environment.

Figure 7.2. Classes generated by JAX-WS

The classes JadiceServerJobInvoker and JobInvocationService are entry points for a client application since they enable access to the SOAP interface. Another essential class is JobConfiguration with which the request is configured. A minimal implementation can look as follows:

// 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();
  …      
}

If the security interface of jadice server has been activated as described in the section called “Configuring the Security Interface”, a security header has to be added to the SOAP request on the client's side. The following example shows this with the help of the JAVA-WS reference implementation. A SOAPHandler generates the necessary 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;
  }

This handler is assigned to the invoker with the help of a HandlerResolver. In order to assign the handler, the following segment of the client code needs to be adjusted:

// 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 is available under Apache License under http://axis.apache.org/axis2/java/core/. If the webservice of jadice server has been activated as described in section the section called “Configuring the SOAP Interface”, the necessary client classes are generated with the following command:

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

The use of the parameters -o for the output directory and -p for the designated package name are optional. The parameter -d determines which data binding shall be used for the conversion from / to XML. The Apache Axis Data Binding (ADB) is the default binding. However, in its current version it struggles with the deserialization of SOAP/MTOM attachments, which is why we recommend using the JAX-B reference implementation (jaxbri) instead.

The classes JadiceServerJobInvokerStub and Run are entry points for a client application since they enable access to the SOAP interface. Another essential class is JobConfiguration with which the request is configured. A minimal implementation can look as follows:

// 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();
  …      
}

If the security interface of jadice server has been activated as described in the section called “Configuring the Security Interface”, a security header has to be added to the SOAP request on the client side. The following example shows this implementation by way of 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;
}

The generated header is assigned to be used for each webservice request with the help of the following adjustments to the webservice code on the client side:

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

Apache CXF is available at http://cxf.apache.org/ and is under Apache License. If the webservice of jadice server has been activated as described in the section called “Configuring the SOAP Interface”, the following command generates the necessary client classes:

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

Using the parameters -d for the output directory and -p for the package name to be used are optional.

The classes JadiceServerJobInvoker and Run are entry points for a client application since they enable the access to the SOAP interface. The class JobConfiguration is also essential as the request is configured with its help. A minimal implementation solution can look as follows:

// 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();
  …      
}

If the security interface of jadice server has been activated as described in the section called “Configuring the Security Interface”, a security header has to be added to the SOAP request on the client side. In order to do so, you can use the same syntax as in the JAX-WS reference implementation, see the section called “JAX-WS Reference Implementation”