Use of the SOAP interface via webPDF wsclient

In this article we would like to show you how you can use the “webPDF wsclient” library (short “wsclient”) in Java to access the webPDF webservices via the SOAP interface. For this it is helpful if you have already read the article “The webPDF wsclient Library“.

An article explaining the use of the REST interface can be found here:

Using the REST interface with webPDF wsclient

The First SOAP Webservice Call

In the following example we would like to deal with the basic call of a webPDF SOAP webservice via “wsclient”, before we will discuss the individual webservices ourselves in further contributions.

The call of all SOAP webservices via “wsclient” follows the pattern presented here. In this example we would like to call the “Converter” Webservice as an example, which is only to serve as a placeholder for all other webPDF webservices. All of the classes used here are made available via “wsclient” without any further preparatory work being necessary.

Connecting via SoapSession

First the connection to the webPDF server has to be established and a session has to be created, for this we instantiate a SoapSession object via the SessionFactory. For the instantiation we select the WebServiceProtocol SOAP and pass the URL (and the port) on which our webPDF server is accessible.

SoapSession session = SessionFactory.createInstance(
   WebServiceProtocol.SOAP,
   new URL("https://localhost:8080/webPDF/")
);

Please note that this session is closed at the end with “session.close()” or is included in a “try-with-resources” statement starting with Java 7.

Selection of source and target document

If we call a webPDF webservice, we usually want to process a certain source document and create a target document with it. The selection of source and target document is done via a SoapDocument object. We transfer both source and target to this object in the constructor, which offers us two variants.

Either we pass a resource directly as the source document that can be found via a URI and a file for the target document in which the work result is to be written.

Or we pass an InputStream as the source document, which holds the document to be processed and an OutputStream, into which the work result is to be written.

In this example we assume that we have the source document as a file and we want to write the work result to a specific file.

SoapDocument soapDocument = new SoapDocument(
   new File("Path of the source document").toURI(),
   new File("Path of the target document")
)

Please note that the SoapDocument object should always be closed at the end.

Selection and configuration of the webservice

We prepare the call of the desired webservice with the help of WebServiceFactory. This allows the selection of the webservice by means of the Enumeration WebServiceType and requests from us the already created SoapSession object.

In our example we select the WebServiceType.CONVERTER.

ConverterWebService converterWebService =
   WebServiceFactory.createInstance(
   session, WebServiceType.CONVERTER
);

Next, our webservice call must be provided with source and target documents, which we do via a corresponding setter, since we have already created the SoapDocument object required for this.

converterWebService.setDocument(soapDocument);

The last thing missing from our call is the parameterization of the webservice call. This is bundled in an object that can be retrieved via the getOperation() method at our SoapSession. The type of this object corresponds to our selected webservice and only provides us with its relevant parameters for modification and retrieval.

The parameters that we pass here directly influence the result and the execution of the operation that we want to trigger. For example, the quality of the images in the result document. Which parameters these are depends on the respective webservice and can be found in the webPDF documentation.

Since we want to discuss the converter in more detail in a later article, the only relevant thing for us here is that we can set all relevant parameters on this object. For example, we configure the following two parameters:

converterWebService.getOperation().setJpegQuality(100);
converterWebService.getOperation().setDpi(300);

Execution, evaluation and deregistration

We can now finally execute the operation by calling the process() method. If the execution was successful, the work result is written directly to the target selected in the SOAPDocument.

converterWebService.process();

If an error occurred during execution, we can (must) catch it as ResultException in a catch block and get access to the wsclient error number and (if available) the underlying error on the webPDF server side via this caught exception.

The result

The overall result is therefore as follows:

try (
    // Setup of a session with the webPDF server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Make available the document that is to be processed.
    // and the file in which the result is to be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    // Selection of the web service via a factory:
    ConverterWebService converterWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.CONVERTER
        );
    converterWebService.setDocument(soapDocument);
    // Object-oriented parameterization of the call:
    converterWebService.getOperation().setJpegQuality(100);
    converterWebService.getOperation().setDpi(300);
    // Execution.
    converterWebService.process();
} catch (ResultException ex) {
    // To evaluate possible errors that may have occurred, the
    // wsclient library appropriate methods are available:
    int webPDFErrorCode = ex.getResult().getCode();
    Exception exception = ex.getResult().getException();
}

The parameters of the individual webservices will be discussed in detail in later articles, you will find a documentation of all webPDF parameters in our parameter documentation.

A documentation of the error numbers of the webPDF wsclient library can be found here: https://github.com/softvision-dev/webpdf-wsclient/wiki/Error-Codes