wsclient library: webservice converter

How does the conversion of various formats with the webPDF wsclient library work? Here we want to introduce the operation of the webPDF Webservices Converter in detail and show how you can best use it with the help of the webPDF wsclient library.

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Start with a REST or SOAP session

We assume that you have already created a REST or SOAP session as preparation and can therefore create either a ConverterWebService object (for a SOAP session) by calling the WebserviceFactory:

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

..or which can create a ConverterRestWebService object (for a REST session):

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

Now either a RestDocument or a SoapDocument object is passed to this WebService object by calling the method setDocument().

Description of the Converter Webservice

The Converter Webservice is an endpoint of your webPDF server that allows you to convert various formats to PDF. You can reinitialize the ConverterType converter operation and set it in the webservice or use the automatically generated instance of the webservice.

ConverterType converterType=converterWebService.getOperation();

The following parameters can be set for the ConverterType instance:

pages (default value: “”)

Specifies the page range to output for the conversion result. You can specify either a single page (“1”), a list of pages (“1,3,5”), a page range (“1-5”), or a combination of these elements (“1,3-5,6”). All pages of the document can be selected using “*”.

converterType.setPages("*");

accessPassword (default value: “”)

This parameter can be used to specify a password that will be used to open the source document if it is protected.

converterType.setAccessPassword("password");

compression(Default value: true)

Determines whether all data objects in the result PDF should be compressed. This reduces the size of the document.

converterType.setCompression(true);

compression(default value: true)

Determines whether all data objects in the result PDF should be compressed. This reduces the size of the document.

converterType.setCompression(true);

dpi (default value: 300)

Specifies the DPI resolution (points per inch) for the document to be generated.

converterType.setDpi(300);

embedFonts (default value: false)

This parameter can be used to specify whether the original fonts are to be included in the document. If these are not available on the server, replacement fonts may be included. If it is intended to create a PDF/A document, the parameter should not be set (otherwise it will be set automatically).

converterType.setEmbedFonts(true);

jpegQuality (default value: 90)

This parameter can be used to specify the desired quality for JPEG graphics as a percentage of the document to be generated.

converterType.setJpegQuality(90);

fileExtension (default value: “”)

With this parameter the automatic recognition of the file format of webPDF can be bypassed. The parameter should only be used in rare exceptional cases. The automatic recognition of webPDF usually recognizes the file format and processes it accordingly.

converterType.setFileExtension("xml")

The object “html”

In this object, settings are set that are relevant for the conversion of HTML and HTML-based documents (such as e-mails).

ConverterHtmlType html=new ConverterHtmlType();
converterType.setHtml(html);

adjustFonts (default value: false)

Automatically changes the font information in HTML-based documents from “Arial”, “Helvetica” and “Sans-Serif” in the generated PDF document to “Arial Unicode MS”. This improves the font image in the PDF output.

html.setAdjustFonts(true);

baseURL (default value: “”)

This parameter can be used to define the basis for all URLs contained in HTML that are not absolute.

html.setBaseURL("https://www.webpdf.de/");

downloadImages (default value: false)

With this parameter you can specify that all images of the HTML content should be downloaded.

html.setDownloadImages(true);

The object “mail”

Settings that are relevant for the conversion of mail documents are set in this object.

ConverterMailType mail=new ConverterMailType();
converterType.setMail(mail);

adjustFonts (default value: false)

Automatically changes the font information in the mail document from “Arial”, “Helvetica” and “Sans-Serif” in the created PDF document to “Arial Unicode MS”. This improves the font image in the PDF output.

mail.setAdjustFonts(true);

attachmentMode (default value: embed)

Specifies how the attachments of emails are handled. AttachmentModeType.EMBED ensures that attachments are embedded in the PDF document. AttachmentModeType.REMOVE ensures that attachments are not included in the PDF document.

mail.setAttachmentMode(AttachmentModeType.EMBED);

downloadImages (default value: false)

With this parameter you can specify that all images of the HTML content of the email should be downloaded.

mail.setDownloadImages(true);

The object “officeBridge”

Adding an object of this type specifies that the Office Bridge is to be used for the conversion. When this is set up, Word, Excel, and PowerPoint documents are converted using it.

converterType.setOfficeBridge(new OfficeBridgeType());

The sharePointBridge Object

If the SharePointBridge is activated, setting an object of this type determines that a Word document is to be converted via a SharePoint service.

converterType.setSharePointBridge(new SharePointBridgeType());

The object “page”

Objects of this type can be used to specify the page format to be generated.

PageType page=new PageType();
converterType.setPage(page);

• bottom (default value: 20)
• top (default value: 20)
• left (default value: 20)
• right (default value: 20)

Defines the margins of the PDF document. The value refers to the unit defined with “metrics” (millimeters by default).

page.setTop(20);
page.setBottom(20);
page.setLeft(20);
page.setRight(20);

• height (default value: 297)
• width (default value: 210)

The parameters can be used to specify the page height and width of the PDF document. The value refers in each case to the unit defined with “metrics” (by default millimeters).

page.setHeight(297);
page.setWidth(210);

metrics(default value: mm)

Specifies the unit of measurement to be used for the object settings. The default unit of measurement is millimeters with MetricsType.MM. Alternatively, the unit pixel can be set with MetricsType.PX.

page.setMetrics(MetricsType.MM);

The “pdfa” object

Direct conversion to PDF/A is set up using an object of this type. All properties to be set can be found in the webPDF documentation and in the article on using the Pdfa webservice with wsclient.

PdfaType pdfa=new PdfaType();
converterType.setPdfa(pdfa);

The object “signature”

Signatures can be added to the result document using an object of this type. All properties to be set can be found in the webPDF documentation and in the article about using the Signature webservice with wsclient.

SignatureType signature = new SignatureType();
converterType.setSignature(signature);

The report object

An object of this type enables extended error reporting for text-based documents.

ConverterReportType report = new ConverterReportType();
converterType.setReport(report);

contentProblems (default value: false)

Triggers the specific error ERR_CONVERTER_CONTENT_PROBLEMS for problems with the file content.

report.setContentProblems(true);

fontAliasUsage (default value: false)

If a font does not exist and a replacement font is used, the specific error ERR_CONVERTER_FONT_ALIAS_USED is triggered.

report.setFontAliasUsage(true);

fontIsMissing (default value: false)

If a font does not exist, triggers the specific error ERR_CONVERTER_FONT_IS_MISSING.

report.setFontIsMissing(true);

The object “template”

Allows you to define settings for file formats that require a template for conversion.

ConverterTemplateType template = new ConverterTemplateType();
converterType.setTemplate(template);

language (default value “”)

Sets the language code to load a localized template.

template.setLanguage("de");

Example for webservice call (for addressing the SOAP interface):

try (
    // Establishing a session with the webPDF Server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Retrieving the document to be processed
    // and the file to 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 webservice via a factory:
    ConverterWebService converterWebService = WebServiceFactory.createInstance(session, WebServiceType.CONVERTER);
    converterWebService.setDocument(soapDocument);

    // Object-oriented parameterization of the call:
    ConverterType converterOperation = converterWebService.getOperation();
    
    PageType page = new PageType();
    converterOperation.setPage(page);
    page.setHeight(100);
    page.setWidth(300);
    
    // Execution.
    converterWebService.process();
} catch (ResultException | MalformedURLException ex) {
    
    // To evaluate possible errors that may have occurred, the
    // wsclient library provides appropriate methods:
}

More coding examples for webservices that you can use with the ws-client library can be found here.