Use of the REST 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 REST 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 SOAP interface can be found here:

Use of the SOAP interface via webPDF wsclient

The first REST web service call​

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

All REST 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 RestSession​

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

RestSession session = SessionFactory.createInstance(
    WebServiceProtocol.REST,
    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.

Login and source document selection​

If we call a webPDF web service, we usually want to process a source document and create a result document from it. First, the source document has to be uploaded to the server and made available for processing.

We first log in to the webPDF server by calling the login() method on our RestSession object.

In the next step, we use getDocumentManager() to retrieve the DocumentManager from our RestSession and then upload the source file via uploadDocument().

The resulting RestDocument manages access to the uploaded document.

session.login();
RestDocument sourceDocument =
    session.getDocumentManager()
        .uploadDocument(
            new File("Path of the source document")
        );

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 RestSession object.

In our example, we select WebServiceType.CONVERTER.

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

The next step is to assign the uploaded source document to the web service call.

converterWebService.setDocument(sourceDocument);

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

We can now execute the operation by calling process(). If execution is successful, the result is returned as a RestDocument.

Just like the uploaded source document, this RestDocument manages access to a document stored on the webPDF server.

To retrieve the result, we download the document via downloadDocument() and write it to an output stream, for example to a file:

RestDocument resultDocument = converterWebService.process();
try (FileOutputStream outputStream =
         new FileOutputStream(new File("Path of the target document"))) {
    resultDocument.downloadDocument(outputStream);
}

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 (
    RestSession session = SessionFactory.createInstance(
        WebServiceProtocol.REST,
        new URL("https://localhost:8080/webPDF/")
    )
) {
    session.login();

    RestDocument sourceDocument = session.getDocumentManager().uploadDocument(
        new File("Path of the source document")
    );

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

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

    RestDocument resultDocument = converterWebService.process();

    try (FileOutputStream outputStream =
             new FileOutputStream(new File("Path of the target document"))) {
        resultDocument.downloadDocument(outputStream);
    }
} 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