Use of the SOAP interface via webPDF wsclient

Minimum technical requirements​

• Java version: 7
• webPDF version: 7
• wsclient version: 1

In this article, we show how to use the webPDF wsclient library in Java to access webPDF web services via the SOAP interface.

If you have not already done so, it is helpful to start with the introductory article: webPDF and Java: very easy with the wsclient library

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

Use of the REST interface via webPDF wsclient

The first SOAP web service call​

In the following example, we look at the basic call of a webPDF SOAP web service via wsclient. The individual web services themselves are covered in more detail in later articles.

All SOAP web services can be called via wsclient according to the pattern presented here. In this example, we use the Converter web service as a representative example for other webPDF web services. All classes used here are provided directly by wsclient.

Connecting via SoapSession​

First, the connection to the webPDF server must be established and a session created. To do this, we instantiate a SoapSession object via the SessionFactory. We select the WebServiceProtocol.SOAP protocol and pass the URL of the webPDF server.

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

Important: The session should be closed again at the end, for example by calling session.close() or by using try-with-resources.

Selection of source and target document​

If we call a webPDF web service, we usually want to process a source document and create a target document from it. Source and target are defined via a SoapDocument.

Either we pass a source resource that can be addressed via a URI and a target file into which the result should be written.

Or we pass an InputStream as the source document and an OutputStream for the result.

In this example, we assume that the source document is available as a file and the result should be written to a specific file.

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

Important: The SoapDocument object should also always be closed at the end.

Selection and configuration of the webservice​

We prepare the call of the desired web service with the help of WebServiceFactory. It selects the web service via the WebServiceType enum and expects the already created SoapSession object.

In our example, we select WebServiceType.CONVERTER.

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

Next, the web service call must be provided with the source and target document via the corresponding setter.

converterWebService.setDocument(soapDocument);

The last missing piece is the parameterization of the web service call. This is bundled in an object that can be accessed via getOperation(). Its type matches the selected web service and exposes only the relevant parameters.

The parameters influence both the result and the execution of the operation. For example, they can control the image quality in the result document. Which parameters are available depends on the selected web service and is described in the webPDF parameter documentation.

Since the converter itself is explained in more detail in a later article, the only important point here is that all relevant parameters can be set on this object. For example:

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

Execution, evaluation and deregistration​

We can now execute the operation by calling process(). If execution is successful, the result is written directly to the target defined in the SoapDocument.

converterWebService.process();

If an error occurs during execution, it should be caught as a ResultException. This exception gives access to the wsclient error number and, if available, the underlying server-side error.

The result​

The overall example then looks as follows:

try (
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    ConverterWebService converterWebService =
        WebServiceFactory.createInstance(session, WebServiceType.CONVERTER);

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

    converterWebService.process();
} catch (ResultException ex) {
    // error handling
}

The parameters of the individual web services are discussed in detail in later articles. You can find an overview of all parameters in the parameter documentation.

Documentation of the webPDF wsclient error codes can be found here:

• wsclient error codes on GitHub