Use of the REST 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 REST interface. For this it is helpful if you have already read the article “The webPDF 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 Webservice call

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

The call of all REST webservices via “wsclient” is done according to 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 RestSession

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

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

Login and source document selection

If we call a webPDF webservice, we usually want to process a certain source document and create a target document with it. First we have to make the source document known to the server and make it available for processing.

First we connect to the webPDF server by calling the method login() at our RestSession object.

In the next step we use the method getDocumentManager() to retrieve the DocumentManager object from our RestSession and finally upload our source file to the webPDF server using the method uploadDocument().

The resulting RestDocument handles all accesses to the document we just uploaded.

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 webservice with the help of WebServiceFactory. The WebServiceFactory allows the selection of the webservice by means of the Enumeration WebServiceType and requests from us the already created RestSession object.

In our example we select the WebServiceType.CONVERTER.

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

The next step is to make the source document known to our webservice call, which we have already uploaded in the previous step.

converterWebService.setDocument(sourceDocument);

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 RestSession. 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 returned to us in the form of a RestDocument object.

Analogous to the RestDocument that we created by uploading our source document, this also manages the access to a document that is stored on the webPDF server.

In order to get the result of our work, we download the document by calling the method downloadDocument() and write it into a suitable output stream of our choice (here for example into a file):

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

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 REST session with the webPDF server:
    RestSession session = SessionFactory.createInstance(
        WebServiceProtocol.REST,
        new URL("https://localhost:8080/webPDF/")
    );
) {
    // Login at the webPDF Server
    session.login();
    // Make available the document to be processed.
    RestDocument sourceDocument =
        //Retrieval of the DocumentManager at the session.
        session.getDocumentManager()
            //Upload of the source document to the webPDF server
            .uploadDocument(
                new File("Path of the source document")
            );
    // Selection of the webservice via a factory:
    ConverterRestWebService converterWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.CONVERTER
        );
    converterWebService.setDocument(sourceDocument);
    // Object-oriented parameterization of the call:
    converterWebService.getOperation().setJpegQuality(100);
    converterWebService.getOperation().setDpi(300);
    // Execution and retrieval of the target document.
    RestDocument resultDocument = converterWebService.process();
    // Download our work results
    try (FileOutputStream outputStream =
             new FileOutputStream(new File("Path of the target document"))
    ) {
        session.getDocumentManager()
            .downloadDocument(resultDocument, outputStream);
    }
} catch (ResultException ex) {
    // To evaluate possible errors that may have occurred, the
    // wsclient library provides corresponding methods:
    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