Webservice PDF/A

In this coding eexample we would like to introduce you to the operation of the webPDF webservice pdfa and how you can 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

Call webservice

To call the webservice, you should have already created a REST or SOAP session and be able to create either a PdfaWebService object (for a SOAP session) by calling the WebServiceFactory:

PdfaWebService pdfaWebService= WebServiceFactory.createInstance(session, WebServiceType.PDFA);

..or a PdfaRestWebService object (for a REST session):

PdfaRestWebService pdfaWebService= WebServiceFactory.createInstance(session, WebServiceType.PDFA);

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

The pdfa webservice

The pdfa Webservice is an endpoint of your webPDF server that enables the conversion of PDF documents into PDF/A formats and their validation.

The Pdfa operation of type PdfaType can be reinitialized and set in the webservice or you can use the automatically generated instance of the webservice.

PdfaType pdfaType=pdfaWebService.getOperation();

The following parameters can be set for the ConverterType instance:

The object „convert“

All settings for a conversion to PDF/A are set in this object.

PdfaType.Convert convert = new PdfaType.Convert();
pdfaType.setConvert(convert);

level (default value: „1b“)

Specifies the desired level of conformity for PDF/A creation (according to ISO 19005).

• 1a = PDF/A-1a
• 1b = PDF/A-1b
• 2a = PDF/A-2a
• 2b = PDF/A-2b
• 2u = PDF/A-2u
• 3a = PDF/A-3a
• 3b = PDF/A-3b
• 3u = PDF/A-3u

convert.setLevel("3b");

imageQuality (Default value: 75)

This parameter sets the quality for images that need to be converted during conversion because they do not use allowed compression (e.g. JPX is not allowed in PDF/A-1). Values in the range from 1 to 100 are allowed, where a higher value means better quality, but also larger PDF documents.

convert.setImageQuality(90);

errorReport (default value: „none“)

This parameter uses a field of the enum type PdfaErrorReportType to determine whether and in what form the XML report for a failed conversion is returned.

• PdfaErrorReportType.NONE = XML report not returned
• PdfaErrorReportType.MESSAGE = XML report delivered as part of error message
• PdfaErrorReportType.FILE = XML report is saved to file

convert.setErrorReport(PdfaErrorReportType.MESSAGE);

successReport (default value: „none“)

This parameter uses a field of the enum type PdfaSuccessReportType to determine whether and in what form the XML report is returned for successful conversion.

• PdfaSuccessReportType.NONE = XML report not returned
• PdfaSuccessReportType.LINKED = XML report is attached to the end of the PDF/A document (XML must be removed from the PDF document after reading).
• PdfaSuccessReportType.ZIP = PDF/A document and XML report are packed together in a ZIP archive.

convert.setSuccessReport(PdfaSuccessReportType.NONE);

The object „zugferd“

With this area you can optionally include a ZUGFeRD document which must be converted at least to PDF/A-3a level.

ZugferdType zugferd = new ZugferdType();
convert.setZugferd(zugferd);

The Object „xmlFile“

ZUGFeRD file as “Base64 encoded”. The file is validated against the ZUGFeRD XSD schema before embedding. If it is not valid, the process is aborted. An object of type ZugferdFileDataType is filled with an object of type FileDataSourceType which contains the Base64 encoded XML data and passed to the object of type ZugferdType.

ZugferdFileDataType zugferdFileData = new ZugferdFileDataType();
FileDataSourceType fileDataSource = FileDataSourceType
        .fromValue(Base64.encodeBase64String(FileUtils.readFileToByteArray(zugferdXmlFile)));
zugferdFileData.setSource(fileDataSource);
zugferd.setXmlFile(zugferdFileData);

The object „analyze“

Operation Object for checking the PDF/A conformity of a document.

PdfaType.Analyze analyze = new PdfaType.Analyze();
pdfaType.setAnalyze(analyze);

level (default value: „1b“)

PDF/A level for which the conformity is to be checked.

analyze.setLevel("3b");

Example for a 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/")
    );
    // Retrieve 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 to the target document")
    )
) {
    // Selection of the webservice via a factory:
    PdfaWebService pdfaWebService = WebServiceFactory.createInstance(session, WebServiceType.PDFA);
    pdfaWebService.setDocument(soapDocument);

    // Object-oriented parameterization of the call:
    PdfaType pdfaType = pdfaWebService.getOperation();

    PdfaType.Convert convert=new PdfaType.Convert();
    pdfaType.setConvert(convert);        
    convert.setLevel("3b");        
    convert.setSuccessReport(PdfaSuccessReportType.NONE);        
    convert.setErrorReport(PdfaErrorReportType.FILE);        
    convert.setImageQuality(90);

    // Execution.
    pdfaWebService.process();
} catch (ResultException | MalformedURLException ex) {

    // To evaluate possible errors that may have occurred, the
    // wsclient library provides appropriate methods:
}

Note: The parameters are of course also documented in our user manual.

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